Guide / Deploy Next.js with PostgreSQL
Deploy Next.js with PostgreSQL: dev, staging, prod
Updated
A Next.js app with a database needs more than one place to run. You want somewhere to try changes, somewhere a client or teammate can review them, and a production environment that nobody touches by accident. Each one needs its own database and its own secrets. Every Resilis project comes with three environments: development, staging and production. This guide sets up one Next.js app across all three, each with a private PostgreSQL database. Then it shows how a change moves from one to the next.
The shape of the setup
| Development | Staging | Production | |
|---|---|---|---|
| Git branch | develop | staging | main |
| Database | PostgreSQL, disposable data | PostgreSQL, realistic test data | PostgreSQL, real data |
| DATABASE_URL | Secret, dev database | Secret, staging database | Secret, production database |
| Delete or stop, by a person | Direct (deletion asks you to type the name) | Direct (deletion asks you to type the name) | Emailed owner approval |
| Delete, by an agent | Prepared, then a person approves | Prepared, then a person approves | Prepared, then emailed owner approval |
| Point-in-time restore | Optional | Optional | Turn on (Pro) |
Within one app, each environment follows its own stable branch. A branch can target only one environment of the same app, so a push to develop can never redeploy production.
Prepare the Next.js app
Build a standalone server
Next.js can produce a minimal server that carries only the files it needs. Turn it on in next.config.js:
JavaScript
// next.config.js
module.exports = {
output: 'standalone',
}; The standalone server does not copy public or .next/static by default. Copy them in the image, as the Dockerfile below does. The server reads PORT and HOSTNAME; set HOSTNAME=0.0.0.0 so it accepts requests from outside the container.
Dockerfile
FROM node:22-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:22-slim
WORKDIR /app
ENV NODE_ENV=production HOSTNAME=0.0.0.0 PORT=3000
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"] Add a .dockerignore that excludes .env*, node_modules and .next. Next.js copies .env and .env.production into the standalone output if the build loads them, so keep secrets out of the build context altogether.
This guide uses the Dockerfile route, which keeps the standalone build explicit.
Keep environment-specific values out of the browser bundle
This is the Next.js detail that breaks multi-environment setups. Variables prefixed with NEXT_PUBLIC_ are inlined into the JavaScript bundle at build time. After the build, the app no longer responds to changes in those variables.
Two rules keep three environments honest:
- 1. Secrets never get the NEXT_PUBLIC_ prefix. DATABASE_URL is read only on the server.
- 2. Read per-environment values on the server at request time. Server code that reads process.env during dynamic rendering sees the runtime value. If the browser needs a value, serve it from a route handler or pass it down from a server component.
If a value genuinely has to reach the browser bundle, treat it as part of the build: check in your development environment that the built app shows the value you expect before you promote the change.
Read the database on the server
TypeScript
// lib/db.ts
import { Pool } from 'pg';
export const pool = new Pool({ connectionString: process.env.DATABASE_URL }); Use it from server components, server actions or route handlers only. Run migrations with your tool of choice as a separate step, described below.
Create the three databases
In your project, open each environment in turn and select Create Database. Choose PostgreSQL 17 and keep public network access off. When the database shows Running, open Connections, choose Internal and copy the connection URI. Keep the value private.
The Node.js and PostgreSQL guide records these screens step by step.
Three databases cost three database service fees ($5 per month each on Hobby, $10 on Pro, prorated hourly) plus their CPU, RAM and disk. For development, a small database is enough. You can delete a development or staging database directly from the dashboard after confirming its name; production deletions wait for an owner's approval.
Deploy the development instance
Create the app from your GitHub repository in the development environment:
- 1. Select the repository and the develop branch. Set the app root to . unless the app lives in a subfolder.
- 2. Choose Dockerfile and keep the path at Dockerfile.
- 3. Add DATABASE_URL with the Secret option on, and paste the internal URI of the development database. Add PORT=3000.
- 4. Deploy, wait for Running, and open the app.
Check a page that reads from the database, then create a record. A green build alone does not prove the database connection works.
If you work from a coding agent instead, the same result comes from databases.create and databases.bind over MCP. The bind keeps the connection string out of the agent's context. See deploying from Claude Code.
Add staging and production from the same app
Create the staging instance from the same repository with the staging branch, and the production instance with main. When you create an instance for an app that already exists, you can inherit its configuration from an existing instance. Inheriting environment variables and secrets is a separate, explicit choice.
For DATABASE_URL, do not inherit. Set it per environment to that environment's own database. A staging instance pointing at the production database is the most expensive typo in this setup.
Before you deploy each instance, check three things: the environment name, the branch, and which database the app is bound to.
Move a change from development to production
The workflow is plain Git:
- 1. Merge a feature into develop. If the repository webhook and branch trigger are configured, the development instance redeploys.
- 2. Test it in development. Run migrations against the development database first.
- 3. Merge develop into staging. The staging instance redeploys. This is where a client or reviewer signs off.
- 4. Merge staging into main. Production redeploys.
Pull request previews can sit alongside this. When previews are on for a stable branch, pull requests targeting that branch get their own preview, which inherits that environment's configuration. Point previews at development or staging data, not production.
Run migrations per environment
Run each environment's migrations against its own database, in order: development, then staging, then production. Run them as a separate step rather than inside the server start command, so a failed migration does not crash-loop the app.
From a connected agent, deployments.release.run runs a command such as ["npx", "prisma", "migrate", "deploy"] with the current deployment's exact image and bound DATABASE_URL, with its own timeout and logs. Prisma's own guidance is to use migrate deploy, never migrate dev, outside development.
Write migrations that the previous release can still run against. That keeps rollback available: rolling back the app selects an earlier release, but it does not undo a migration.
What production adds
Production runs the same build as staging, with three extra protections:
- Rollback on every deploy. Each deploy keeps the previous release, ready to restore from the dashboard or by an agent.
- Approval for destructive actions. Deleting or stopping a production resource sends an approval email to the organization's account owners. Nothing happens until an owner signs in and approves.
- Point-in-time restore. On Pro and Enterprise, turn on continuous backups for the production database. You can then restore it to a chosen minute inside the retention window. See recovering from a bad Postgres migration.
Add your custom domain to the production instance. Hobby includes 5 custom domains and Pro includes 10.
Frequently asked questions
How do I give Next.js different environment variables for staging and production? Set them per environment instance in Resilis. Read them on the server at request time. Avoid NEXT_PUBLIC_ for anything that changes between environments, because those values are inlined at build time.
Should staging share the production database? No. Give each environment its own database and its own DATABASE_URL secret. Copy sanitized data into staging if reviewers need realistic records.
Can I use one Docker image for all three environments? Next.js supports one image promoted through environments if per-environment values are read at runtime on the server. On Resilis, each environment builds from its own branch, which avoids the frozen NEXT_PUBLIC_ problem.
Do I need Vercel-specific features like ISR or the image service? This guide runs Next.js as a Node.js server in a container. Test any feature that depends on a specific hosting platform in development before relying on it.
What does three environments cost? Each environment's app and database are billed by usage against your plan credit. The billing docs show a worked example for one app and one database.