{
    "mode": "man",
    "parameter": "mysql_table",
    "section": "5",
    "url": "https://www.chedong.com/phpMan.php/man/mysql_table/5/json",
    "generated": "2026-08-05T22:35:37Z",
    "synopsis": "postmap -q \"string\" mysql:/etc/postfix/filename\npostmap -q - mysql:/etc/postfix/filename <inputfile",
    "sections": {
        "NAME": {
            "content": "mysqltable - Postfix MySQL client configuration\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "postmap -q \"string\" mysql:/etc/postfix/filename\n\npostmap -q - mysql:/etc/postfix/filename <inputfile\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The Postfix mail system uses optional tables for address rewriting or mail routing. These ta‐\nbles are usually in dbm or db format.\n\nAlternatively,  lookup  tables  can  be  specified as MySQL databases.  In order to use MySQL\nlookups, define a MySQL source as a lookup table in main.cf, for example:\naliasmaps = mysql:/etc/postfix/mysql-aliases.cf\n\nThe file /etc/postfix/mysql-aliases.cf has the same format as the Postfix main.cf  file,  and\ncan specify the parameters described below.\n",
            "subsections": []
        },
        "LIST MEMBERSHIP": {
            "content": "When using SQL to store lists such as $mynetworks, $mydestination, $relaydomains, $localre‐\ncipientmaps,  etc., it is important to understand that the table must store each list member\nas a separate key. The table lookup verifies the *existence* of the key. See  \"Postfix  lists\nversus tables\" in the DATABASEREADME document for a discussion.\n\nDo NOT create tables that return the full list of domains in $mydestination or $relaydomains\netc., or IP addresses in $mynetworks.\n\nDO create tables with each matching item as a key and with an arbitrary value. With SQL data‐\nbases it is not uncommon to return the key itself or a constant value.\n",
            "subsections": []
        },
        "MYSQL PARAMETERS": {
            "content": "hosts  The  hosts that Postfix will try to connect to and query from.  Specify unix: for UNIX\ndomain sockets, inet: for TCP connections (default).  Examples:\nhosts = inet:host1.some.domain inet:host2.some.domain:port\nhosts = host1.some.domain host2.some.domain:port\nhosts = unix:/file/name\n\nThe hosts are tried in random order, with all connections over UNIX domain sockets be‐\ning tried before those over TCP.  The connections are automatically closed after being\nidle for about 1 minute, and are re-opened as necessary. Postfix versions 2.0 and ear‐\nlier do not randomize the host order.\n\nNOTE: if you specify localhost as a hostname (even if you prefix it with inet:), MySQL\nwill connect to the default UNIX domain socket.  In order to instruct MySQL to connect\nto localhost over TCP you have to specify\nhosts = 127.0.0.1\n",
            "subsections": [
                {
                    "name": "user",
                    "content": ""
                },
                {
                    "name": "password",
                    "content": "The user name and password to log into the mysql server.  Example:\nuser = someone\npassword = somepassword\n\ndbname The database name on the servers. Example:\ndbname = customerdatabase\n\nquery  The SQL query template used to search the database, where %s is a substitute  for  the\naddress Postfix is trying to resolve, e.g.\nquery = SELECT replacement FROM aliases WHERE mailbox = '%s'\n\nBy  default, every query must return a result set (instead of storing its results in a\ntable); with \"requireresultset = no\" (Postfix 3.2 and later), the absence of  a  re‐\nsult set is treated as \"not found\".\n\nThis parameter supports the following '%' expansions:\n\n%%     This is replaced by a literal '%' character.\n\n%s     This  is  replaced by the input key.  SQL quoting is used to make sure that the\ninput key does not add unexpected metacharacters.\n\n%u     When the input key is an address of the form user@domain, %u is replaced by the\nSQL quoted local part of the address.  Otherwise, %u is replaced by the  entire\nsearch  string.  If the localpart is empty, the query is suppressed and returns\nno results.\n\n%d     When the input key is an address of the form user@domain, %d is replaced by the\nSQL quoted domain part of the address.  Otherwise, the query is suppressed  and\nreturns no results.\n\n%[SUD] The  upper-case equivalents of the above expansions behave in the query parame‐\nter identically to their lower-case counter-parts.  With the resultformat  pa‐\nrameter (see below), they expand the input key rather than the result value.\n\n%[1-9] The  patterns %1, %2, ... %9 are replaced by the corresponding most significant\ncomponent of the input key's domain. If the input key is user@mail.example.com,\nthen %1 is com, %2 is example and %3 is mail. If the input key  is  unqualified\nor  does  not  have  enough domain components to satisfy all the specified pat‐\nterns, the query is suppressed and returns no results.\n\nThe domain parameter described below limits the input keys to  addresses  in  matching\ndomains. When the domain parameter is non-empty, SQL queries for unqualified addresses\nor addresses in non-matching domains are suppressed and return no results.\n\nThis  parameter  is  available  with  Postfix 2.2. In prior releases the SQL query was\nbuilt from  the  separate  parameters:  selectfield,  table,  wherefield  and  addi‐\ntionalconditions. The mapping from the old parameters to the equivalent query is:\n\nSELECT [selectfield]\nFROM [table]\nWHERE [wherefield] = '%s'\n[additionalconditions]\n\nThe  '%s'  in the WHERE clause expands to the escaped search string.  With Postfix 2.2\nthese legacy parameters are used if the query parameter is not specified.\n\nNOTE: DO NOT put quotes around the query parameter.\n\nresultformat (default: %s)\nFormat template applied to  result  attributes.  Most  commonly  used  to  append  (or\nprepend) text to the result. This parameter supports the following '%' expansions:\n\n%%     This is replaced by a literal '%' character.\n\n%s     This  is replaced by the value of the result attribute. When result is empty it\nis skipped.\n\n%u     When the result attribute value is an address of the form  user@domain,  %u  is\nreplaced  by the local part of the address. When the result has an empty local‐\npart it is skipped.\n\n%d     When a result attribute value is an address of the form user@domain, %d is  re‐\nplaced  by  the domain part of the attribute value. When the result is unquali‐\nfied it is skipped.\n\n%[SUD1-9]\nThe upper-case and decimal digit expansions interpolate the parts of the  input\nkey  rather than the result. Their behavior is identical to that described with\nquery, and in fact because the input key is known in advance, queries whose key\ndoes not contain all the information specified in the result template are  sup‐\npressed and return no results.\n\nFor  example, using \"resultformat = smtp:[%s]\" allows one to use a mailHost attribute\nas the basis of a transport(5) table. After applying the result format, multiple  val‐\nues are concatenated as comma separated strings. The expansionlimit and parameter ex‐\nplained  below allows one to restrict the number of values in the result, which is es‐\npecially useful for maps that must return at most one value.\n\nThe default value %s specifies that each result value should be used as is.\n\nThis parameter is available with Postfix 2.2 and later.\n\nNOTE: DO NOT put quotes around the result format!\n"
                },
                {
                    "name": "domain (default: no domain list)",
                    "content": "This is a list of domain names, paths to files, or \"type:table\" databases. When speci‐\nfied, only fully qualified search keys with a *non-empty* localpart and a matching do‐\nmain are eligible for lookup:  'user'  lookups,  bare  domain  lookups  and  \"@domain\"\nlookups  are  not performed. This can significantly reduce the query load on the MySQL\nserver.\ndomain = postfix.org, hash:/etc/postfix/searchdomains\n\nIt is best not to use SQL to store the domains eligible for SQL lookups.\n\nThis parameter is available with Postfix 2.2 and later.\n\nNOTE: DO NOT define this parameter for local(8) aliases, because the  input  keys  are\nalways unqualified.\n"
                },
                {
                    "name": "expansion_limit (default: 0)",
                    "content": "A limit on the total number of result elements returned (as a comma separated list) by\na  lookup  against the map.  A setting of zero disables the limit. Lookups fail with a\ntemporary error if the limit is exceeded.  Setting the limit to 1 ensures that lookups\ndo not return multiple values.\n"
                },
                {
                    "name": "option_file",
                    "content": "Read options from the given file instead of the default my.cnf  location.  This  reads\noptions  from the [client] option group, optionally followed by options from the group\ngiven with optiongroup.\n\nThis parameter is available with Postfix 2.11 and later.\n"
                },
                {
                    "name": "option_group (default: Postfix >=3.2: client, <= 3.1: empty)",
                    "content": "Read options from the given group of the mysql options  file,  after  reading  options\nfrom the [client] group.\n\nPostfix  3.2 and later read [client] option group settings by default. To disable this\nspecify no optionfile and specify \"optiongroup =\" (i.e. an empty value).\n\nPostfix 3.1 and earlier don't read [client] option group settings unless  a  non-empty\noptionfile or optiongroup value are specified. To enable this, specify, for example,\n\"optiongroup = client\".\n\nThis parameter is available with Postfix 2.11 and later.\n"
                },
                {
                    "name": "require_result_set (default: yes)",
                    "content": "If  \"yes\",  require that every query returns a result set.  If \"no\", treat the absence\nof a result set as \"not found\".\n\nThis parameter is available with Postfix 3.2 and later.\n"
                },
                {
                    "name": "tls_cert_file",
                    "content": "File containing client's X509 certificate.\n\nThis parameter is available with Postfix 2.11 and later.\n"
                },
                {
                    "name": "tls_key_file",
                    "content": "File containing the private key corresponding to tlscertfile.\n\nThis parameter is available with Postfix 2.11 and later.\n"
                },
                {
                    "name": "tls_CAfile",
                    "content": "File containing certificates for all of the X509 Certification Authorities the  client\nwill recognize.  Takes precedence over tlsCApath.\n\nThis parameter is available with Postfix 2.11 and later.\n"
                },
                {
                    "name": "tls_CApath",
                    "content": "Directory  containing X509 Certification Authority certificates in separate individual\nfiles.\n\nThis parameter is available with Postfix 2.11 and later.\n"
                },
                {
                    "name": "tls_ciphers",
                    "content": "The list of permissible ciphers for SSL encryption.\n\nThis parameter is available with Postfix 2.11 and later.\n"
                },
                {
                    "name": "tls_verify_cert (default: no)",
                    "content": "Verify that the server's name matches the common name in the certificate.\n\nThis parameter is available with Postfix 2.11 and later.\n"
                }
            ]
        },
        "USING MYSQL STORED PROCEDURES": {
            "content": "Postfix 3.2 and later support calling a stored procedure instead of using a SELECT  statement\nin the query, e.g.\n\nquery = CALL lookup('%s')\n\nThe  previously described '%' expansions can be used in the parameter(s) to the stored proce‐\ndure.\n\nBy default, every stored procedure call must return a result set, i.e. every code  path  must\nexecute a SELECT statement that returns a result set (instead of storing its results in a ta‐\nble). With \"requireresultset = no\", the absence of a result set is treated as \"not found\".\n\nA stored procedure must not return multiple result sets.  That is, there must be no code path\nthat  executes  multiple SELECT statements that return a result (instead of storing their re‐\nsults in a table).\n\nThe following is an example of a stored procedure returning a single result set:\n\nCREATE [DEFINER=`user`@`host`] PROCEDURE\n`lookup`(IN `param` VARCHAR(255))\nREADS SQL DATA\nSQL SECURITY INVOKER\nBEGIN\nselect goto from alias where address=param;\nEND\n\nOBSOLETE MAIN.CF PARAMETERS\nFor compatibility with other Postfix lookup tables, MySQL parameters can also be  defined  in\nmain.cf.  In order to do that, specify as MySQL source a name that doesn't begin with a slash\nor  a  dot.  The MySQL parameters will then be accessible as the name you've given the source\nin its definition, an underscore, and the name of the parameter.  For example, if the map  is\nspecified  as \"mysql:mysqlname\", the parameter \"hosts\" would be defined in main.cf as \"mysql‐\nnamehosts\".\n\nNote: with this form, the passwords for the MySQL sources are written in  main.cf,  which  is\nnormally world-readable.  Support for this form will be removed in a future Postfix version.\n",
            "subsections": []
        },
        "OBSOLETE QUERY INTERFACE": {
            "content": "This  section  describes an interface that is deprecated as of Postfix 2.2. It is replaced by\nthe more general query interface described above. If the  query  parameter  is  defined,  the\nlegacy  parameters described here ignored.  Please migrate to the new interface as the legacy\ninterface may be removed in a future release.\n\nThe following parameters can be used to fill in a SELECT template statement of the form:\n\nSELECT [selectfield]\nFROM [table]\nWHERE [wherefield] = '%s'\n[additionalconditions]\n\nThe specifier %s is replaced by the search string, and is escaped so if  it  contains  single\nquotes  or  other odd characters, it will not cause a parse error, or worse, a security prob‐\nlem.\n",
            "subsections": [
                {
                    "name": "select_field",
                    "content": "The SQL \"select\" parameter. Example:\nselectfield = forwaddr\n\ntable  The SQL \"select .. from\" table name. Example:\ntable = mxaliases\n"
                },
                {
                    "name": "where_field",
                    "content": "The SQL \"select .. where\" parameter. Example:\nwherefield = alias\n"
                },
                {
                    "name": "additional_conditions",
                    "content": "Additional conditions to the SQL query. Example:\nadditionalconditions = AND status = 'paid'\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "postmap(1), Postfix lookup table maintenance\npostconf(5), configuration parameters\nldaptable(5), LDAP lookup tables\npgsqltable(5), PostgreSQL lookup tables\nsqlitetable(5), SQLite lookup tables\n",
            "subsections": []
        },
        "README FILES": {
            "content": "Use \"postconf readmedirectory\" or \"postconf htmldirectory\" to locate this information.\nDATABASEREADME, Postfix lookup table overview\nMYSQLREADME, Postfix MYSQL client guide\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "The Secure Mailer license must be distributed with this software.\n",
            "subsections": []
        },
        "HISTORY": {
            "content": "MySQL support was introduced with Postfix version 1.0.\n\nAUTHOR(S)\nOriginal implementation by:\nScott Cotton, Joshua Marcus\nIC Group, Inc.\n\nFurther enhancements by:\nLiviu Daia\nInstitute of Mathematics of the Romanian Academy\nP.O. BOX 1-764\nRO-014700 Bucharest, ROMANIA\n\nStored-procedure support by John Fawcett.\n\nWietse Venema\nGoogle, Inc.\n111 8th Avenue\nNew York, NY 10011, USA\n\nMYSQLTABLE(5)",
            "subsections": []
        }
    },
    "summary": "mysqltable - Postfix MySQL client configuration",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "postmap",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/postmap/1/json"
        },
        {
            "name": "postconf",
            "section": "5",
            "url": "https://www.chedong.com/phpMan.php/man/postconf/5/json"
        },
        {
            "name": "ldaptable",
            "section": "5",
            "url": "https://www.chedong.com/phpMan.php/man/ldaptable/5/json"
        },
        {
            "name": "pgsqltable",
            "section": "5",
            "url": "https://www.chedong.com/phpMan.php/man/pgsqltable/5/json"
        },
        {
            "name": "sqlitetable",
            "section": "5",
            "url": "https://www.chedong.com/phpMan.php/man/sqlitetable/5/json"
        }
    ]
}