Deploy PostgreSQL

Deploy and Host PostgreSQL with Railway

PostgreSQL is the world's most advanced open-source relational database. This template deploys a single-node PostgreSQL 18 server with a persistent volume, five widely-used contrib extensions preinstalled on first boot, and a pgAdmin web UI that ships pre-wired to the database.

> 🔄 Actively maintained — latest update 2026-10-28: PostgreSQL upgraded to 18.6 (from 17.11). The dated change history lives in this repository's CHANGELOG.md.

About Hosting PostgreSQL

Hosting PostgreSQL on Railway runs the official postgres:18.6-alpine image (plus a thin extension layer) as a private-network service with a persistent volume at /var/lib/postgresql/data. Data survives redeploys and restarts. The superuser password is auto-generated at deploy time via Railway's secret() function, and a DATABASE_URL variable is composed from the service's private hostname so other services in the same project can connect with a single reference — no public exposure required.

Extensions pgcrypto, pg_trgm, unaccent, citext, and uuid-ossp are created on first boot into your database and into template1, so databases created later inherit them too.

A bundled pgAdmin service gives you a browser UI for the database in one click: generate a public domain on the pgadmin service, open it, and sign in as admin@template.local with the generated password. The PostgreSQL server is already registered inside pgAdmin — including its stored credentials — so the browser tree connects immediately; no manual host or password entry.

Login credentials

pgAdmin web UI (the only service meant to be public):

PostgreSQL itself has no login screen: it is private-network only (no public domain), and connects with user app + the generated POSTGRES_PASSWORD variable (postgres service → Variables). pgAdmin already has both stored — you never need to type them.

> Both passwords are generated fresh at deploy time via ${{secret(20)}}. PGADMIN_DEFAULT_PASSWORD applies on pgAdmin's first boot only; change it inside pgAdmin afterwards. POSTGRES_USER/POSTGRES_DB defaults (app/app) are baked into the image.

This is a single-node deployment without replication — the building block most self-hosted apps need. For automated failover and a streaming read replica, see our Postgres HA Read Replica template instead.

Why Deploy PostgreSQL on Railway?

• One platform: host your database next to your apps, APIs, and AI agents with private networking between them.
• Zero-config secrets: the superuser password is generated at deploy time; nothing is hardcoded.
• Admin UI included: pgAdmin ships pre-registered with the database and its credentials.
• Persistent by default: the data volume is attached out of the box.
• Scale when needed: vertical scaling takes seconds; no cluster YAML required.

Common Use Cases

• Backend database for self-hosted web apps and APIs (works out of the box with our Paperclip and Multica templates).
• Trigram search (pg_trgm) for search features without extra infrastructure.
• UUID-primary-key schemas via pgcrypto / uuid-ossp.
• Scratch/analytics database for agents and cron jobs on the private network.

Dependencies for PostgreSQL Hosting

• Docker image: postgres:18.6-alpine (official, pinned)
• Extensions: PostgreSQL contrib — pgcrypto, pg_trgm, unaccent, citext, uuid-ossp

Deployment Dependencies

• Source: https://github.com/postgres/postgres (upstream)
• Image source of truth: this repository's Dockerfile
• Docs: https://www.postgresql.org/docs/18/

Environment Variables

pgAdmin service

The pgAdmin login email is a fixed placeholder (admin@template.local — not a real inbox). Change it inside pgAdmin (File → Runtime Configuration → user management) if you keep the service running.

> Note: POSTGRES_USER / POSTGRES_DB / POSTGRES_PASSWORD only take effect on first boot, before any data exists — after that, manage users and databases with SQL.

Connect From Another Service

In the same Railway project, add a variable to your app service. With the defaults, compose:

DATABASE_URL = postgres://app:${{postgres.POSTGRES_PASSWORD}}@${{postgres.RAILWAY_PRIVATE_DOMAIN}}:5432/app

Traffic stays on Railway's private network (postgres.railway.internal). No public domain is generated for the database by default — keep it that way unless you have a specific need, and restrict any exposed domain accordingly. The pgAdmin service is the intended public window into the database: expose pgadmin, not postgres.

Local Setup

cp .env.example .env   # edit POSTGRES_PASSWORD
docker build -t wotonews/postgres:v18.6-1 .
docker run -d --name postgres -p 5432:5432 --env-file .env \
  -v pgdata:/var/lib/postgresql/data wotonews/postgres:v18.6-1
psql postgres://app:change-me@localhost:5432/app

Deploy to Railway

Deploy this template from the Railway marketplace, or from the repository root:

railway init --name my-postgres
railway add --service postgres
railway variables set POSTGRES_PASSWORD=$(openssl rand -hex 12)
railway deploy --image wotonews/postgres:v18.6-1
railway volume add --mount-path /var/lib/postgresql/data --service postgres

Backups

This template does not include managed backups. Use pg_dump over railway ssh on a schedule, or enable Railway's database backup features available on plans that include them.