How to Install Managed PostgreSQL and pgAdmin in xCloud

Updated November 15, 2026 · 10 min read

Summarize with:
Share:

xCloud can run one managed PostgreSQL service per Nginx server. Every PostgreSQL site on that server shares it, you manage databases and roles in a managed pgAdmin, and native Git sites (PHP App, Laravel and Node.js) can choose PostgreSQL instead of MySQL when you create them. This guide shows how to install PostgreSQL (when you create a server or later), enable pgAdmin, create a PostgreSQL site, and restart PostgreSQL or read its logs. To install from a script or an AI agent instead, see Install PostgreSQL with the Public API or MCP.

Before you start

  • An Nginx server. Managed PostgreSQL is only available on the Nginx stack. See Available Server Stacks in xCloud.
  • Docker Engine 28 or newer on the server. PostgreSQL and pgAdmin run as private containers. If Docker is older, the install fails with “Private data services require Docker Engine 28 or newer. Upgrade Docker before retrying.”
  • No PostgreSQL one-click app on the server. If the server already runs the catalog PostgreSQL one-click app, the managed install is not offered.
  • Permission to manage the server’s services. Team members need server service access to install PostgreSQL or use pgAdmin.

Install PostgreSQL when you create a server

On a new Nginx server, you can pick PostgreSQL as the server’s database instead of MySQL or MariaDB. On the server form, choose the Nginx stack, open Select Database Server and pick PostgreSQL. xCloud installs PostgreSQL 17 while it sets up the server.

Pick ‘PostgreSQL’ in the ‘Select Database Server’ dropdown on the new server form

  • One database server at creation. Picking PostgreSQL means the server starts without MySQL or MariaDB. You can add one later from Install a Service in ‘Management’ → ‘Settings’.
  • Nginx only. PostgreSQL is not in the list for other stacks. If you switch the stack away from Nginx after picking PostgreSQL, the form goes back to MySQL.

When the server is ready, go to Step 3: Enable pgAdmin. To add PostgreSQL to a server you already have, follow Step 1 below.

Step 1: Install PostgreSQL from Server Management

Open your server and go to ‘Management’ → ‘Settings’. Scroll to Install a Service (the Install a Service button at the top jumps there) and click Install on the PostgreSQL row (“Private PostgreSQL shared by sites on this server”).

Click ‘Install’ on the PostgreSQL row under ‘Install a Service’ in Management → Settings

PostgreSQL moves to the Server Utilities list at the top of the page and shows Queued, then Installing…. The page refreshes the status on its own.

Step 2: Wait for Ready, or retry a failed install

When the install finishes, the PostgreSQL row shows Ready.

The PostgreSQL row shows ‘Ready’ in Server Utilities

If the row shows Failed, read the message under the status. It names the cause, for example an outdated Docker Engine or another managed database operation still running. Fix the cause, then click Retry on the row.

Click ‘Retry’ on a failed PostgreSQL row in Server Utilities

Step 3: Enable pgAdmin

Go to ‘Management’ → ‘Database’. Once PostgreSQL is ready, a pgAdmin card appears above phpMyAdmin. Click Enable pgAdmin.

Click ‘Enable pgAdmin’ on the pgAdmin card in Management → Database

The card shows Provisioning… while xCloud installs pgAdmin. If it fails, click Retry on the card.

Step 4: Open pgAdmin and sign in

When pgAdmin is ready, the card shows Open pgAdmin, Show credentials and Disable pgAdmin.

Click ‘Open pgAdmin’ on the pgAdmin card once it is ready

  1. Click Show credentials to see the pgAdmin Email and Password. pgAdmin has its own web login: the email is the one on the xCloud account that enabled pgAdmin, and the password is shown only to members who can manage the server.
  2. Click Open pgAdmin. pgAdmin opens over HTTPS in a new tab.
  3. Sign in with those credentials. You can now create databases and roles, run queries, and export data.

Click Hide credentials when you’re done.

Step 5: Create a site that uses PostgreSQL

With PostgreSQL ready, native Git sites on this server can use it. Start a new site with Deploy via Git (see Deploy Git Projects in One Click), choose the repository, and pick PHP App, Laravel or Node.js as the App Type. Set Database engine to PostgreSQL.

Set ‘Database engine’ to ‘PostgreSQL’ in the Deploy via Git site form

The form notes “A database and role will be created automatically. Manage them in pgAdmin.” Click Deploy. xCloud creates a database and role for the site and writes the connection to the site’s environment:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=<port>
DB_DATABASE=<site database>
DB_USERNAME=<site role>
DB_PASSWORD=<generated password>
DATABASE_URL=postgresql://<site role>:<generated password>@127.0.0.1:<port>/<site database>

The same choice is in the white-label site form. If Database engine does not appear, PostgreSQL is not Ready on the server yet, or the app type is not PHP App, Laravel or Node.js.

Restart PostgreSQL and read its logs

Once PostgreSQL shows Ready, you can restart it and read its logs from the dashboard. Restarting needs permission to manage the server’s services; reading the log needs permission to view the server’s logs.

Check its health

Open your server and go to ‘Management’ → ‘Settings’. Under Ready, the PostgreSQL row shows a health badge and the time of the last check:

Badge Meaning
Healthy PostgreSQL is running and accepts connections
Unhealthy The container runs, but PostgreSQL does not accept connections
Not running The PostgreSQL container is stopped
Unknown xCloud has not checked it yet, or could not reach the server

When PostgreSQL stays down, xCloud tries to restart it on its own and emails your team about it.

Restart PostgreSQL

  1. On the PostgreSQL row, click Restart.

    Click ‘Restart’ on the PostgreSQL row in Management → Settings

  2. A Restart PostgreSQL? panel opens under the row: “Restarts the PostgreSQL container. Sites using it lose their database connection for a few seconds.” Click Restart postgresql to confirm, or Cancel.

    Click ‘Restart postgresql’ in the ‘Restart PostgreSQL?’ panel to confirm

xCloud restarts the PostgreSQL container and checks that it accepts connections again. This takes a few seconds, and the row stays Ready. If a message appears under the row instead:

  • “PostgreSQL was restarted a moment ago. Try again in a minute.” Only one restart runs per minute. Wait, then try again.
  • “A site that uses PostgreSQL is still being set up. Try again when it has finished.” Wait for the new site to finish deploying.
  • “PostgreSQL could not be restarted. Check the task output.” Read the PostgreSQL log below for the cause, then try again.

Read the PostgreSQL log

Go to ‘Monitoring’ → ‘Logs’ and pick PostgreSQL Log in the log type list. The page shows the latest lines from the PostgreSQL container, newest first. Click Reload to fetch new lines.

Pick ‘PostgreSQL Log’ in the log type list in Monitoring → Logs

xCloud hides passwords and other secrets in these lines. The PostgreSQL log has no Download or Clear button. PostgreSQL Log appears in the list only while PostgreSQL is Ready on the server.

Limits to know

Area What happens with PostgreSQL
Services per server One managed PostgreSQL, shared by every PostgreSQL site on the server
Server stack Nginx only, with Docker Engine 28 or newer
Site types Native Git sites: PHP App, Laravel and Node.js
Backups Site backups include the PostgreSQL database and restore it in place, into the same site only: see Back up and restore PostgreSQL
Clone, migrate, staging, snapshots Not supported for PostgreSQL sites yet
Deleting a site The site’s database and role are kept
Disabling pgAdmin Nothing is deleted. Databases created in pgAdmin move to the xcloud_pg_owner role

The site’s Backup pages say Backups include this site’s PostgreSQL database. when a backup destination saves it. For MySQL databases, see Create a database for your site.

Disable pgAdmin

To remove pgAdmin, click Disable pgAdmin on the card in ‘Management’ → ‘Database’ and confirm. xCloud removes pgAdmin and moves the databases you created there to xcloud_pg_owner. PostgreSQL and your sites keep running. If disabling fails, the card lists the affected databases and offers Retry.

Install PostgreSQL with the Public API or MCP

You can run the same install from a script or an AI agent. The xCloud Public API has three endpoints for managed PostgreSQL, and the xCloud MCP server offers the same three as tools. They start the same install as the dashboard, so the server’s Server Utilities list shows the same status. pgAdmin is not in the API: enable it from the dashboard as in Step 3.

Task Public API MCP tool
Check whether the server can have PostgreSQL, and its install status GET /api/v1/servers/{uuid}/postgresql servers_postgresql_show
Install PostgreSQL POST /api/v1/servers/{uuid}/postgresql servers_postgresql_install
Retry a failed install POST /api/v1/servers/{uuid}/postgresql/retry servers_postgresql_retry

You need an API token with read:servers to check the status and write:servers to install or retry. All three, including the status check, also need your team role to manage the server’s services, the same permission the dashboard asks for.

The general services endpoint (POST /api/v1/servers/{uuid}/services/install, MCP tool servers_services_install) cannot install PostgreSQL. If you ask it to, it answers with a pointer to the PostgreSQL endpoint above.

Check the server first

Send a GET request with the server’s UUID. It changes nothing.

export XCLOUD_TOKEN='YOUR_API_TOKEN'
export SERVER_UUID='9a1f0c2e-4b7d-4e8a-9c3f-1d2e3f4a5b6c'

curl "https://app.xcloud.host/api/v1/servers/$SERVER_UUID/postgresql" \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json'

Expected result: a 200 response. On a server that can install PostgreSQL and doesn’t have it yet:

{
  "success": true,
  "message": "Success",
  "data": {
    "status": null,
    "message": null,
    "can_install": true,
    "can_retry": false,
    "reason": null
  }
}
Field Meaning
status null when PostgreSQL is not installed, then queued, installing, ready or failed
message Why the install failed, when status is failed
can_install true when you can start an install now
can_retry true when a failed install can be retried now
reason Why this server can’t have managed PostgreSQL right now, or null when it can

When can_install is false and status is null, reason tells you why, for example “Managed PostgreSQL is only available on Nginx servers.” Fix that before you install.

Install and wait for ready

Send a POST request to the same path:

curl --request POST "https://app.xcloud.host/api/v1/servers/$SERVER_UUID/postgresql" \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json'

Expected result: 202 with status set to queued and the message “PostgreSQL installation queued. Poll GET /postgresql until status is ready or failed.” Repeat the GET request from the step above every few seconds until status is ready or failed.

If the server already has managed PostgreSQL, the request queues nothing and returns 200 with the current status, for example “PostgreSQL is already ready on this server.” Sending the install request twice is therefore safe.

Retry a failed install

When status is failed, read message, fix the cause (for example, upgrade Docker Engine to 28 or newer), then retry:

curl --request POST "https://app.xcloud.host/api/v1/servers/$SERVER_UUID/postgresql/retry" \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json'

Expected result: 202 with status set to queued. Poll the status again. The retry works only when the status shows can_retry: true. Calling the install endpoint on a failed install does not start it again: it returns 200 with “The previous PostgreSQL installation failed. Use POST /postgresql/retry to try again.”

Ask an AI agent over MCP

In an MCP client connected to xCloud, ask in plain language:

Check whether my xCloud server docs-demo can run managed PostgreSQL. If it can,
install it and tell me when it is ready.

The agent runs servers_postgresql_show first, then servers_postgresql_install, and polls servers_postgresql_show until the status is ready or failed. Installing changes your server, so the agent asks you to confirm before it runs the install or a retry. On the compact MCP profile, it finds the servers.postgresql.install operation with search and runs it through xcloud_execute_destructive, which needs the same confirmation.

When the API refuses an install

Install and retry requests return 422 and queue nothing in these cases:

Message Cause Fix
“Managed PostgreSQL is only available on Nginx servers.” The server runs OpenLiteSpeed or another stack Use an Nginx server. See Available Server Stacks in xCloud
“A catalog PostgreSQL install already exists on this server. Managed installation is unavailable.” The server already runs the PostgreSQL one-click app Use that app, or install managed PostgreSQL on another Nginx server
“Server is not connected” xCloud can’t reach the server Reconnect the server, then try again
“There is no failed PostgreSQL installation to retry.” You called retry, but no install has failed Check the status. If status is null, install. If it is queued or installing, wait. If it is ready, nothing is needed.
“Another managed database operation is in progress. Try again shortly.” Another managed database task is running on the server Wait for it to finish, then try again

Other responses: 401 means the token is missing or revoked, 403 means the token lacks write:servers (or read:servers for the status) or your role can’t manage the server’s services, and 404 means the server UUID is not one you can access.

Frequently asked questions

Which servers can run managed PostgreSQL?

Nginx servers with Docker Engine 28 or newer. Each server runs one managed PostgreSQL service that every PostgreSQL site on it shares. OpenLiteSpeed servers cannot install it, and a server that already runs the PostgreSQL one-click app cannot add the managed service.

Are PostgreSQL databases included in xCloud site backups?

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. PostgreSQL sites cannot be cloned, migrated, staged or snapshotted yet.

To check your backups, restore, or export a database step by step, see How to Back Up and Restore a PostgreSQL Database in xCloud.

How do I restart PostgreSQL or see its logs?

Once PostgreSQL shows Ready, click Restart on its row in Management → Settings, then confirm. To read its logs, open Monitoring → Logs and pick PostgreSQL Log. Restarting needs permission to manage the server’s services.

See Restart PostgreSQL and read its logs for each screen.

Does deleting a PostgreSQL site delete its database?

No. xCloud keeps the site’s PostgreSQL database and role when you delete the site, and tells you so. Remove them in pgAdmin if you no longer need them.

If you run into any issues with managed PostgreSQL or pgAdmin, feel free to reach out to our support team.