Skip to content

Latest commit

 

History

History
58 lines (42 loc) · 4.43 KB

README.md

File metadata and controls

58 lines (42 loc) · 4.43 KB

@op/db Workspace

This workspace defines the database schema, manages migrations, and provides the database client for the application using Drizzle ORM with a PostgreSQL database, hosted and managed via Supabase.

Purpose

To provide a single source of truth for the database structure and a typed client for interacting with the database from other services and applications within the monorepo.

Structure

  • schema/: Contains the Drizzle schema definitions, defining tables, columns, relations, and types.
    • publicTables.ts: Exports tables intended for direct migration generation by drizzle-kit.
    • internalTables.ts: Exports tables potentially used internally but not directly included in auto-generated migrations.
    • index.ts: Exports all schema components (from both publicTables and internalTables) for use by the Drizzle client (./client.ts).
    • tables/: Contains the actual SQL table definitions (e.g., profiles.sql).
  • migrations/: Stores the SQL migration files generated by drizzle-kit (excluding index definitions).
  • customMigrations/: Stores custom SQL files, primarily containing CREATE INDEX statements extracted from the main migrations by the extractIndexes.ts script. These are applied separately by migrate.ts.
  • client.ts: Exports the configured Drizzle database client instance, using schemas from schema/index.ts.
  • tables.ts: Exports a helper object tables containing only the PgTable instances from the combined schema, useful for direct table access.
  • migrate.ts: Script executed to apply database migrations. It first runs standard migrations from migrations/ using Drizzle's migrator, then executes SQL statements from customMigrations/ individually (outside transactions). It targets the local development database by default and includes checks to prevent accidental production runs.
  • seed.ts: Script to populate the database with initial or test data.
  • scripts/extractIndexes.ts: A custom script that reads generated migration files in migrations/, moves any CREATE INDEX statements to customMigrations/0000_CUSTOM_indexes.sql, and removes them from the original migration files.
  • drizzle.config.ts: Configuration file for drizzle-kit, specifying schema/publicTables.ts as the input for migration generation.

Key exports (client, schema, tables) are defined in package.json.

Key Technologies

  • Drizzle ORM: TypeScript ORM for interacting with the database.
  • PostgreSQL: The underlying relational database (hosted on Supabase).
  • postgres: Node.js PostgreSQL client library used by Drizzle.
  • Supabase: Used for database hosting, storage (buckets created in migrate.ts), and provides CLI tools (supabase) for local development workflows (start, stop, reset, status).
  • drizzle-kit: CLI tool for managing Drizzle schemas and generating migrations based on schema/publicTables.ts.
  • tsx: For running TypeScript files directly (used in migration and seeding scripts).
  • dotenv: For loading environment variables (database connection strings from .env.local).

Relationship to Other Workspaces

Depends On:

  • @op/core: For configuration or shared types, specifically adminEmails used in seed.ts.

  • @op/typescript-config (Dev): Used for TypeScript configuration during development.

Depended On By:

  • @op/trpc: Uses the DB client and schema for API procedures.

Development & Workflow

  • Local Database: Use pnpm start (runs supabase start) to spin up the local Supabase development environment.
  • Schema Changes: Modify files in schema/tables/*.sql and update exports in schema/publicTables.ts or schema/internalTables.ts.
  • Generate Migrations: Run pnpm generate after schema changes. This runs drizzle-kit generate (based on publicTables.ts) and the custom extractIndexes.ts script (which moves index statements to customMigrations/).
  • Apply Migrations: Run pnpm migrate to apply pending migrations from migrations/ and customMigrations/ to the configured database (local development database by default).
  • View Schema: Use pnpm studio (runs drizzle-kit studio) to browse the schema visually.
  • Seeding: Run pnpm seed to populate the database.
  • Reset Local DB: Use pnpm reset (runs supabase db reset) to completely reset the local Supabase database.
  • Lint: Run pnpm lint.