# 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.

**Verified** November 6, 2026

## What it runs on

- [Computeverified](/content/discover/primitive/compute/index.html)  
  Apps run in isolated x86_64 Firecracker microVMs; sizes are the priced VM sizes.

- [Postgresverified](/content/discover/primitive/postgres/index.html)  
  Managed PostgreSQL 16 with pgvector runs in its own microVM and is auto-provisioned when an app needs a database and no `DATABASE_URL` is supplied.

## You need

- 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`

## Exact tested configuration

- **build**  
npm run build --if-present
- **install**  
npm install
- **runtime**  
node
- **sizes**  
1vcpu-1gb
- **start**  
npm run start
- **template**  
node-22

## 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.

```
   $ ample deploy . --name <app-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.

```
   $ ample logs <deployment_id> --kind build
   ```

## How it was checked

✓ database route reports a live connection · `http get/api/db` → “postgres=ok”

## Evidence

1. November 6, 2026 · canary run  
   Next.js 15 route handler using pg with no `DATABASE_URL` supplied: Ample auto-provisioned a managed PostgreSQL database and `/api/db` reported `postgres=ok`.

2. November 6, 2026 · canary run  
   Node app needing PostgreSQL with no `DATABASE_URL`: a managed database was auto-provisioned and `/db` reported `postgres=ok`.

## Tested examples

- **Next.js + pg canary.** Route handler `/api/db` with an auto-provisioned managed database.

## What it doesn’t cover

- Verified on the node-22 template at s-1vcpu-1gb.
- Managed PostgreSQL 16 with pgvector.
- Apps and their managed databases are placed together, in the same region.
- The app is one long-lived process, so one connection pool serves every request.
