# NeonDB
URL: /docs/features/database/neondb

Learn how to setup and use NeonDB and Drizzle ORM.

<FeatureExclusiveFor repos={["vercel-monorepo", "cli-monorepo"]} />

## Setup

If you're using the [Vercel Monorepo](/docs/picking-a-template/vercel-monorepo) or [CLI Monorepo](/docs/picking-a-template/cli-monorepo) template, the `@workspace/drizzle` package is setup with [NeonDB](https://neon.com/) 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:

```txt title="Example NeonDB connection 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
```

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`

```txt title="/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:

```bash title="/packages/drizzle"
rm -rf ./.drizzle
```

Then generate fresh migrations based on your current schema:

```bash title="/packages/drizzle"
pnpm run migrate:generate
```

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

```bash title="/packages/drizzle"
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

<Callout title="Important" type="warn">
  Disclaimer: The following documentation assumes that you already have [Docker](https://www.docker.com/) installed on your local environment.
</Callout>

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

```bash title="/"
docker compose up -d
```

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

```txt title=".env"
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.