Connect Your Laravel, Node.js or PHP App to PostgreSQL in xCloud
Updated November 17, 2026 · 7 min read
When you create a PHP App, Laravel or Node.js site with Database engine set to PostgreSQL, xCloud creates a database and a role for the site and writes the connection details to the site’s .env file. Your app only has to read those variables. This guide lists the variables, shows how Laravel, Node.js (pg and Prisma) and plain PHP (PDO) read them, and covers the errors people hit most.
Apps that run in a container, such as Python, Ruby, Go, Java and Bun apps, can use managed PostgreSQL too. They reach it by a different host name, so read Apps that run in a container below.
If PostgreSQL is not on your server yet, first follow Install Managed PostgreSQL and pgAdmin in xCloud. That guide also shows how to pick PostgreSQL when you create a site. To create a PostgreSQL site from a script or an AI agent instead, see Use the server’s managed PostgreSQL in the Public API and MCP guide.
Before you start
- Managed PostgreSQL shows Ready on an Nginx server. It runs PostgreSQL 17 in Docker (Docker Engine 28 or newer) and is not available on OpenLiteSpeed servers.
- A Git site that uses PostgreSQL. The site’s App Type is PHP App, Laravel or Node.js, or a container app (see Apps that run in a container below), and its Database engine was set to PostgreSQL when you created it. When your repository needs PostgreSQL, Deploy via Git selects it for you and can install it on the server from the same form. See Check the database xCloud picked.
The variables xCloud writes
xCloud adds these seven lines to the site’s .env file during the first deploy. It writes them last, so they replace any database values that came from your repository’s .env.example.
DB_CONNECTION='pgsql'
DB_HOST='127.0.0.1'
DB_PORT='<port>'
DB_DATABASE='xc_site_<site id>'
DB_USERNAME='xc_site_<site id>'
DB_PASSWORD='<generated password>'
DATABASE_URL='postgresql://xc_site_<site id>:<generated password>@127.0.0.1:<port>/xc_site_<site id>'
| Variable | What it holds |
|---|---|
DB_CONNECTION |
Always pgsql, the name Laravel uses for its PostgreSQL driver |
DB_HOST |
127.0.0.1 for PHP App, Laravel and Node.js sites. PostgreSQL only listens on the server itself and is not reachable from the internet. Container apps use xcloud-postgresql instead |
DB_PORT |
The port xCloud chose for the server’s PostgreSQL. It is usually not 5432 |
DB_DATABASE and DB_USERNAME |
The site’s own database and role. Both are named xc_site_ plus the site’s ID |
DB_PASSWORD |
A generated 40-character password made of letters and numbers |
DATABASE_URL |
The same details as one connection string, for Node.js libraries and Prisma |
The site’s role owns its database. It cannot create other databases or roles. Use pgAdmin for that (see Add more databases and roles in pgAdmin).
Step 1: Find the variables in your site’s .env file
Laravel and Node.js sites: open the site and go to ‘Laravel’ → ‘Environment’ (or ‘Node.js’ → ‘Environment’). The editor shows the .env file with the DB_ lines and DATABASE_URL at the end.

You can edit values here and click Update Environment. For a Node.js site, saving restarts the app so it picks up the change. Leave the database lines as xCloud wrote them unless you deliberately point the app at another database. On these sites, each Git deploy puts back the .env you had before it, even over a .env committed to your repository. See Environment variables and Git deployments.
PHP App sites: the dashboard has no Environment editor for PHP App sites. The file is /var/www/<your site>/.env, or .env in the folder you set as .env File Path in the site’s Git settings. Open it over SSH or in the web terminal.
Step 2: Connect your app
Laravel
Laravel reads DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME and DB_PASSWORD with its default config/database.php, so nothing needs to change in code. After the deploy, run the migrations from your deploy script or on the server:
php artisan migrate --force
Expected result: the migrations run without a connection error. If you cached the config before the variables were written, run php artisan config:clear first.
Node.js with pg
xCloud loads the site’s .env file into the app’s environment every time the app starts, so process.env.DATABASE_URL is set without the dotenv package.
const { Pool } = require('pg');
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const { rows } = await pool.query('SELECT version()');
console.log(rows[0].version);
You can also pass the separate values: host: process.env.DB_HOST, port: Number(process.env.DB_PORT), database: process.env.DB_DATABASE, user: process.env.DB_USERNAME, password: process.env.DB_PASSWORD.
Node.js with Prisma
Point the datasource at DATABASE_URL in prisma/schema.prisma:
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}
Then apply your migrations in the site’s deploy script, for example npx prisma migrate deploy. The Prisma CLI reads DATABASE_URL from the .env file in the project folder.
Plain PHP with PDO
PHP on xCloud Nginx servers includes the pdo_pgsql driver. Plain PHP does not read .env files by itself, so load it first, for example with the vlucas/phpdotenv package (composer require vlucas/phpdotenv):
<?php
require __DIR__ . '/vendor/autoload.php';
Dotenv\Dotenv::createImmutable(__DIR__)->load();
$dsn = sprintf('pgsql:host=%s;port=%s;dbname=%s',
$_ENV['DB_HOST'], $_ENV['DB_PORT'], $_ENV['DB_DATABASE']);
$pdo = new PDO($dsn, $_ENV['DB_USERNAME'], $_ENV['DB_PASSWORD'], [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);
echo $pdo->query('SELECT version()')->fetchColumn();
If your .env file is in a subfolder, pass that folder to createImmutable() instead of __DIR__.
Step 3: Check the connection
Load a page or route that queries the database, or run the check from the server. Expected result: the query returns the PostgreSQL 17 version string. If it fails, find the error in the table below.
Common errors
| Error | Cause | Fix |
|---|---|---|
connection refused on port 5432 |
The app uses 5432 instead of the port xCloud chose (PHP App, Laravel and Node.js sites) | Use DB_PORT or DATABASE_URL from the .env file, never a hard-coded port |
could not translate host name "xcloud-postgresql" |
A non-container site uses the container host name | Use 127.0.0.1 and DB_PORT. Only container apps use xcloud-postgresql:5432 |
could not find driver in Laravel or PDO |
The app still uses the MySQL driver, or DB_CONNECTION is mysql |
Set DB_CONNECTION=pgsql and use a pgsql: DSN, not mysql: |
Access denied or SQLSTATE[HY000] [2002] |
A MySQL error: the app is still connecting to MySQL | Check that the config reads the .env values above and clear any cached config |
password authentication failed |
Wrong database user or password, for example one changed by hand | Use DB_USERNAME and DB_PASSWORD exactly as written |
pg_hba.conf rejects connection |
The app logs in as the postgres admin user |
Use DB_USERNAME and DB_PASSWORD from the site. The postgres user can’t log in over a network connection |
permission denied to create database |
The site role cannot create databases or roles | Create extra databases and roles in pgAdmin |
| Variables are empty in a PHP App | Plain PHP does not load .env files |
Load the file with phpdotenv as shown above |
| Timeout when connecting from your computer | PostgreSQL can’t be reached from the internet by server IP and port | Work in pgAdmin, or connect through an SSH tunnel |
Apps that run in a container
Apps that xCloud builds from a Dockerfile, such as a Django, Rails, Go, Java or Bun app, can use the server’s managed PostgreSQL too. When the repository needs PostgreSQL, the Deploy via Git form says This app needs PostgreSQL, we’ll create it. Untick the box to add your own DATABASE_URL instead. and ticks Create a PostgreSQL database for this app. If the server has no managed PostgreSQL yet, the form offers Install PostgreSQL instead. While it installs, you can tick Deploy without a managed database to deploy without it.
A container can’t reach the server’s 127.0.0.1, so xCloud writes different connection values for it:
DB_CONNECTION=pgsql
DB_HOST=xcloud-postgresql
DB_PORT=5432
DATABASE_URL=postgresql://xc_site_<site id>:<generated password>@xcloud-postgresql:5432/xc_site_<site id>
DB_DATABASE, DB_USERNAME and DB_PASSWORD work the same way as above. xCloud writes these values once, when it creates the site. A value you already gave in the .env box is kept, and an empty one or a localhost example from your repository is replaced.
The app reaches PostgreSQL over a private network that only your site and PostgreSQL share. Other sites on the server, and pgAdmin, are not on it. Read DATABASE_URL or the DB_ values in your app, for example dj-database-url in Django or database.yml with url: <%= ENV["DATABASE_URL"] %> in Rails.
Two cases still need your own DATABASE_URL: a container app that needs MySQL, and a repository that runs its own docker-compose.yml. For those, the form asks you to add DATABASE_URL to the .env. To deploy a container app, see Deploy Python, Ruby, Go, Java and Bun apps from Git.
Add more databases and roles in pgAdmin
Each site gets one database and one role. To add more, for example a separate database for a queue or a read-only role for reports, use pgAdmin:
- Go to the server’s ‘Management’ → ‘Database’ and click Open pgAdmin on the pgAdmin card. Sign in with the details from Show credentials.
- In pgAdmin, right-click Login/Group Roles and choose Create → Login/Group Role. Give it a name, set a password on the Definition tab and allow Can login? on the Privileges tab.
- Right-click Databases and choose Create → Database. Set Owner to the role you created.
- Add the new values to your site’s
.envunder your own variable names. Use127.0.0.1and the sameDB_PORTas the site’s other values.
pgAdmin shows the server on port 5432 because it connects from inside the private Docker network. Your app on the server still uses DB_PORT.
Limits to know
- Backups: xCloud site backups include the PostgreSQL database and restore it in place. See Back up and restore PostgreSQL.
- Clone, migrate, staging and snapshots: not available for PostgreSQL sites yet.
- Deleting a site: xCloud keeps the site’s database and role. Remove them in pgAdmin if you no longer need them.
- One-click PostgreSQL app: the separate PostgreSQL one-click app is a different setup. A server that runs it cannot add managed PostgreSQL.
For MySQL sites, see Create a database for your site. To deploy the app itself, see Deploy a Node.js application or Deploy Laravel applications.
Frequently asked questions
Why does my app fail to connect on port 5432?
Managed PostgreSQL does not listen on 5432 on the server. xCloud picks a port for it and writes that port to DB_PORT and DATABASE_URL in your site’s .env file. Read the port from there instead of hard-coding 5432. pgAdmin shows 5432 because it connects from inside the private Docker network.
Can I connect to managed PostgreSQL from my computer?
Not directly. Managed PostgreSQL on xCloud can’t be reached from the internet by server IP and port, so you connect from your computer through an SSH tunnel. Use pgAdmin, or open the tunnel as the site user and connect DBeaver, TablePlus or psql through it.
Can I log in to PostgreSQL as the postgres user?
No. The postgres admin user cannot log in over a network connection. Use the site’s own role from DB_USERNAME, or create more databases and roles in pgAdmin.
Does xCloud back up my PostgreSQL database?
Yes. When Database Backup is set to Take Database Backup in Backup Settings, every site backup saves a full copy of the site’s PostgreSQL database next to its files, and you can restore it in place. You can also export it yourself with pgAdmin or pg_dump.
If you run into any issues connecting your app to PostgreSQL, feel free to reach out to our support team.