2 min read

Directus Can't Connect to the Database

The Directus Software attempts to make a connection to the configured database but fails. Checking the configuration, ports and the database itself will resolve the issue.

This error can be quite broad. I collected a checklist in this article that you can use to troubleshoot your database connection.

This happens when the Directus Software attempts to make a connection to the configured database but fails. Checking the configuration, ports and the database itself will resolve the issue.

1. Check the Configuration

In the Directus environment file, check the host, port and credentials. If your database is on the same server, the host should be localhost. The port will be the default for the database provider, for example, MySQL is 3306. If you have configured your database to run on a non-standard port, make sure this is set in the environment file.

Lastly, your credentials. Use a terminal or console to login to your database using the same credentials. If you can access you database, then you know it's correct.

If any of these are incorrect, please edit the environment file and update the database connection.

2. Can your Server Reach the Database?

Sometimes the port or server can be blocked by a firewall. Check access by running telnet from the server the Directus is running on and using the database hostname and port.

telnet databasehost.example.com 1433

If the connection is successful, then your server can connect to the database.

If unsuccessful, you need to open the ports between the Directus Server and the Database Server. Without knowing the specifics, it's safe to say this usually happens on the database server. Update the firewall settings to allow your Directus server's IP address on the Database port. It's best to limit access to your database and the outside world as much as possible. To confirm if a firewall is the issue, you can temporarily disable the firewall on the database server and try telnet again.

For those using cloud computing, the Firewall settings tend to be in the VM admin and can also have network firewall as well. If this is the case, the exception will need to be added to both.

3. Is the Database Online

This is rare but worth checking. You can check if the database is running using the systemctl command (Linux) or check Windows Services and make sure the service is running.

If it's offline, try starting the service again. It's also worth checking the logs for the database service to make sure there wasn't an error that caused it to fail.

It can also be the database service is not configured to start on boot. In Windows, you can check the service properties and make sure it's set to Automatic. For Linux, just run systemctl enable database, and it will either enable it or tell you it's already enabled.

4. The Database does not exist

Directus will not create the database for you, this must be created first. Make sure the database name matches exactly to your environment file.

5. Database Permissions

Directus requires full permissions over the named database. This allows full use of the capabilities of Directus and avoids permission errors. This includes Inserts, Updates, Deletes, Creates, Drops, Truncate and most importantly, the ability to create Primary/Foreign Keys and Constraints. This is how Directus enforces the validation that you have confirgured within the application.

If you are installing Directus over an existing database, it's worth backing up your data before making changes.

Hopefully by this stage you have resolved you issue connecting to the database from Directus. If possible, the simplest and most secure database connection for Directus is using a local database. If your database is hosted externally, then the potential for issues increases.

By continuing to use our website, you consent to use essential cookies. We also use optional tracking cookies which help us gather statistics to improve our services. Do you consent to these cookies?

I Consent Do not track