Connect Postgres for Next.js

Connect a Next.js app to PostgreSQL on Ample from a route handler. Read DATABASE_URL at request time (force-dynamic) with pg; with no DATABASE_URL supplied, Ample auto-provisions a managed PostgreSQL 16 database and injects its connection string as an encrypted environment variable.

Representative Queries

• Connect Postgres for Next.js
• Where can I host Connect Postgres built with Next.js?
• I need driver setup, connection settings, secret handling and a real connection test.

Prerequisites

• The pg driver in dependencies and a route handler that reads process.env.DATABASE_URL at request time
• Either a production DATABASE_URL to pass with --env, or nothing (auto-provision)
• An Ample account token with servers:write and databases:read

Workflow Steps

1. Keep the database out of the build
   Mark the route handler dynamic and open the client per request; next build must not need the database.
2. Deploy
   Omit DATABASE_URL to auto-provision, or pass --env DATABASE_URL=... to use an existing database.
   Command: ample deploy . --name --public
3. Test through the app
   Fetch the route; it should report postgres=ok after a real query.
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.
   Command: ample logs --kind build

Success Checks

• Database route reports a live connection
  • Kind: http_get
  • Path: /api/db
  • 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.
• Connection pooling across serverless-style invocations is not applicable; the app is one long-lived process.

Cost Estimate

• Currency: USD
• Monthly Amount: 10.0
• Components:
  • App server (s-1vcpu-1gb): $5.00/month
  • Managed PostgreSQL database (s-1vcpu-1gb): $5.00/month
• Note: 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.

Examples

• Next.js + pg canary
  Route handler /api/db with an auto-provisioned managed database.
  Source Ref: tests/deploy-canaries/next-postgres-basic

Formats

• HTML
• Markdown
• JSON

Next Actions

• Browse the catalog index
  Action ID: browse-catalog
• Search published recipes by intent, stack and constraints
  Action ID: search-recipes
• Prepare a side-effect-free deployment plan for an authorized project
  Action ID: plan:page:guides:next-js:database-connection
• Read the existing agent authentication setup
  Action ID: auth-setup
• Browse Next.js
  Action ID: browse:stack:framework-next-js
• Browse Connect app to database
  Action ID: browse:intent:connect-app-to-database
• Browse Relational records
  Action ID: browse:pattern:relational-records