Postfix Can’t Connect to MySQL: Causes & Fixes

Postfix fails to connect to MySQL when the Postfix process cannot reach the MySQL server, authenticate, or parse the lookup table configuration. The fix usually involves checking the MySQL service is running, verifying the connection parameters in mysql-*.cf files, and ensuring the Postfix user has the correct database permissions. Below is a systematic guide to diagnosing and resolving the most common causes.

How Postfix Uses MySQL

Postfix uses MySQL for virtual mailboxes, aliases, and relay domains. Instead of storing mail routing data in flat files, you can point Postfix to a database table. For example, a virtual_mailbox_maps entry in main.cf might look like:

virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf

The .cf file contains the connection details: host, port, user, password, database name, and the SQL query. When Postfix receives mail, it runs that query and expects a result. If the connection fails, Postfix logs an error like warning: mysql_query failed or connect to server failed and defers or rejects the mail.

Common Causes of Connection Failure

MySQL service is down – the database server is not running or is restarting.
Wrong host or port – Postfix is trying to connect to localhost but MySQL listens on a Unix socket, or the port is non-standard.
Authentication failure – the user or password in the .cf file is incorrect, or the user is only allowed to connect from a different host.
Missing database or table – the database name or table in the SQL query does not exist.
Permissions – the MySQL user lacks SELECT privilege on the table.
Postfix chroot – if Postfix runs in a chroot jail, it cannot see the MySQL socket or resolve the hostname.

Step-by-Step Diagnosis

Check MySQL is running: systemctl status mysql or service mysql status. If it is not running, start it and check the error log.
Test the connection manually: From the same machine, run mysql -u postfix -p -h 127.0.0.1 -P 3306 with the credentials from your .cf file. If this fails, the problem is in MySQL, not Postfix.
Verify the SQL query: Run the query from the .cf file manually, replacing %s with a test email address. Ensure it returns the expected result.
Check Postfix logs: Look in /var/log/mail.log or /var/log/maillog for the exact error message. Common lines include warning: mysql:/etc/postfix/mysql-*.cf: Host '...' is not allowed to connect to this MySQL server or lost connection to MySQL server.
Test with postmap: Run postmap -q "user@example.com" mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf to see if Postfix can query the database directly.

Fixing the Most Frequent Issues

1. MySQL Service Not Running

If MySQL is down, Postfix cannot connect. Start it with systemctl start mysql and enable it to start on boot. Check /var/log/mysql/error.log for crash reasons, such as disk full or corrupted tables.

2. Wrong Host or Socket

Postfix connects via TCP by default. If MySQL is configured to listen only on a Unix socket (common with localhost), you must use hosts = 127.0.0.1 instead of localhost in the .cf file. Alternatively, set hosts = unix:/var/run/mysqld/mysqld.sock if the socket path is accessible.

3. Authentication or Permission Errors

MySQL users are defined by user@host. If the .cf file uses hosts = localhost but the user is defined for 'postfix'@'127.0.0.1', the connection will be refused. Create a user that matches the host Postfix connects from, and grant SELECT on the specific table:

CREATE USER 'postfix'@'127.0.0.1' IDENTIFIED BY 'password';
GRANT SELECT ON maildb.* TO 'postfix'@'127.0.0.1';
FLUSH PRIVILEGES;

4. Chroot Jail

If Postfix runs in a chroot (typical on Debian/Ubuntu), it cannot access files outside the jail. The MySQL socket is usually outside. Solutions: use TCP (127.0.0.1) instead of a socket, or copy the necessary libraries and the socket into the chroot. The simplest fix is to set hosts = 127.0.0.1 and ensure the MySQL user is allowed to connect via TCP.

Verifying the Fix

After making changes, reload Postfix with postfix reload and test with postmap -q. Send a test email to a virtual user and check the logs. If the error is gone, the mail will be accepted. If you still see errors, run postconf -n to confirm the .cf file paths are correct and that no other map is overriding them.

Preventing Future Issues

Use a dedicated MySQL user with minimal privileges for Postfix.
Monitor MySQL connection limits – too many connections can cause temporary failures.
Set connect_timeout in the .cf file (e.g., connect_timeout = 5) to avoid long hangs.
Keep the MySQL server and Postfix on the same host to reduce network issues, or use a stable internal IP.
Regularly check logs for slow queries that might time out.

Frequently Asked Questions

Why does Postfix say “connect to server failed” but MySQL is running?

This usually means the host or port is wrong, or MySQL is listening only on a Unix socket. Try using 127.0.0.1 instead of localhost, and verify the port with netstat -tlnp | grep 3306.

Can I use a Unix socket instead of TCP?

Yes, but only if Postfix is not chrooted. Set hosts = unix:/var/run/mysqld/mysqld.sock and ensure the socket path is correct. If Postfix is chrooted, you must copy the socket into the jail or use TCP.

How do I test the MySQL query that Postfix runs?

Use the postmap command: postmap -q "user@example.com" mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf. If it returns nothing, the query or the data is wrong. You can also run the query manually in the MySQL client, replacing %s with the email address.

What does “Table ‘maildb.virtual_users’ doesn’t exist” mean?

It means the database or table name in the .cf file’s query does not match what is in MySQL. Check the spelling and the database name, and verify with SHOW TABLES in the MySQL client.

Why does Postfix work after a restart but fail later?

This can happen if MySQL runs out of connections or if a slow query blocks the table. Increase max_connections in MySQL config, or add indexes to the table being queried. Also check for long-running locks.

Is it safe to store the MySQL password in the .cf file?

Yes, but restrict file permissions to root and postfix: chmod 640 /etc/postfix/mysql-*.cf and chown root:postfix. Never use a MySQL user with full admin rights; grant only SELECT on the needed tables.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →