Connect Postgres for Express

Summary

Connect an Express app to PostgreSQL on Ample. Read DATABASE_URL at runtime: when you supply one with --env it is delivered encrypted and takes precedence; when you supply none and the app needs PostgreSQL, Ample auto-provisions a managed PostgreSQL 16 database and injects its connection string.

Infrastructure requirements

• Compute: verified (Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.)
• Postgres: verified (Managed PostgreSQL 16 runs in its own microVM and is auto-provisioned when an app needs a database and no DATABASE_URL is supplied.)

Prerequisites

• The pg driver reading process.env.DATABASE_URL
• Either a production DATABASE_URL to pass with --env, or nothing (auto-provision)
• An Ample account token with servers:write and databases:read

Exact tested configuration

• template: node-22
• runtime: node
• size: s-1vcpu-1gb
• install: npm install
• build: npm run build --if-present
• start: npm run start

Steps

1. Read the URL at runtime. Construct the pg Pool from process.env.DATABASE_URL inside the app; never commit credentials.
2. Choose the source of the database. Pass --env DATABASE_URL=... for an existing database, or omit it to let Ample provision a managed one on first deploy and reuse it on redeploys.

   ample deploy . --name <app-name> --public --env DATABASE_URL=postgres://...

3. Test the connection through the app. Expose a route that runs a trivial query and returns postgres=ok, then deploy and fetch it.
4. Verify. Fetch the live URL and run the success checks below. On failure read the build log, then the runtime log, fix the cause and deploy again; do not blind-retry.

   ample logs <deployment_id> --kind build

Tested examples

• Express + pg canary (tests/deploy-canaries/express-postgres-api): Auto-provisioned managed database with a real insert and count.
• Supplied DATABASE_URL (tests/deploy-canaries/env-database-url): An explicit connection string delivered as an encrypted environment variable.

Success checks

• database route reports a live connection (/items on the live URL, expect postgres=ok)

Limitations

• Verified on the node-22 template at s-1vcpu-1gb; other templates and sizes are not verified by this recipe.
• Region, compliance attestations and request-duration limits are unknown and not claimed.
• Apps auto-pause when idle and wake on the next request; always-on is an operator setting, not a plan feature.
• Managed PostgreSQL 16 only; extensions, connection limits and backup or restore procedures are not verified.
• Apps and their managed databases are placed together; cross-node shared databases are unsupported.
• A supplied URL is used as-is; Ample does not validate reachability of external databases before the release starts.

Cost estimate

Estimated 10.00 USD per month (size prices from pricing.toml at build revision a1b8c38919e59cd035ebabaced73cf84ece24371).

• app server x1 s-1vcpu-1gb: 5.00 USD
• managed PostgreSQL database x1 s-1vcpu-1gb: 5.00 USD

Apps and managed databases auto-pause when idle; the estimate is the always-on monthly price of the tested sizes. Plan quotas and budgets apply.

Verification evidence

• canary_run on 2026-09-19T23:55:33Z at revision 1764076-tls-account-903d345: Express REST API using pg with no DATABASE_URL supplied: Ample auto-provisioned a managed PostgreSQL 16 database, injected the connection string, and /items reported postgres=ok after a real insert and count. (expires 2027-03-18T23:55:33Z)
• canary_run on 2026-09-19T23:55:33Z at revision 1764076-tls-account-903d345: Node app needing PostgreSQL with no DATABASE_URL: a managed database was auto-provisioned and /db reported postgres=ok. (expires 2027-03-18T23:55:33Z)
• canary_run on 2026-09-19T23:55:33Z at revision 1764076-tls-account-903d345: A supplied DATABASE_URL was delivered as an encrypted environment variable; the app saw the configured host and the secret was never echoed by the platform. (expires 2027-03-18T23:55:33Z)

Last verified: 2026-09-19T23:55:33Z

Execution binding

MCP tool ample_deploy (registry mcp:ample_deploy), schema hash 876465fce906da0c observed 2026-09-20T01:55:48.667900+00:00 at revision 199ff1dfd526, binding state current, required scopes: servers:write, databases:read.