Integrating Drizzle ORM into a Turborepo Monorepo: A Complete Guide

Introduction

Modern web applications often require sophisticated architecture to manage complexity and scale efficiently. Turborepo monorepos have emerged as a powerful solution for managing multiple packages and applications within a single repository, while Drizzle ORM is gaining popularity as a lightweight, type-safe SQL ORM for TypeScript. Combining these technologies creates a robust foundation for building scalable, maintainable applications.

This comprehensive guide will walk you through integrating Drizzle ORM into a Turborepo monorepo structure. You'll learn how to set up shared database packages, manage migrations across environments, and implement efficient development workflows. By the end of this tutorial, you'll have a fully functional monorepo with type-safe database access across all your applications and packages.

What You'll Learn

Setting up a Turborepo monorepo with a shared database package
Configuring Drizzle ORM with PostgreSQL
Creating a type-safe schema and query builder
Managing database migrations in a monorepo context
Implementing repository patterns for clean data access
Setting up efficient development workflows with Docker
Handling environment-specific configurations
Testing database code within the monorepo structure

Let's dive in!

Prerequisites

Before we begin, make sure you have the following installed:

Node.js (v18+)
pnpm (v8+)
Docker and Docker Compose
Basic understanding of TypeScript, Turborepo, and SQL concepts

Part 1: Setting Up Your Turborepo Monorepo

First, let's create a new Turborepo project:

npx create-turbo@latest drizzle-turbo-project
cd drizzle-turbo-project

This will set up a basic Turborepo structure. Now, let's customize it for our needs.

Monorepo Structure

We'll organize our monorepo with the following structure:

drizzle-turbo-project/
├── apps/
│   ├── api/           # API service
│   └── web/           # Web application
├── packages/
│   ├── db/            # Shared database package
│   ├── eslint-config/ # ESLint configurations
│   └── tsconfig/      # TypeScript configurations
├── turbo.json         # Turborepo configuration
└── package.json       # Root package.json

Creating the Shared Database Package

Let's create a dedicated database package that other apps and packages can depend on:

mkdir -p packages/db
cd packages/db

Initialize the package:

pnpm init

Edit the packages/db/package.json file:

{
  "name": "@repo/db",
  "version": "0.0.0",
  "private": true,
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "files": [
    "dist/**"
  ],
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch",
    "lint": "eslint src/",
    "typecheck": "tsc --noEmit",
    "generate": "drizzle-kit generate:pg",
    "migrate": "tsx src/migrate.ts",
    "studio": "drizzle-kit studio"
  },
  "dependencies": {
    "dotenv": "^16.3.1",
    "drizzle-orm": "^0.28.6",
    "postgres": "^3.4.2"  
  },
  "devDependencies": {
    "@repo/eslint-config": "*",
    "@repo/tsconfig": "*",
    "@types/node": "^20.8.4",
    "drizzle-kit": "^0.19.13",
    "eslint": "^8.51.0",
    "tsup": "^7.2.0",
    "tsx": "^3.13.0",
    "typescript": "^5.2.2"
  }
}

Part 2: Installing and Configuring Drizzle ORM

Let's set up the shared database package with Drizzle ORM.

Installing Dependencies

First, install the necessary dependencies:

cd packages/db
pnpm install

Now, let's create the TypeScript configuration:

mkdir -p src

Create packages/db/tsconfig.json:

{
  "extends": "@repo/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

Create packages/db/tsup.config.ts:

import { defineConfig } from "tsup";

export default defineConfig({
  entry: ["src/index.ts"],
  format: ["cjs", "esm"],
  dts: true,
  clean: true,
  sourcemap: true,
});

Setting Up Drizzle ORM Configuration

Let's create the basic Drizzle configuration file:

mkdir -p src/config

Create packages/db/src/config/index.ts:

import { drizzle } from "drizzle-orm/postgres-js";
import { migrate } from "drizzle-orm/postgres-js/migrator";
import postgres from "postgres";
import * as dotenv from "dotenv";

dotenv.config({ path: "../../.env" });

// Database connection config
const connectionString = process.env.DATABASE_URL;

if (!connectionString) {
  throw new Error("DATABASE_URL environment variable is not set");
}

// Client for migrations and queries
export const migrationClient = postgres(connectionString, { max: 1 });

// Client for queries only
export const queryClient = postgres(connectionString);

// Drizzle ORM instance
export const db = drizzle(queryClient);

// Migration function
export async function runMigrations() {
  try {
    console.log("Running migrations...");
    
    const migrationDb = drizzle(migrationClient);
    
    await migrate(migrationDb, {
      migrationsFolder: "./drizzle",
    });
    
    console.log("Migrations completed successfully");
  } catch (error) {
    console.error("Migration failed:", error);
    throw error;
  }
}

Creating Database Schema

Now, let's define our database schema. First, create a directory for our schema:

mkdir -p src/schema

Create packages/db/src/schema/index.ts:

export * from "./users";
export * from "./posts";

Create packages/db/src/schema/users.ts:

import { pgTable, serial, text, varchar, timestamp } from "drizzle-orm/pg-core";
import { relations } from "drizzle-orm";
import { posts } from "./posts";

export const users = pgTable("users", {
  id: serial("id").primaryKey(),
  email: varchar("email", { length: 255 }).notNull().unique(),
  name: varchar("name", { length: 255 }),
  password: text("password").notNull(),
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at").defaultNow().notNull(),
});

export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts),
}));

Create packages/db/src/schema/posts.ts:

import { pgTable, serial, text, timestamp, integer } from "drizzle-orm/pg-core";
import { relations } from "drizzle-orm";
import { users } from "./users";

export const posts = pgTable("posts", {
  id: serial("id").primaryKey(),
  title: text("title").notNull(),
  content: text("content").notNull(),
  authorId: integer("author_id").references(() => users.id).notNull(),
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at").defaultNow().notNull(),
});

export const postsRelations = relations(posts, ({ one }) => ({
  author: one(users, {
    fields: [posts.authorId],
    references: [users.id],
  }),
}));

Creating Repository Pattern

Let's create a repository pattern for clean data access:

mkdir -p src/repositories

Create packages/db/src/repositories/base-repository.ts:

import { SQL, SQLWrapper } from "drizzle-orm";
import { db } from "../config";

export abstract class BaseRepository<T> {
  protected abstract table: any;

  async findAll(options?: {
    where?: SQLWrapper | SQL | undefined;
    limit?: number;
    offset?: number;
  }): Promise<T[]> {
    const { where, limit, offset } = options || {};
    let query = db.select().from(this.table);
    
    if (where) {
      query = query.where(where);
    }
    
    if (limit) {
      query = query.limit(limit);
    }
    
    if (offset) {
      query = query.offset(offset);
    }
    
    return query as unknown as T[];
  }

  async findById(id: number): Promise<T | undefined> {
    const [record] = await db
      .select()
      .from(this.table)
      .where(({ and, eq }) => eq(this.table.id, id))
      .limit(1);
      
    return record as unknown as T | undefined;
  }

  async create(data: Omit<T, "id" | "createdAt" | "updatedAt">): Promise<T> {
    const [record] = await db
      .insert(this.table)
      .values(data)
      .returning();
      
    return record as unknown as T;
  }

  async update(id: number, data: Partial<Omit<T, "id" | "createdAt" | "updatedAt">>): Promise<T | undefined> {
    const [record] = await db
      .update(this.table)
      .set({ ...data, updatedAt: new Date() })
      .where(({ and, eq }) => eq(this.table.id, id))
      .returning();
      
    return record as unknown as T | undefined;
  }

  async delete(id: number): Promise<T | undefined> {
    const [record] = await db
      .delete(this.table)
      .where(({ and, eq }) => eq(this.table.id, id))
      .returning();
      
    return record as unknown as T | undefined;
  }
}

Create packages/db/src/repositories/user-repository.ts:

import { eq } from "drizzle-orm";
import { BaseRepository } from "./base-repository";
import { users } from "../schema";
import { db } from "../config";

export interface User {
  id: number;
  email: string;
  name: string | null;
  password: string;
  createdAt: Date;
  updatedAt: Date;
}

export class UserRepository extends BaseRepository<User> {
  protected table = users;

  async findByEmail(email: string): Promise<User | undefined> {
    const [user] = await db
      .select()
      .from(users)
      .where(eq(users.email, email))
      .limit(1);
      
    return user as unknown as User | undefined;
  }
  
  async findWithPosts(id: number) {
    const result = await db.query.users.findFirst({
      where: eq(users.id, id),
      with: {
        posts: true,
      },
    });
    
    return result;
  }
}

Create packages/db/src/repositories/post-repository.ts:

import { eq } from "drizzle-orm";
import { BaseRepository } from "./base-repository";
import { posts } from "../schema";
import { db } from "../config";

export interface Post {
  id: number;
  title: string;
  content: string;
  authorId: number;
  createdAt: Date;
  updatedAt: Date;
}

export class PostRepository extends BaseRepository<Post> {
  protected table = posts;

  async findByAuthor(authorId: number): Promise<Post[]> {
    return db
      .select()
      .from(posts)
      .where(eq(posts.authorId, authorId));
  }
  
  async findWithAuthor(id: number) {
    const result = await db.query.posts.findFirst({
      where: eq(posts.id, id),
      with: {
        author: true,
      },
    });
    
    return result;
  }
}

Creating Main Index File

Create packages/db/src/index.ts:

// Export configuration
export * from "./config";

// Export schema
export * from "./schema";

// Export repositories
export { UserRepository, type User } from "./repositories/user-repository";
export { PostRepository, type Post } from "./repositories/post-repository";

Creating Migration Script

Create packages/db/src/migrate.ts:

import { runMigrations } from "./config";

// Run migrations programmatically
async function main() {
  try {
    await runMigrations();
    process.exit(0);
  } catch (error) {
    console.error("Migration failed:", error);
    process.exit(1);
  }
}

main();

Setting Up .env File

Create a .env file at the root of your project:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/drizzle_turbo_db

Creating Docker Compose for Local Development

Create a docker-compose.yml file at the root of your project:

version: '3'

services:
  postgres:
    image: postgres:15-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: drizzle_turbo_db
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Part 3: Generate Migrations and Set Up Drizzle Studio

Now that we have our schema defined, let's generate migrations:

Configure Drizzle Kit

Create packages/db/drizzle.config.ts:

import type { Config } from "drizzle-kit";
import * as dotenv from "dotenv";

dotenv.config({ path: "../../.env" });

if (!process.env.DATABASE_URL) {
  throw new Error("DATABASE_URL environment variable is not set");
}

export default {
  schema: "./src/schema/*.ts",
  out: "./drizzle",
  driver: "pg",
  dbCredentials: {
    connectionString: process.env.DATABASE_URL,
  },
} satisfies Config;

Generate Migrations

From the packages/db directory, run:

pnpm generate

This will create a drizzle directory with migration files based on your schema.

Running Migrations

Now, let's run the migrations:

pnpm migrate

Using Drizzle Studio

Drizzle Kit provides a built-in studio for database management:

pnpm studio

This will start Drizzle Studio on a local port (typically 4983), allowing you to inspect and manipulate your database schema and data.

Part 4: Integrating with Applications

Now let's set up the API service to use our database package:

Setting Up the API Service

Navigate to the API directory:

cd ../../apps/api

Update apps/api/package.json:

{
  "name": "@repo/api",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch --onSuccess \"node dist/index.js\"",
    "lint": "eslint src/",
    "start": "node dist/index.js",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@repo/db": "*",
    "cors": "^2.8.5",
    "dotenv": "^16.3.1",
    "express": "^4.18.2"
  },
  "devDependencies": {
    "@repo/eslint-config": "*",
    "@repo/tsconfig": "*",
    "@types/cors": "^2.8.15",
    "@types/express": "^4.17.19",
    "@types/node": "^20.8.4",
    "eslint": "^8.51.0",
    "tsup": "^7.2.0",
    "typescript": "^5.2.2"
  }
}

Install dependencies:

pnpm install

Create apps/api/src/index.ts:

import express from "express";
import cors from "cors";
import { UserRepository, PostRepository } from "@repo/db";

const app = express();
const port = process.env.PORT || 3001;

// Middleware
app.use(cors());
app.use(express.json());

// Initialize repositories
const userRepository = new UserRepository();
const postRepository = new PostRepository();

// Routes
app.get("/api/users", async (req, res) => {
  try {
    const users = await userRepository.findAll();
    res.json(users);
  } catch (error) {
    console.error("Error fetching users:", error);
    res.status(500).json({ error: "Internal server error" });
  }
});

app.get("/api/users/:id", async (req, res) => {
  try {
    const user = await userRepository.findById(Number(req.params.id));
    if (!user) {
      return res.status(404).json({ error: "User not found" });
    }
    res.json(user);
  } catch (error) {
    console.error("Error fetching user:", error);
    res.status(500).json({ error: "Internal server error" });
  }
});

app.post("/api/users", async (req, res) => {
  try {
    const { email, name, password } = req.body;
    const user = await userRepository.create({
      email,
      name,
      password, // In a real app, you would hash this password
    });
    res.status(201).json(user);
  } catch (error) {
    console.error("Error creating user:", error);
    res.status(500).json({ error: "Internal server error" });
  }
});

app.get("/api/posts", async (req, res) => {
  try {
    const posts = await postRepository.findAll();
    res.json(posts);
  } catch (error) {
    console.error("Error fetching posts:", error);
    res.status(500).json({ error: "Internal server error" });
  }
});

app.get("/api/posts/:id", async (req, res) => {
  try {
    const post = await postRepository.findById(Number(req.params.id));
    if (!post) {
      return res.status(404).json({ error: "Post not found" });
    }
    res.json(post);
  } catch (error) {
    console.error("Error fetching post:", error);
    res.status(500).json({ error: "Internal server error" });
  }
});

app.post("/api/posts", async (req, res) => {
  try {
    const { title, content, authorId } = req.body;
    const post = await postRepository.create({
      title,
      content,
      authorId,
    });
    res.status(201).json(post);
  } catch (error) {
    console.error("Error creating post:", error);
    res.status(500).json({ error: "Internal server error" });
  }
});

// Start server
app.listen(port, () => {
  console.log(`API server running at http://localhost:${port}`);
});

Part 5: Updating Turborepo Configuration

Let's update the Turborepo configuration to orchestrate our build and development workflow:

Edit turbo.json at the root of your project:

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "dev": {
      "dependsOn": ["^build"],
      "cache": false,
      "persistent": true
    },
    "lint": {},
    "typecheck": {},
    "generate": {
      "cache": false
    },
    "migrate": {
      "cache": false
    },
    "studio": {
      "cache": false
    }
  }
}

Part 6: Environment-specific Configurations

For different environments (development, staging, production), we can create environment-specific configuration files.

Create packages/db/src/config/environments.ts:

type Environment = "development" | "test" | "staging" | "production";

interface EnvironmentConfig {
  database: {
    ssl: boolean;
    maxConnections: number;
    idleTimeout: number;
  };
}

const configurations: Record<Environment, EnvironmentConfig> = {
  development: {
    database: {
      ssl: false,
      maxConnections: 10,
      idleTimeout: 30,
    },
  },
  test: {
    database: {
      ssl: false,
      maxConnections: 5,
      idleTimeout: 10,
    },
  },
  staging: {
    database: {
      ssl: true,
      maxConnections: 20,
      idleTimeout: 60,
    },
  },
  production: {
    database: {
      ssl: true,
      maxConnections: 50,
      idleTimeout: 120,
    },
  },
};

export function getConfig(): EnvironmentConfig {
  const env = (process.env.NODE_ENV || "development") as Environment;
  return configurations[env] || configurations.development;
}

Update packages/db/src/config/index.ts to use environment-specific configurations:

import { drizzle } from "drizzle-orm/postgres-js";
import { migrate } from "drizzle-orm/postgres-js/migrator";
import postgres from "postgres";
import * as dotenv from "dotenv";
import { getConfig } from "./environments";

dotenv.config({ path: "../../.env" });

// Get environment-specific configuration
const config = getConfig();

// Database connection config
const connectionString = process.env.DATABASE_URL;

if (!connectionString) {
  throw new Error("DATABASE_URL environment variable is not set");
}

// Client for migrations
export const migrationClient = postgres(connectionString, { 
  max: 1,
  ssl: config.database.ssl,
});

// Client for queries
export const queryClient = postgres(connectionString, {
  max: config.database.maxConnections,
  idle_timeout: config.database.idleTimeout,
  ssl: config.database.ssl,
});

// Drizzle ORM instance
export const db = drizzle(queryClient);

// Migration function
export async function runMigrations() {
  try {
    console.log("Running migrations...");
    
    const migrationDb = drizzle(migrationClient);
    
    await migrate(migrationDb, {
      migrationsFolder: "./drizzle",
    });
    
    console.log("Migrations completed successfully");
  } catch (error) {
    console.error("Migration failed:", error);
    throw error;
  }
}

Part 7: Running the Project

Now, let's run the project:

Start the PostgreSQL container:

docker-compose up -d

Build the database package:

cd packages/db
pnpm build

Run migrations:

pnpm migrate

Start the development environment from the root:

pnpm dev

This will start both the API and web applications, with the database package being watched for changes.

Part 8: Testing

Let's set up testing for our database package.

Install test dependencies:

cd packages/db
pnpm add -D vitest @vitest/coverage-v8 testcontainers pg-mem

Update packages/db/package.json to add test scripts:

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage"
  }
}

Create a test configuration file packages/db/vitest.config.ts:

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    environment: "node",
    include: ["src/**/*.test.ts"],
    coverage: {
      reporter: ["text", "json", "html"],
    },
  },
});

Let's create a test for our UserRepository:

mkdir -p src/repositories/__tests__

Create packages/db/src/repositories/__tests__/user-repository.test.ts:

import { describe, it, expect, beforeAll, afterAll } from "vitest";
import { PostgreSqlContainer } from "testcontainers";
import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";
import { migrate } from "drizzle-orm/postgres-js/migrator";
import { UserRepository } from "../user-repository";
import * as schema from "../../schema";

describe("UserRepository", () => {
  let container;
  let client;
  let db;
  let userRepository: UserRepository;

  beforeAll(async () => {
    // Start a PostgreSQL container
    container = await new PostgreSqlContainer()
      .withDatabase("test")
      .withUsername("test")
      .withPassword("test")
      .start();

    // Create database connection
    const connectionString = `postgres://${container.getUsername()}:${container.getPassword()}@${container.getHost()}:${container.getPort()}/${container.getDatabase()}`;
    client = postgres(connectionString);
    db = drizzle(client, { schema });

    // Run migrations
    await migrate(db, { migrationsFolder: "./drizzle" });

    // Initialize repository
    userRepository = new UserRepository();

    // Override the config module to use our test database
    const configModule = await import("../../config");
    configModule.db = db;
  }, 60000);

  afterAll(async () => {
    // Clean up
    await client.end();
    await container.stop();
  });

  it("should create a new user", async () => {
    const user = await userRepository.create({
      email: "test@example.com",
      name: "Test User",
      password: "password123",
    });

    expect(user).toBeDefined();
    expect(user.id).toBeDefined();
    expect(user.email).toBe("test@example.com");
    expect(user.name).toBe("Test User");
  });

  it("should find a user by email", async () => {
    const email = "find-by-email@example.com";
    
    await userRepository.create({
      email,
      name: "Email Test",
      password: "password123",
    });

    const user = await userRepository.findByEmail(email);

    expect(user).toBeDefined();
    expect(user?.email).toBe(email);
  });

  it("should update a user", async () => {
    const user = await userRepository.create({
      email: "update-test@example.com",
      name: "Before Update",
      password: "password123",
    });

    const updatedUser = await userRepository.update(user.id, {
      name: "After Update",
    });

    expect(updatedUser).toBeDefined();
    expect(updatedUser?.id).toBe(user.id);
    expect(updatedUser?.name).toBe("After Update");
    expect(updatedUser?.email).toBe(user.email);
  });

  it("should delete a user", async () => {
    const user = await userRepository.create({
      email: "delete-test@example.com",
      name: "Delete Test",
      password: "password123",
    });

    const deletedUser = await userRepository.delete(user.id);
    expect(deletedUser).toBeDefined();
    expect(deletedUser?.id).toBe(user.id);

    const foundUser = await userRepository.findById(user.id);
    expect(foundUser).toBeUndefined();
  });
});

Run the tests:

pnpm test

Part 9: CI/CD Setup

Let's create a GitHub Actions workflow for our CI/CD pipeline.

Create .github/workflows/ci.yml:

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: test_db
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'pnpm'

      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 8
          run_install: false

      - name: Create .env file
        run: |
          echo "DATABASE_URL=postgres://postgres:postgres@localhost:5432/test_db" > .env

      - name: Install dependencies
        run: pnpm install

      - name: Build packages
        run: pnpm build

      - name: Run migrations
        run: cd packages/db && pnpm migrate

      - name: Type check
        run: pnpm typecheck

      - name: Lint
        run: pnpm lint

      - name: Test
        run: cd packages/db && pnpm test

Conclusion

Congratulations! You've successfully set up a Turborepo monorepo with Drizzle ORM integration. This architecture provides several benefits:

Type Safety: Drizzle ORM generates TypeScript types based on your schema, giving you full type safety across your applications.
Code Sharing: The database package can be imported by any app or package in your monorepo, ensuring consistent data access patterns.
Performance: Turborepo's caching capabilities combined with Drizzle's efficient SQL operations result in excellent performance.
Developer Experience: The combination of Turborepo's task orchestration and Drizzle's schema-first approach creates a smooth development workflow.
Scalability: This architecture is designed to scale with your project, making it easy to add new apps or packages that share the same database layer.

From here, you can extend your monorepo by:

Adding authentication and authorization
Implementing GraphQL APIs
Creating shared UI components
Building admin dashboards
Setting up serverless functions

The foundational work you've done will make these additions much easier, as they can all leverage your shared database layer.