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:
|Pool connection options that will be passed to Drizzle and |
|Disable Drizzle's |
|Customize the directory that migrations are stored.|
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:
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.
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
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.
Migrations are extremely powerful thanks to the seamless way that Payload and Drizzle work together. Let's take the following scenario:
pushenabled, so every time you change your Payload config (add or remove fields, collections, etc.), Drizzle will automatically push changes to your local DB.
npm run payload migrate:create.
npm run payload migrateagainst your production database, which will apply any new migrations that have not yet run.