Postgres

To use Payload with Postgres, install the package @payloadcms/db-postgres. It leverages Drizzle ORM and node-postgres to interact with a Postgres database that you provide.

It automatically manages changes to your database for you in development mode, and exposes a full suite of migration controls for you to leverage in order to keep other database environments in sync with your schema. DDL transformations are automatically generated.

To configure Payload to use Postgres, pass the postgresAdapter to your Payload config as follows:

1import { postgresAdapter } from '@payloadcms/db-postgres'
2
3export default buildConfig({
// Your config goes here
collections: [
  // Collections go here
],
// Configure the Postgres adapter here
db: postgresAdapter({
  // Postgres-specific arguments go here.
  // `pool` is required.
  pool: {
    connectionString: process.env.DATABASE_URI,
  }
}),
16})

Options

Option	Description
`pool` *	Pool connection options that will be passed to Drizzle and `node-postgres`.
`push`	Disable Drizzle's `db push` in development mode. By default, `push` is enabled for development mode only.
`migrationDir`	Customize the directory that migrations are stored.
`logger`	The instance of the logger to be passed to drizzle. By default Payload's will be used.
`schemaName`	A string for the postgres schema to use, defaults to 'public'.
`localesSuffix`	A string appended to the end of table names for storing localized fields. Default is '_locales'.
`relationshipsSuffix`	A string appended to the end of table names for storing relationships. Default is '_rels'.
`versionsSuffix`	A string appended to the end of table names for storing versions. Defaults to '_v'.

Access to Drizzle

After Payload is initialized, this adapter will expose the full power of Drizzle to you for use if you need it.

You can access Drizzle as follows:

1payload.db.drizzle

Tables, relations, and enums

In addition to exposing Drizzle directly, all of the tables, Drizzle relations, and enum configs are exposed for you via the payload.db property as well.

Tables - payload.db.tables
Enums - payload.db.enums
Relations - payload.db.relations

Prototyping in development mode

Drizzle exposes two ways to work locally in development mode.

The first is db push, which automatically pushes changes you make to your Payload config (and therefore, Drizzle schema) to your database so you don't have to manually migrate every time you change your Payload config. This only works in development mode, and should not be mixed with manually running migrate commands.

You will be warned if any changes that you make will entail data loss while in development mode. Push is enabled by default, but you can opt out if you'd like.

Alternatively, you can disable push and rely solely on migrations to keep your local database in sync with your Payload config.

Migration workflows

Migrations are extremely powerful thanks to the seamless way that Payload and Drizzle work together. Let's take the following scenario:

You are building your Payload config locally, with a local database used for testing.
You have left the default setting of push enabled, so every time you change your Payload config (add or remove fields, collections, etc.), Drizzle will automatically push changes to your local DB.
Once you're done with your changes, or have completed a feature, you can run npm run payload migrate:create.
Payload and Drizzle will look for any existing migrations, and automatically generate all SQL changes necessary to convert your schema from its prior state into the state of your current Payload config, and store the resulting DDL in a newly created migration.
Once you're ready to go to production, you will be able to run npm run payload migrate against your production database, which will apply any new migrations that have not yet run.
Now your production database is in sync with your Payload config!

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.