Drizzle ORM Documentation

Overview

This directory contains all documentation related to the Drizzle ORM migration for the Suitsbooks application. The migration from Supabase client to Drizzle ORM is complete and all database operations now use Drizzle while maintaining Supabase for authentication.

Quick Navigation

Getting Started

• Quick Start Guide - Start here! 5-minute setup guide
• Query Reference - Common query patterns and examples
• Schema Management - How to add and manage database tables

Detailed Information

• Migration Complete - Full migration details and overview
• Migrations Guide - Database migrations documentation

Documentation Files

1. quick-start.md

Read Time: 5 minutes

Essential guide to get up and running with Drizzle ORM. Covers:

• Environment setup
• Basic queries
• Service layer usage
• Common tasks
• FAQ

Start here if you're new to the project or Drizzle ORM.

2. query-reference.md

Read Time: 10 minutes

Comprehensive query reference guide. Covers:

• CRUD operations
• Complex queries
• Joins and relationships
• Raw SQL
• Migration from Supabase syntax
• Error handling
• Type safety
• Performance tips

Keep this open while coding for quick reference.

3. schema-management.md

Read Time: 10 minutes

Guide to managing database schema. Covers:

• Current schema limitations
• How to add new tables
• Common table patterns
• Known syntax errors
• Testing your schema
• Troubleshooting

Read this before adding tables to the schema.

4. migration-complete.md

Read Time: 15 minutes

Complete overview of the Drizzle migration. Covers:

• What was migrated
• Project structure
• Available commands
• Known issues
• Testing checklist
• Rollback plan
• Team coordination

Read this for full context of the migration.

Quick Reference

Essential Commands

# View database in browser
pnpm db:studio

# Generate migrations
pnpm db:generate

# Run migrations
pnpm db:migrate:run

# Push schema changes directly
pnpm db:push

# Start development server
pnpm dev
```typescript

### Basic Query Example

```typescript
import { db } from '@/src/db';
import * as schema from '@/src/schema';
import { eq } from 'drizzle-orm';

// Select
const users = await db.select()
  .from(schema.users)
  .where(eq(schema.users.email, 'user@example.com'));

// Insert
const newUser = await db.insert(schema.users)
  .values({ email: 'new@example.com', name: 'John Doe' })
  .returning();

// Update
await db.update(schema.users)
  .set({ name: 'Jane Doe' })
  .where(eq(schema.users.userId, 'user-id'));

// Delete
await db.delete(schema.users)
  .where(eq(schema.users.userId, 'user-id'));
```typescript

### Using Service Layer

```typescript
import { DrizzleService } from '@/lib/db/drizzle-service';

const service = new DrizzleService({
  companyId: user.company_id,
  organizationId: user.organization_id,
  userId: user.user_id,
});

// Fetch (with automatic tenant scoping)
const data = await service.fetchData('users', {
  conditions: [eq(schema.users.email, 'user@example.com')],
  limit: 10,
});
```typescript

---

## Learning Path

### For New Developers (15 minutes)
1. Read `quick-start.md` (5 min)
2. Skim `query-reference.md` (5 min)
3. Try a simple query (5 min)

### For Schema Work (25 minutes)
1. Read `quick-start.md` (5 min)
2. Read `schema-management.md` (10 min)
3. Read `migrations/MIGRATION_GUIDE.md` (10 min)

### For Complete Understanding (45 minutes)
1. Read `quick-start.md` (5 min)
2. Read `migration-complete.md` (15 min)
3. Read `query-reference.md` (10 min)
4. Read `schema-management.md` (10 min)
5. Browse `migrations/README.md` (5 min)

---

## Key Files in Project

```files
project/
├── src/
│   ├── db.ts
│   ├── schema.ts
│   └── schema.backup.ts
├── lib/
│   └── db/
│       └── drizzle-service.ts
├── migrations/
├── drizzle.config.ts
└── .env

Current Schema

The minimal schema includes these core tables:

• users - User accounts
• companies - Company information
• invoices - Invoice records
• customers - Customer data

Note: Only 4 core tables are defined. See schema-management.md for how to add more.

Common Tasks

I want to...

Query the database

• See query-reference.md
• Use db.select().from(schema.tableName)

Add a new table

• See schema-management.md
• Add to src/schema.ts
• Test with pnpm db:studio

Create a migration

• See migrations/MIGRATION_GUIDE.md
• Run pnpm db:generate
• Run pnpm db:migrate:run

Fix a schema error

• See schema-management.md section "Known Syntax Errors"
• Check src/schema.backup.ts for reference

Rollback changes

• See migration-complete.md section "Rollback Plan"
• Use git to revert code changes

Getting Help

Documentation

1. Check the relevant documentation file above
2. Search for your error in schema-management.md
3. Review code comments in lib/db/drizzle-service.ts

External Resources

• Drizzle ORM Documentation
• Drizzle GitHub
• Drizzle Discord
• PostgreSQL Documentation

Common Issues

• Schema errors: See schema-management.md
• Query errors: See query-reference.md
• Migration errors: See migrations/MIGRATION_GUIDE.md
• Connection errors: Check DATABASE_URL in .env

Important Notes

1. Authentication: Supabase Auth is unchanged. Only database queries use Drizzle.
2. Tenant Context: Always use DrizzleService for tenant-scoped operations.
3. Schema Limitations: Only 4 core tables defined. Add more as needed.
4. Data Safety: Same PostgreSQL database. No data migration needed.
5. Type Safety: TypeScript types are inferred from schema definitions.

Migration Status

Status: Complete
Date: November 23, 2025
Files Migrated: 15+
Action Files: 12+
Lines of Code: 2000+

Welcome to Drizzle ORM!

Start with quick-start.md and explore from there. Happy coding!