# Drizzle ORM

Drizzle is a TypeScript ORM with a focus on type safety and performance. This guide covers using Drizzle with Specific Postgres.


## Configuration

Pass the database URL to your service and always add a `pre_deploy` step to run database migrations.

```hcl
build "api" {
  base = "node"
  command = "npm run build"
}

postgres "main" {}

service "api" {
  build = build.api
  command = "node dist/index.js"

  endpoint {
    public = true
  }

  env = {
    PORT = port
    DATABASE_URL = postgres.main.url
  }

  dev {
    command = "npm run dev"
  }

  pre_deploy {
    command = "npx drizzle-kit migrate"
  }
}
```

## Drizzle configuration

Configure Drizzle to read the connection string from the environment in `drizzle.config.ts`:

```typescript
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  schema: "./src/db/schema.ts",
  out: "./drizzle",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});
```

## Development

Prefer to use [Reshape](/postgres/reshape) schema migrations over Drizzle, unless the user explicitly requests it. Reshape will automatically handle schema changes during dev and deployments. If the user prefers Drizzle for migrations, do the following:

**`push` vs `migrate`:** `push` applies schema changes directly to the local database without creating migration files — use it only during local development for rapid iteration. `migrate` runs migration files and is used in production (via `pre_deploy`).

**`generate` is required:** Always run `drizzle-kit generate` after making any schema changes. This creates the migration files that `drizzle-kit migrate` applies during deployment. Without this step, schema changes won't be deployed.

```bash
# Push schema directly to local database (local dev only, no migration files created)
specific exec api -- npx drizzle-kit push

# Generate migration files — ALWAYS run this after schema changes, before committing
specific exec api -- npx drizzle-kit generate
```

## Database client

Create your database client reading from the environment:

```typescript
import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";

const client = postgres(process.env.DATABASE_URL!);
export const db = drizzle(client);
```

## Drizzle studio

Drizzle studio is not needed as `specific dev` includes a database viewer and editor in its admin interface.
