SupportConsole
llms.txtSign in

Connect a site to its database

llms.txt

A database is only useful once your application knows how to reach it: a host, a port, a database name, a user and a password. SrvYard can fill these in for you when you create a site, and you can change them at any time on the site's Environment page.

This article covers both routes, what values SrvYard writes for Laravel, Symfony and WordPress sites, and the few things to check when the application says it cannot connect. It assumes you already know how to create a database and a user.

Before you begin

  • A database engine on the server that runs the site. Install MySQL, MariaDB or PostgreSQL from the server's Services tab if the site form says to.
  • A PHP site. The Connect to database switch on the new site form is only offered for PHP-based site types. A phpMyAdmin or WordPress site needs a MySQL-family database and asks for one.
  • The application and the database on the same server is the simple case this article describes. For a database on another server, read Remote access, phpMyAdmin and SSH tunnels first.

1. Connect a database while you create the site

Open Sites > New site, choose the project type and the server. Below the repository choice you will find the Connect to database switch.

The Connect to database switch on the new site form
On the new site form, Connect to database creates or selects a database and writes the connection settings into .env.
  1. Connect to database. Switch it on to have SrvYard prepare the database with the site. For types that cannot run without one (WordPress and phpMyAdmin) it is already on.
  2. Select or create a database. Pick one of the databases that already exist on the server, or choose Create database at the bottom of the list to make a new one.

When you choose Create database a small dialog opens.

The Add database dialog of the new site form
The Add database dialog: a name and a user, created together with the site.
  1. Name. Pre-filled from the site name. Letters, numbers and underscores, up to 48 characters.
  2. User. The login for the new database, pre-filled too. It gets full access to that one database, and SrvYard generates its password.

Nothing is created until you press Create site. Then SrvYard creates the database and its user (or reuses the existing one), and keeps the connection details encrypted until the site's .env is written.

Note

If you pick an existing database, SrvYard looks for a user that already reaches it, has a stored password and is not a remote user, and reuses that one. If there is none (for example the database was imported), it creates a new user for the site with a generated name such as acme_shop_production_4f2a and full access to that database. Your other users are not touched.

2. What SrvYard writes

For a Laravel site, the .env receives these lines:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=shop_production
DB_USERNAME=shop_user
DB_PASSWORD=generated-by-srvyard

The connection name is mysql, mariadb or pgsql to match the engine, and the port is 3306 for MySQL and MariaDB or 5432 for PostgreSQL. The host is 127.0.0.1 because the application and the database share the server. For a Symfony site the same facts go into one DATABASE_URL line instead. For WordPress they go into wp-config.php, and phpMyAdmin is configured to talk to the server's own engine.

When the site has a repository, the file is written at the first deployment, together with the other first-run values (APP_KEY, APP_ENV=production and so on). Your repository's .env.example is used as the starting point and the database lines are merged into it.

3. Connect an existing site

A site that already exists gets its database settings on the Environment tab.

The Environment page filtered to the database variables
The .env of a site, filtered to its database variables; values stay hidden until you reveal them.
  1. Filter variables. Type DB_ to list only the database variables.
  2. Each row is one variable. Edit the value, or use Add variable to add a missing one. The values are hidden: press the eye on a row to see one.
  3. Reveal values shows all of them at once. Do it only when nobody is looking over your shoulder.
  4. Save and write to server stores the file encrypted in SrvYard and writes it to the server. Save and deploy does the same and deploys the site, which is what a Laravel application usually needs to pick up new values. The tick boxes Run php artisan config:cache and Restart queue workers do what they say once the file is written.

The password comes from the dialog you saw when the user was created. If you no longer have it, open the Users tab of the server's Databases page and choose Reveal password (it asks for your own SrvYard password first), or Reset password to get a new one.

Warning

Resetting a user's password breaks every application that still uses the old one. Update the .env of each of those sites straight afterwards.

4. Check what the user may do

Many "connection refused" and "access denied" problems come from the user, not the .env. Open the user from the Users tab with Edit.

The Edit panel of a database user
Edit a user to see which databases it reaches and what it may do there.
  1. Permissions. An application that runs migrations needs Full access or at least Read and write. A Read only user fails the first INSERT.
  2. Databases. The database your DB_DATABASE names must be ticked.
  3. Allow remote access. Switched off for a user that connects from the same server. Switched on, the Allowed host or IP field limits where it may connect from.

Press Save changes and SrvYard applies the permissions again on every linked database.

5. Test the connection

On the server, as the site user, a one-line check shows whether the credentials work. Open the site's Commands tab, or a terminal, and run:

php artisan db:show

Laravel prints the connection, the database name and its tables. If it reports an error, the message tells you which of the five values is wrong. The command only reads from the database, so it is safe to run on a live site. If you prefer to test outside the application, mysql -u shop_user -p shop_production (or psql for PostgreSQL) on the server opens a prompt with the same credentials. After changing the .env, run php artisan config:clear first when the application caches its configuration.

Troubleshooting

  • "Access denied for user". The username or password in .env does not match the user on the server. Reveal or reset the password on the Users tab and copy it into the .env again.
  • "Unknown database". The name in DB_DATABASE is wrong or the database was deleted. Compare it with the Databases tab; names are case sensitive on Linux.
  • "Connection refused" or "No such file or directory". The engine is not running (check the Services tab), or DB_HOST points somewhere else. On the same server use 127.0.0.1.
  • The new values are ignored. The application cached its configuration. Tick Run php artisan config:cache when saving, or deploy the site again.
  • A site on another server cannot connect. The user must allow remote access from that server, the engine must listen on the private address, and the firewall must allow the port. See the remote access article.
  • I cannot switch on Connect to database. The server has no database engine, or the site type does not use a database. Install an engine under Services.
Last updated 2026-10-247 min readNeed help? Contact support
PreviousCreate a database and a userNextRemote access, phpMyAdmin and SSH tunnels