NeonDB

Setup

If you're using the Vercel Monorepo or CLI Monorepo template, the @workspace/drizzle package is setup with NeonDB and Drizzle ORM out of the box.

To use NeonDB, you will need to create a new NeonDB database for your project, update your environment variables, then run migrations.

Create a new NeonDB database

In your NeonDB dashboard, create a new database with any name that you like. Once you've created the database, you will be sent to NeonDB's Project Dashboard page. On this page, you will find a button at the top right that says "Connect". Click on it, select the "Connection string" option, ensure that the "Connection pooling" option is selected, and copy the connection string to a separate file to use later.

You should see something like this:

postgresql://neondb_owner:my_password@ep-sweet-frog-aerm7yqw-pooler.c-2.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require

Ensure that the connection string you copy is the raw, password-included version, and contains "pooler" in the hostname.

Then, we recommend creating new database branches for staging (i.e. preview) and local environments. You can do this simply by going to the "Branches" page in the NeonDB dashboard, and clicking on the "Create branch" button.

Save these connection strings in a separate txt file, as you will need these as well.

Update environment variables

Next, we will need to update your local environment variables to include the connection string for your NeonDB branch that you've created for your local environment. Open and edit the .env files in the following locations:

1. /apps/web/.env
2. /packages/drizzle/.env

DATABASE_URL="postgresql://neondb_owner:my_password@ep-sweet-frog-aerm7yqw-pooler.c-2.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require"

Run migrations

Lastly, you will need to ensure that your NeonDB branch contains the latest schema. Since your NeonDB database should be new and empty, you can first delete the existing migrations in the @workspace/drizzle package:

rm -rf ./.drizzle

Then generate fresh migrations based on your current schema:

pnpm run migrate:generate

Finally, run the migrations to apply them to your database:

pnpm run migrate:apply

You do not need to run migrations for your staging and production NeonDB branches, because we will have these automatically run during your deployments to Vercel later on.

Using Docker for development

We recommend using NeonDB branches for your local development so that you can make use of NeonDB's branches feature; however, it can be handy to setup a local Postgres instance instead if you want to work while offline.

For this, you can run the following command in the root of your project to create your local Postgres instance at localhost:5432:

docker compose up -d

Then in the .env files above, update the DATABASE_URL environment variables to be as follows:

DATABASE_URL="postgres://postgres:postgres@db.localtest.me:5432/main"

Finally, ensure that your local database has the latest schema by running the migration commands above once more.