Quick answer
When a database refuses a connection, the most common causes are incorrect login details, the database is not running, network problems or a configuration that does not allow remote connections. Check whether the service is running, test the connection from the local machine and review the database logs.
How to recognize the problem
- The application reports an error when connecting to the database
- The message contains 'connection refused' or 'can't connect'
- The connection works locally but not from a remote machine
- The database crashes or restarts when attempting to connect
- The error occurs only in the production environment
Most common causes
The database is not running
The database service may be stopped or crashing due to lack of resources. Check the service status and logs.
Incorrect connection details
A wrong hostname, port, username or password prevents the connection from being established. Check the application configuration.
Network problems or firewall
A firewall or network rules may block the database port. Check whether the port is reachable from the client machine.
The database does not allow remote connections
By default, many databases accept only local connections. You need to configure parameters such as `bind-address` or `listen_addresses`.
Too many active connections
The database may refuse new connections if the maximum allowed number has been reached. Check `max_connections` and close idle connections.
Step-by-step fix
- 1
Check whether the database service is running
On Windows, open
services.mscand find the database service (e.g. MySQL, PostgreSQL). On Linux, usesystemctl status mysqlorsystemctl status postgresql. If the service is not running, start it withsudo systemctl start mysql(or the appropriate command for your database). - 2
Test the connection from the local machine
Try to connect to the database from the same machine where the database is running, using a command-line tool (e.g.
mysql -u root -porpsql -U postgres). If that succeeds, the problem is in the network or remote access. - 3
Check the connection details
Make sure the host, port, username and password are correct. In the application, check the configuration files or environment variables. Pay attention to whether you are using
localhostor127.0.0.1. - 4
Check whether the port is reachable
From the client machine, try
telnet <host> <port>ornc -zv <host> <port>. If the port is closed, check the firewall on the server and the network rules. On Windows, useTest-NetConnection -ComputerName <host> -Port <port>in PowerShell. - 5
Configure the database to accept remote connections
Before making changes, back up the configuration files. For MySQL, change
bind-addressinmy.cnformy.inito the address of the appropriate interface (e.g.0.0.0.0only if access is restricted by a firewall) and restart the service; then check the user permissions by host. For PostgreSQL, changelisten_addressesinpostgresql.confand add the appropriate entry inpg_hba.conf. For SQL Server, enable the TCP/IP protocol in SQL Server Configuration Manager, check the port and restart the service. - 6
Check the maximum number of connections
Connect to the database as an administrator and run a query for the current number of connections (e.g.
SHOW STATUS LIKE 'Threads_connected';for MySQL). If it is close to the maximum, increasemax_connectionsor optimize the application to close unused connections. - 7
Review the database logs
The database logs (e.g. MySQL error log, PostgreSQL log or the system journal) often contain the exact reason for the connection refusal. Look for authentication error messages or network problems.
- 8
Restart the database and the application
Sometimes a restart of the database service and the application that connects to it is needed. Use
sudo systemctl restart mysqlor the appropriate command. In production, plan the restart during downtime. Then start the application again and check whether the error occurs.
If nothing helps
If you have checked everything listed above and the database still refuses the connection, consider the following:
- Check the database and driver versions: Incompatible versions can cause connection errors.
- Test from another client: Try from another computer or tool (e.g. DBeaver, pgAdmin) to rule out a problem in the application.
- Temporarily disable the firewall only on a test machine: Never do this on a production server; if you must, do it briefly and make sure to re-enable the firewall.
- Consult the documentation: See the official documentation for your database.
- Engage an expert: If the problem persists, contact a more experienced colleague or IT support.
How to prevent it
- Regularly update the database and drivers.
- Use strong passwords and restrict access to the necessary IP addresses.
- Monitor the number of active connections and increase the limit if needed.
- Test the connection in the development environment before moving to production.
When to call a professional
If you do not have access to the server infrastructure or are not sure how to change the database configuration, contact IT support. Also, if the database is in production and you must not risk downtime, it is better to have experienced administrators do it.
Software and product development · Custom apps, SaaS and an MVP in 4 to 8 weeksFAQ
Why does the database refuse a connection from a remote machine but work locally?
Most likely the database is not configured to accept remote connections. Check parameters such as `bind-address` (MySQL) or `listen_addresses` (PostgreSQL) and the permissions in `pg_hba.conf` or the `mysql.user` table.
How do I know whether the problem is in the database or in the application?
Try to connect to the database using a command-line tool from the same machine where the application is. If that succeeds, the problem is in the application configuration. If it fails, the problem is in the database or the network.
What does the 'Too many connections' error mean?
The database has reached the maximum number of allowed simultaneous connections. Increase `max_connections` or optimize the application to close connections properly.