diff --git a/postfix/.indent.pro b/postfix/.indent.pro
index 06435a2a6..0b5723cf5 100644
--- a/postfix/.indent.pro
+++ b/postfix/.indent.pro
@@ -223,6 +223,7 @@
-TMVECT
-TMYSQL
-TMYSQL_NAME
+-TMYSQL_RES
-TNAMADR_LIST
-TNAME_ASSIGNMENT
-TNAME_CODE
diff --git a/postfix/HISTORY b/postfix/HISTORY
index 0e536cc79..d4c6b7d65 100644
--- a/postfix/HISTORY
+++ b/postfix/HISTORY
@@ -22702,3 +22702,11 @@ Apologies for any names omitted.
Cleanup: simplified code structure in the MySQL client
support for stored procedures. File: global/dict_mysql.c.
+
+20161226
+
+ Cleanup: more MySQL client code simplification, better error
+ messages, new per-database "require_result_set" parameter
+ (default: yes) which can be set to "no" to avoid the need
+ for dummy SELECT statements in stored procedures. Files:
+ global/dict_mysql.c, proto/mysql_table, postconf/postconf_dbms.c.
diff --git a/postfix/html/mysql_table.5.html b/postfix/html/mysql_table.5.html
index ba5c7632b..e066bc88c 100644
--- a/postfix/html/mysql_table.5.html
+++ b/postfix/html/mysql_table.5.html
@@ -101,47 +101,52 @@ MYSQL_TABLE(5) MYSQL_TABLE(5)
a substitute for the address Postfix is trying to resolve, e.g.
query = SELECT replacement FROM aliases WHERE mailbox = '%s'
+ By default, every query must return a result set (instead of
+ storing its results in a table); with "require_result_set = no"
+ (Postfix 3.2 and later), the absence of a result set is treated
+ as "not found".
+
This parameter supports the following '%' expansions:
%% This is replaced by a literal '%' character.
- %s This is replaced by the input key. SQL quoting is used
- to make sure that the input key does not add unexpected
+ %s This is replaced by the input key. SQL quoting is used
+ to make sure that the input key does not add unexpected
metacharacters.
%u When the input key is an address of the form user@domain,
- %u is replaced by the SQL quoted local part of the
- address. Otherwise, %u is replaced by the entire search
- string. If the localpart is empty, the query is sup-
+ %u is replaced by the SQL quoted local part of the
+ address. Otherwise, %u is replaced by the entire search
+ string. If the localpart is empty, the query is sup-
pressed and returns no results.
%d When the input key is an address of the form user@domain,
- %d is replaced by the SQL quoted domain part of the
- address. Otherwise, the query is suppressed and returns
+ %d is replaced by the SQL quoted domain part of the
+ address. Otherwise, the query is suppressed and returns
no results.
%[SUD] The upper-case equivalents of the above expansions behave
- in the query parameter identically to their lower-case
- counter-parts. With the result_format parameter (see
- below), they expand the input key rather than the result
+ in the query parameter identically to their lower-case
+ counter-parts. With the result_format parameter (see
+ below), they expand the input key rather than the result
value.
- %[1-9] The patterns %1, %2, ... %9 are replaced by the corre-
- sponding most significant component of the input key's
- domain. If the input key is user@mail.example.com, then
+ %[1-9] The patterns %1, %2, ... %9 are replaced by the corre-
+ sponding most significant component of the input key's
+ domain. If the input key is user@mail.example.com, then
%1 is com, %2 is example and %3 is mail. If the input key
- is unqualified or does not have enough domain components
- to satisfy all the specified patterns, the query is sup-
+ is unqualified or does not have enough domain components
+ to satisfy all the specified patterns, the query is sup-
pressed and returns no results.
- The domain parameter described below limits the input keys to
- addresses in matching domains. When the domain parameter is
+ The domain parameter described below limits the input keys to
+ addresses in matching domains. When the domain parameter is
non-empty, SQL queries for unqualified addresses or addresses in
non-matching domains are suppressed and return no results.
- This parameter is available with Postfix 2.2. In prior releases
- the SQL query was built from the separate parameters:
- select_field, table, where_field and additional_conditions. The
+ This parameter is available with Postfix 2.2. In prior releases
+ the SQL query was built from the separate parameters:
+ select_field, table, where_field and additional_conditions. The
mapping from the old parameters to the equivalent query is:
SELECT [select_field]
@@ -149,50 +154,50 @@ MYSQL_TABLE(5) MYSQL_TABLE(5)
WHERE [where_field] = '%s'
[additional_conditions]
- The '%s' in the WHERE clause expands to the escaped search
- string. With Postfix 2.2 these legacy parameters are used if
+ The '%s' in the WHERE clause expands to the escaped search
+ string. With Postfix 2.2 these legacy parameters are used if
the query parameter is not specified.
NOTE: DO NOT put quotes around the query parameter.
result_format (default: %s)
Format template applied to result attributes. Most commonly used
- to append (or prepend) text to the result. This parameter sup-
+ to append (or prepend) text to the result. This parameter sup-
ports the following '%' expansions:
%% This is replaced by a literal '%' character.
- %s This is replaced by the value of the result attribute.
+ %s This is replaced by the value of the result attribute.
When result is empty it is skipped.
%u When the result attribute value is an address of the form
- user@domain, %u is replaced by the local part of the
- address. When the result has an empty localpart it is
+ user@domain, %u is replaced by the local part of the
+ address. When the result has an empty localpart it is
skipped.
- %d When a result attribute value is an address of the form
- user@domain, %d is replaced by the domain part of the
- attribute value. When the result is unqualified it is
+ %d When a result attribute value is an address of the form
+ user@domain, %d is replaced by the domain part of the
+ attribute value. When the result is unqualified it is
skipped.
%[SUD1-9]
- The upper-case and decimal digit expansions interpolate
- the parts of the input key rather than the result. Their
- behavior is identical to that described with query, and
- in fact because the input key is known in advance,
- queries whose key does not contain all the information
- specified in the result template are suppressed and
+ The upper-case and decimal digit expansions interpolate
+ the parts of the input key rather than the result. Their
+ behavior is identical to that described with query, and
+ in fact because the input key is known in advance,
+ queries whose key does not contain all the information
+ specified in the result template are suppressed and
return no results.
For example, using "result_format = smtp:[%s]" allows one to use
a mailHost attribute as the basis of a transport(5) table. After
- applying the result format, multiple values are concatenated as
+ applying the result format, multiple values are concatenated as
comma separated strings. The expansion_limit and parameter
- explained below allows one to restrict the number of values in
+ explained below allows one to restrict the number of values in
the result, which is especially useful for maps that must return
at most one value.
- The default value %s specifies that each result value should be
+ The default value %s specifies that each result value should be
used as is.
This parameter is available with Postfix 2.2 and later.
@@ -201,14 +206,14 @@ MYSQL_TABLE(5) MYSQL_TABLE(5)
domain (default: no domain list)
This is a list of domain names, paths to files, or dictionaries.
- When specified, only fully qualified search keys with a
- *non-empty* localpart and a matching domain are eligible for
+ When specified, only fully qualified search keys with a
+ *non-empty* localpart and a matching domain are eligible for
lookup: 'user' lookups, bare domain lookups and "@domain"
- lookups are not performed. This can significantly reduce the
+ lookups are not performed. This can significantly reduce the
query load on the MySQL server.
domain = postfix.org, hash:/etc/postfix/searchdomains
- It is best not to use SQL to store the domains eligible for SQL
+ It is best not to use SQL to store the domains eligible for SQL
lookups.
This parameter is available with Postfix 2.2 and later.
@@ -217,35 +222,41 @@ MYSQL_TABLE(5) MYSQL_TABLE(5)
the input keys are always unqualified.
expansion_limit (default: 0)
- A limit on the total number of result elements returned (as a
+ A limit on the total number of result elements returned (as a
comma separated list) by a lookup against the map. A setting of
- zero disables the limit. Lookups fail with a temporary error if
- the limit is exceeded. Setting the limit to 1 ensures that
+ zero disables the limit. Lookups fail with a temporary error if
+ the limit is exceeded. Setting the limit to 1 ensures that
lookups do not return multiple values.
option_file
- Read options from the given file instead of the default my.cnf
- location. This reads options from the [client] option group,
+ Read options from the given file instead of the default my.cnf
+ location. This reads options from the [client] option group,
optionally followed by options from the group given with
option_group.
This parameter is available with Postfix 2.11 and later.
option_group (default: Postfix >=3.2: client, <= 3.1: empty)
- Read options from the given group of the mysql options file,
+ Read options from the given group of the mysql options file,
after reading options from the [client] group.
- Postfix 3.2 and later read [client] option group settings by
- default. To disable this specify no option_file and specify
+ Postfix 3.2 and later read [client] option group settings by
+ default. To disable this specify no option_file and specify
"option_group =" (i.e. an empty value).
- Postfix 3.1 and earlier don't read [client] option group set-
- tings unless a non-empty option_file or option_group value are
+ Postfix 3.1 and earlier don't read [client] option group set-
+ tings unless a non-empty option_file or option_group value are
specified. To enable this, specify, for example, "option_group =
client".
This parameter is available with Postfix 2.11 and later.
+ require_result_set (default: yes)
+ If "yes", require that every query returns a result set. If
+ "no", treat the absence of a result set as "not found".
+
+ This parameter is available with Postfix 3.2 and later.
+
tls_cert_file
File containing client's X509 certificate.
@@ -284,25 +295,18 @@ MYSQL_TABLE(5) MYSQL_TABLE(5)
The previously described '%' expansions can be used in the parameter(s)
to the stored procedure.
- The stored procedure must return data with a single result set, that is
- the stored procedure must execute exactly one SELECT statement on every
- code path. If you have complex logic and for some paths you want to
- return no result you will need to include a SELECT statement that
- returns no rows. One example of a query that returns no rows is
+ By default, every stored procedure call must return a result set, i.e.
+ every code path must execute a SELECT statement that returns a result
+ set (instead of storing its results in a table). With
+ "require_result_set = no", the absence of a result set is treated as
+ "not found".
- SELECT 1 FROM DUAL WHERE FALSE
+ A stored procedure must not return multiple result sets. That is,
+ there must be no code path that executes multiple SELECT statements
+ that return a result (instead of storing their results in a table).
- but you may use your own query.
-
- Stored procedures that return multiple result sets containing data,
- that is stored procedures that execute multiple SELECT statements, are
- not supported. Stored procedures in mysql produce an additional result
- set without data which indicates the final status of the stored proce-
- dure. If this final status is an error then any previous returned data
- will not be used.
-
- The following is an example of a stored procedure returning a single
- result set containing data:
+ The following is an example of a stored procedure returning a single
+ result set:
CREATE [DEFINER=`user`@`host`] PROCEDURE
`lookup`(IN `param` VARCHAR(255))
@@ -313,13 +317,13 @@ MYSQL_TABLE(5) MYSQL_TABLE(5)
END
OBSOLETE QUERY INTERFACE
- This section describes an interface that is deprecated as of Postfix
- 2.2. It is replaced by the more general query interface described
- above. If the query parameter is defined, the legacy parameters
- described here ignored. Please migrate to the new interface as the
+ This section describes an interface that is deprecated as of Postfix
+ 2.2. It is replaced by the more general query interface described
+ above. If the query parameter is defined, the legacy parameters
+ described here ignored. Please migrate to the new interface as the
legacy interface may be removed in a future release.
- The following parameters can be used to fill in a SELECT template
+ The following parameters can be used to fill in a SELECT template
statement of the form:
SELECT [select_field]
@@ -328,7 +332,7 @@ MYSQL_TABLE(5) MYSQL_TABLE(5)
[additional_conditions]
The specifier %s is replaced by the search string, and is escaped so if
- it contains single quotes or other odd characters, it will not cause a
+ it contains single quotes or other odd characters, it will not cause a
parse error, or worse, a security problem.
select_field
@@ -376,5 +380,10 @@ MYSQL_TABLE(5) MYSQL_TABLE(5)
Stored-procedure support by John Fawcett.
+ Wietse Venema
+ Google, Inc.
+ 111 8th Avenue
+ New York, NY 10011, USA
+
MYSQL_TABLE(5)