@withmata/blueprints 0.2.0

package/blueprints/features/db-drizzle-postgres/BLUEPRINT.md

@@ -0,0 +1,596 @@
+# Database Blueprint — Drizzle ORM + PostgreSQL
+
+## Tier
+
+Feature
+
+## Status
+
+Complete.
+
+## Problem
+
+Setting up a structured database layer involves connection management, schema organization, migration workflows, and clean imports for consuming code. Getting the Drizzle Kit config, migration scripts, schema group organization, and project wiring right from scratch is error-prone and time-consuming.
+
+This blueprint creates a centralized database layer (`packages/db/` in monorepos, `src/db/` in single-repo apps) with opinionated patterns for schema organization, migration workflows, and clean consumption.
+
+## Blueprint Dependencies
+
+None. This blueprint is standalone and can be installed into any project.
+
+### Interaction with auth-better-auth
+
+If auth-better-auth was installed first, the database directory will already exist with an `auth` schema group. This blueprint merges into the existing structure — it does not overwrite auth files. See "Interaction with Auth Blueprint" section for details.
+
+---
+
+## Architecture
+
+### Core Pattern
+
+All database schemas live in a single shared package (`packages/db/`), organized into **schema groups** — subdirectories under `src/` that each represent a logical domain or database. Each group has its own Drizzle Kit config for independent migration generation, its own barrel export, and its own subpath export in `package.json`.
+
+Consuming packages import schemas via subpath exports (`@scope/db/core`) and create Drizzle client instances with `drizzle(new pg.Pool({...}), { schema })`.
+
+### Key Decisions
+
+- **One package, multiple schema groups** (required) — All database schemas live in `packages/db/`. Groups are subdirectories under `src/` (e.g., `src/core/`, `src/auth/`). This keeps all database-related code centralized while supporting multiple databases.
+
+- **Per-group drizzle.config.ts** (required) — Each group has its own config at `drizzle/<group>/drizzle.config.ts`. This supports separate databases per group (multi-db pattern) and avoids migration conflicts between unrelated schemas.
+
+- **Explicit schema file lists** (required) — `drizzle.config.ts` lists each schema file individually, NOT via globs or directory paths. Excludes `index.ts` barrel files to avoid import issues during `drizzle-kit generate`. When you add a new entity file, you must add it to the config's `schema` array.
+
+- **One file per domain entity** (required) — Each table gets its own file: enums at top, table definition, indexes, type exports at bottom. Follows ENGINEERING.md "feature-based structure".
+
+- **Barrel exports per schema group** (required) — Each group has `index.ts` that re-exports all entity files. Consuming packages import from the barrel: `import { users, articles } from "@scope/db/core"`.
+
+- **Subpath exports** (required) — `package.json` uses `"exports": { "./<group>": ... }` for clean cross-package imports. Each group gets its own entry point.
+
+- **Committed migrations** (required) — Generated SQL migration files live in `drizzle/<group>/` alongside the config and are committed to version control. This provides a clear audit trail of schema changes.
+
+- **UUID primary keys** (recommended) — Application tables use `uuid("id").primaryKey().defaultRandom()`. Auth tables use text IDs (generated by Better Auth). Configurable per project.
+
+- **Automatic timestamps** (recommended) — Every table includes `createdAt: timestamp().defaultNow()` and `updatedAt: timestamp().defaultNow().$onUpdate(() => new Date())`.
+
+- **Single database default** (recommended) — Blueprint starts with one database and one schema group. The multi-db pattern (separate `DATABASE_URL` per group) is documented and easy to adopt later.
+
+### Connection Patterns
+
+Two approaches for creating Drizzle client instances:
+
+**Option A — Client helper in db package (blueprint default):**
+```typescript
+// packages/db/src/core/client.ts
+import * as schema from "./index.js";
+const pool = new pg.Pool({ connectionString: env.CORE_DATABASE_URL });
+export const db = drizzle(pool, { schema });
+```
+Simpler. One connection per group. Good for single-server architectures. Consuming packages import `db` directly.
+
+**Option B — Client in each consuming app:**
+```typescript
+// apis/server/src/db/core.ts
+import * as schema from "@scope/db/core";
+const pool = new pg.Pool({ connectionString: env.CORE_DATABASE_URL });
+export const db = drizzle(pool, { schema });
+```
+Each app controls its own pool configuration (size, timeout). Better for multi-server setups. The auth blueprint uses this pattern.
+
+The blueprint generates Option A by default. Delete `client.ts` and adopt Option B if your architecture requires per-app pool control.
+
+---
+
+## Hard Requirements vs Recommended Defaults
+
+**Hard requirements:**
+- Drizzle ORM as the database library
+- PostgreSQL as the database
+- Centralized db directory (`packages/db/` in monorepo, `src/db/` in single-repo)
+
+**Recommended defaults — ask during scaffolding:**
+
+| Choice | Recommended | Alternatives |
+|---|---|---|
+| Schema group name | `"core"` | Any name: `"app"`, `"main"`, etc. |
+| Primary key type | UUID (`defaultRandom()`) | serial, CUID, ULID, text |
+| Include example entity | Yes | No (empty scaffold) |
+| Include seed script | Yes | No |
+| Include client helper | Yes (in db package) | No (per-app connections) |
+| Database per group | Single database (shared URL) | Separate database per group |
+
+---
+
+## Dependencies
+
+### npm packages
+
+**packages/db:**
+| Package | Version | Purpose |
+|---|---|---|
+| `drizzle-orm` | ^0.45.1 | Database ORM |
+| `dotenv` | ^16.4.5 | Env loading for drizzle configs and scripts |
+
+**packages/db (dev):**
+| Package | Version | Purpose |
+|---|---|---|
+| `drizzle-kit` | ^0.31.8 | Migration generation, execution, and Drizzle Studio |
+| `pg` | ^8.18.0 | PostgreSQL driver (node-postgres) |
+| `@types/pg` | ^8.16.0 | Type definitions for pg |
+| `tsx` | ^4 | Running seed scripts directly from TypeScript |
+| `typescript` | ^5.9 | TypeScript compiler |
+
+### Environment Variables
+
+| Variable | Where | Description |
+|---|---|---|
+| `{{GROUP_UPPER}}_DATABASE_URL` | `packages/db/.env` | PostgreSQL connection URL (e.g., `CORE_DATABASE_URL`) |
+
+---
+
+## Monorepo Wiring
+
+### DB Package (`packages/db/`)
+
+**`package.json` exports:**
+```json
+{
+  "exports": {
+    "./{{GROUP}}": {
+      "import": "./dist/{{GROUP}}/index.js",
+      "types": "./dist/{{GROUP}}/index.d.ts"
+    }
+  }
+}
+```
+
+**Scripts:**
+```json
+{
+  "build": "tsc -p tsconfig.json",
+  "typecheck": "tsc -p tsconfig.json --noEmit",
+  "clean": "rm -rf dist",
+  "{{GROUP}}:generate": "drizzle-kit generate --config ./drizzle/{{GROUP}}/drizzle.config.ts",
+  "{{GROUP}}:migrate": "drizzle-kit generate --config ./drizzle/{{GROUP}}/drizzle.config.ts && drizzle-kit migrate --config ./drizzle/{{GROUP}}/drizzle.config.ts",
+  "drizzle:studio:{{GROUP}}": "drizzle-kit studio --config ./drizzle/{{GROUP}}/drizzle.config.ts",
+  "seed": "tsx src/scripts/seed.ts"
+}
+```
+
+**File structure:**
+```
+packages/db/
+├── package.json
+├── tsconfig.json
+├── .env                        # DATABASE_URL(s)
+├── .env.example
+├── drizzle/
+│   └── {{GROUP}}/
+│       ├── drizzle.config.ts   # Drizzle Kit config
+│       ├── *.sql               # Generated migrations (committed)
+│       └── meta/               # Drizzle Kit snapshots (committed)
+└── src/
+    ├── {{GROUP}}/
+    │   ├── index.ts            # Barrel export
+    │   ├── client.ts           # Connection helper (optional)
+    │   └── example.ts          # Example entity (optional)
+    └── scripts/
+        └── seed.ts             # Seed script (optional)
+```
+
+### Root `package.json`
+
+```json
+{
+  "scripts": {
+    "db:generate": "turbo run {{GROUP}}:generate --filter={{SCOPE}}/db --no-cache",
+    "db:migrate": "turbo run {{GROUP}}:migrate --filter={{SCOPE}}/db --no-cache",
+    "db:studio": "turbo run drizzle:studio:{{GROUP}} --filter={{SCOPE}}/db --no-cache",
+    "db:seed": "turbo run seed --filter={{SCOPE}}/db --no-cache"
+  }
+}
+```
+
+### `turbo.json`
+
+```json
+{
+  "tasks": {
+    "{{GROUP}}:generate": { "cache": false },
+    "{{GROUP}}:migrate": { "cache": false }
+  }
+}
+```
+
+### Consuming App Pattern
+
+```typescript
+// Option A: Using the client helper
+import { db } from "{{SCOPE}}/db/{{GROUP}}/client";
+
+const users = await db.query.example.findMany();
+
+// Option B: Managing your own connection
+import * as schema from "{{SCOPE}}/db/{{GROUP}}";
+import { drizzle } from "drizzle-orm/node-postgres";
+import pg from "pg";
+
+const pool = new pg.Pool({ connectionString: env.DATABASE_URL });
+export const db = drizzle(pool, { schema });
+```
+
+---
+
+## Single-Repo Adaptation
+
+For standalone applications (Next.js, Node, Bun) without a monorepo, the core database patterns are identical — only file placement and wiring differ.
+
+### Path Mapping
+
+| Aspect | Monorepo | Single-Repo |
+|--------|----------|-------------|
+| DB code location | `packages/db/` (own package.json) | `src/db/` (directory in app) |
+| Import pattern | `import { x } from "@scope/db/core"` | `import { x } from "@/db/core"` or `#db/core` |
+| Package dependencies | `workspace:*` protocol | Direct — packages at root `package.json` |
+| TypeScript config | Extends `@scope/typescript-config/base.json` | Inherits from root `tsconfig.json` |
+| Drizzle config location | `packages/db/drizzle/<group>/drizzle.config.ts` | `drizzle/<group>/drizzle.config.ts` (project root) |
+| Schema paths in config | `./src/<group>/example.ts` (relative to `packages/db/`) | `./src/db/<group>/example.ts` (relative to root) |
+| `.env` location | `packages/db/.env` | `.env` or `.env.local` at project root |
+| Build step | Separate `tsc` in db package | Framework transpiles directly (no separate build) |
+| Scripts | Turbo wrappers in root package.json | Direct drizzle-kit calls in root package.json |
+| Task orchestration | Turbo tasks in `turbo.json` (`cache: false`) | N/A — no Turbo |
+
+### Single-Repo Scripts
+
+```json
+{
+  "scripts": {
+    "db:generate": "drizzle-kit generate --config ./drizzle/<group>/drizzle.config.ts",
+    "db:migrate": "drizzle-kit generate --config ./drizzle/<group>/drizzle.config.ts && drizzle-kit migrate --config ./drizzle/<group>/drizzle.config.ts",
+    "db:studio": "drizzle-kit studio --config ./drizzle/<group>/drizzle.config.ts",
+    "db:seed": "tsx src/db/scripts/seed.ts"
+  }
+}
+```
+
+### Single-Repo File Structure
+
+```
+<project-root>/
+├── src/db/
+│   ├── <group>/
+│   │   ├── index.ts            # Barrel export
+│   │   ├── client.ts           # Connection helper
+│   │   └── example.ts          # Example entity
+│   └── scripts/
+│       └── seed.ts             # Seed script
+├── drizzle/
+│   └── <group>/
+│       ├── drizzle.config.ts   # Drizzle Kit config
+│       ├── *.sql               # Generated migrations
+│       └── meta/               # Drizzle Kit snapshots
+├── .env                        # DATABASE_URL(s)
+└── package.json                # Scripts + dependencies at root
+```
+
+### What Stays the Same
+
+All core patterns are project-type-agnostic:
+- Drizzle ORM + PostgreSQL
+- Schema groups (directories for domain separation)
+- Per-group `drizzle.config.ts` with explicit file lists
+- Entity file pattern (pgTable, indexes, type exports, one file per entity)
+- Barrel exports per group (`index.ts`)
+- Migration workflow (generate → migrate), committed migrations
+- Seed scripts, connection helpers, `.env` pattern
+
+---
+
+## Interaction with Auth Blueprint
+
+The auth blueprint (`auth-better-auth`) also creates database schemas in `packages/db/`. Here's how the two blueprints interact:
+
+### Scenario A: DB blueprint first, auth second (recommended)
+
+1. DB blueprint creates `packages/db/` with the initial schema group (e.g., `core`)
+2. Auth blueprint detects the existing `packages/db/` and adds to it:
+   - Adds `"./auth"` export to `package.json`
+   - Adds `auth:generate`, `auth:migrate`, `drizzle:studio:auth` scripts
+   - Creates `src/auth/schema.ts` and `drizzle/auth/drizzle.config.ts`
+   - Does NOT overwrite existing files
+
+### Scenario B: Auth blueprint first, db second
+
+1. Auth blueprint creates a minimal `packages/db/` with just the auth group
+2. DB blueprint detects the existing package and merges:
+   - Adds the new group's export alongside `"./auth"`
+   - Adds new scripts without overwriting auth scripts
+   - Creates new group directory structure alongside `src/auth/`
+   - Skips `tsconfig.json` if already present
+
+### Shared vs Separate Databases
+
+- **Separate databases** (recommended for auth): Auth and core use different `DATABASE_URL` env vars (`AUTH_DATABASE_URL`, `CORE_DATABASE_URL`). Each group has independent migrations.
+- **Shared database**: Both auth and core schemas point to the same `DATABASE_URL`. Simpler but couples auth and application data.
+
+---
+
+## Schema File Patterns
+
+### Entity File Structure
+
+Every entity file follows this pattern:
+
+```typescript
+// 1. Imports
+import { index, pgEnum, pgTable, text, timestamp, uuid, varchar } from "drizzle-orm/pg-core";
+
+// 2. Enums (optional)
+export const statusEnum = pgEnum("entity_status", ["active", "archived"]);
+
+// 3. Table definition
+export const entity = pgTable(
+  "entity",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    name: varchar("name", { length: 200 }).notNull(),
+    status: statusEnum("status").default("active").notNull(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at").defaultNow().$onUpdate(() => new Date()).notNull(),
+  },
+  (table) => [
+    index("entity_name_idx").on(table.name),
+    index("entity_status_idx").on(table.status),
+  ],
+);
+
+// 4. Type exports
+export type Entity = typeof entity.$inferSelect;
+export type NewEntity = typeof entity.$inferInsert;
+```
+
+### Common Column Patterns
+
+```typescript
+// UUID primary key
+id: uuid("id").primaryKey().defaultRandom(),
+
+// Text primary key (for external IDs like Better Auth)
+id: text("id").primaryKey(),
+
+// Foreign key to user (text, matches Better Auth user.id)
+userId: text("user_id").notNull(),
+
+// Foreign key to another table in same group
+categoryId: uuid("category_id").references(() => category.id, { onDelete: "cascade" }),
+
+// PostgreSQL enum
+status: statusEnum("status").default("active").notNull(),
+
+// JSONB field with TypeScript type
+metadata: jsonb("metadata").$type<{ key: string; value: unknown }>(),
+
+// Array field
+tags: text("tags").array(),
+
+// Automatic timestamps
+createdAt: timestamp("created_at").defaultNow().notNull(),
+updatedAt: timestamp("updated_at").defaultNow().$onUpdate(() => new Date()).notNull(),
+
+// Soft delete
+deletedAt: timestamp("deleted_at"),
+```
+
+### Index Patterns
+
+```typescript
+// Single column index
+index("entity_user_id_idx").on(table.userId),
+
+// Composite index
+index("entity_org_status_idx").on(table.organizationId, table.status),
+
+// Unique constraint
+uniqueIndex("entity_slug_unique").on(table.slug),
+```
+
+---
+
+## File Manifest
+
+| File | Purpose | Monorepo Target | Single-Repo Target |
+|---|---|---|---|
+| `files/db/package.json` | Package config with exports, scripts, deps | `packages/db/package.json` | N/A (scripts go in root `package.json`) |
+| `files/db/tsconfig.json` | TypeScript config extending shared base | `packages/db/tsconfig.json` | N/A (use root `tsconfig.json`) |
+| `files/db/env.example` | Example env with DATABASE_URL | `packages/db/.env.example` | `.env.example` (merge into root) |
+| `files/db/drizzle.config.ts` | Per-group Drizzle Kit config template | `packages/db/drizzle/{{GROUP}}/drizzle.config.ts` | `drizzle/{{GROUP}}/drizzle.config.ts` |
+| `files/db/src/index.ts` | Barrel export for schema group | `packages/db/src/{{GROUP}}/index.ts` | `src/db/{{GROUP}}/index.ts` |
+| `files/db/src/example-entity.ts` | Example entity showing full pattern | `packages/db/src/{{GROUP}}/example.ts` | `src/db/{{GROUP}}/example.ts` |
+| `files/db/src/client.ts` | Optional connection helper | `packages/db/src/{{GROUP}}/client.ts` | `src/db/{{GROUP}}/client.ts` |
+| `files/db/src/scripts/seed.ts` | Example seed script using tsx | `packages/db/src/scripts/seed.ts` | `src/db/scripts/seed.ts` |
+
+---
+
+## Integration Steps
+
+### Phase 1: Package Setup
+
+1. Create `packages/db/` directory
+2. Copy `package.json` — replace `{{SCOPE}}` and `{{GROUP}}` placeholders
+3. Copy `tsconfig.json` — replace `{{SCOPE}}` with shared config package name
+4. Copy `.env.example` — replace `{{GROUP_UPPER}}`
+5. Create `packages/db/.env` from `.env.example` with actual DATABASE_URL
+
+### Phase 2: Schema Group
+
+6. Create `src/{{GROUP}}/` directory
+7. Copy example entity file (if included) — demonstrates full pattern
+8. Create barrel `index.ts` with re-exports
+9. Copy `client.ts` helper (if included) — replace `{{SCOPE}}`, `{{GROUP}}`, `{{GROUP_UPPER}}`
+
+### Phase 3: Drizzle Config
+
+10. Create `drizzle/{{GROUP}}/` directory
+11. Copy `drizzle.config.ts` — replace `{{GROUP}}`, `{{GROUP_UPPER}}`, set schema file paths
+
+### Phase 4: Seed Script (optional)
+
+12. Create `src/scripts/` directory
+13. Copy `seed.ts` — replace `{{GROUP}}`, `{{GROUP_UPPER}}`, adjust entity imports
+
+### Phase 5: Project Integration (monorepo)
+
+> Skip this phase for single-repo projects — use Phase 5-alt instead.
+
+14. Add `{{GROUP}}:generate`, `{{GROUP}}:migrate` tasks to `turbo.json` (both `cache: false`)
+15. Add `db:generate`, `db:migrate`, `db:studio`, `db:seed` scripts to root `package.json` (Turbo wrappers)
+16. Verify `packages/db` is covered by `pnpm-workspace.yaml` (should be via `packages/*`)
+17. Run `pnpm install` to wire workspace dependencies
+
+### Phase 5-alt: Project Integration (single-repo)
+
+> Use this phase instead of Phase 5 for standalone applications.
+
+14. Add `db:generate`, `db:migrate`, `db:studio`, `db:seed` scripts to root `package.json` (direct drizzle-kit calls — see Single-Repo Scripts above)
+15. Add drizzle-orm, dotenv as dependencies and drizzle-kit, pg, @types/pg, tsx as devDependencies in root `package.json`
+16. Set `{{GROUP_UPPER}}_DATABASE_URL` in `.env` at project root
+
+### Phase 6: Verification
+
+18. Set `{{GROUP_UPPER}}_DATABASE_URL` in `packages/db/.env`
+19. Run `pnpm db:generate` — should produce initial migration SQL
+20. Run `pnpm db:migrate` — should apply migration to database
+21. Run `pnpm db:studio` — should open Drizzle Studio
+22. Run `pnpm db:seed` — should insert sample data (if seed included)
+
+---
+
+## Adding New Entities
+
+After initial scaffolding, add new domain entities with this checklist:
+
+1. Create `src/{{GROUP}}/new-entity.ts` (copy the example entity pattern)
+2. Add `export * from "./new-entity.js";` to `src/{{GROUP}}/index.ts`
+3. Add `"./src/{{GROUP}}/new-entity.ts"` to `drizzle/{{GROUP}}/drizzle.config.ts` schema array
+4. Run `pnpm {{GROUP}}:generate` to create the migration
+5. Run `pnpm {{GROUP}}:migrate` to apply it
+
+## Adding a New Schema Group
+
+To add a second group (e.g., `"pipeline"`) for a separate database or logical domain:
+
+1. Create `src/pipeline/` directory with entity files and `index.ts`
+2. Create `drizzle/pipeline/drizzle.config.ts` (copy from existing group, update paths and env var)
+3. Add `"./pipeline"` export to `package.json`:
+   ```json
+   "./pipeline": {
+     "import": "./dist/pipeline/index.js",
+     "types": "./dist/pipeline/index.d.ts"
+   }
+   ```
+4. Add scripts: `pipeline:generate`, `pipeline:migrate`, `drizzle:studio:pipeline`
+5. Add `PIPELINE_DATABASE_URL` to `.env` and `.env.example`
+6. Add `pipeline:generate` and `pipeline:migrate` tasks to `turbo.json` (`cache: false`)
+7. (Optional) Add `db:generate:pipeline`, `db:migrate:pipeline` convenience scripts to root `package.json`
+
+---
+
+## Maintenance Hooks
+
+### Schema & Migration Hooks
+
+| When you... | Then run... | Why |
+|---|---|---|
+| Add a new entity file | Add to `drizzle.config.ts` schema array AND `index.ts` barrel | Missing entries = invisible to migrations and consumers |
+| Modify any schema file | `pnpm {{GROUP}}:generate` then `pnpm {{GROUP}}:migrate` | Schema changes need migrations generated and applied |
+| Add a new schema group | Follow "Adding a New Schema Group" checklist | Multiple configs + exports + scripts needed |
+| Update drizzle-orm or drizzle-kit | `pnpm {{GROUP}}:generate` and check for unexpected diffs | New versions may change migration format |
+
+### Environment Hooks
+
+| When you... | Then do... | Why |
+|---|---|---|
+| Add a new `DATABASE_URL` | Add to `.env`, `.env.example`, and consuming app env validation | Missing URL = crash at startup |
+| Change `DATABASE_URL` | Verify connection with `pnpm drizzle:studio:{{GROUP}}` | Wrong URL = silent connection failures |
+
+### Condensed Rules for CLAUDE.md
+
+```markdown
+### db-drizzle-postgres maintenance
+- After creating a new schema file: add it to `drizzle/<group>/drizzle.config.ts` schema array AND the group's `index.ts` barrel export
+- After any schema change: run `pnpm <group>:generate && pnpm <group>:migrate`
+- After adding a new schema group: create drizzle config, add package.json export, add scripts (see BLUEPRINT.md "Adding a New Schema Group")
+- After updating drizzle-orm/drizzle-kit: run generate and check migration diff for unexpected changes
+- Never use glob patterns in drizzle.config.ts schema — always list files explicitly, excluding index.ts
+```
+
+---
+
+## What's Configurable
+
+- Schema group name and number of groups
+- Primary key strategy (UUID, serial, CUID, ULID, text)
+- Whether to include example entity and seed script
+- Connection helper location (in db package vs per consuming app)
+- Single database vs separate database per group
+
+## What's Opinionated
+
+- **Drizzle ORM** — the only supported ORM (hard requirement per ENGINEERING.md)
+- **PostgreSQL** — the only supported database (this is `db-drizzle-*postgres*`)
+- **Centralized db directory** — schemas live in one location (`packages/db/` in monorepo, `src/db/` in single-repo), not scattered across apps
+- **Schema-per-file** — one file per domain entity, not one giant schema file
+- **Per-group drizzle.config.ts** — independent migration generation per schema group
+- **Explicit schema file lists** — no globs in drizzle config (avoids barrel export issues)
+- **Committed migrations** — SQL files are version-controlled for auditability
+- **`pg` (node-postgres) driver** — standard PostgreSQL driver for Node.js
+
+## Project Context Output
+
+Appends to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### db-drizzle-postgres
+blueprint: db-drizzle-postgres
+choices:
+  schema_group: {{GROUP}}
+  include_example: true|false
+  include_seed: true|false
+  connection_helper: in-db-package|per-app
+files_created:
+  - packages/db/package.json
+  - packages/db/tsconfig.json
+  - packages/db/.env.example
+  - packages/db/drizzle/{{GROUP}}/drizzle.config.ts
+  - packages/db/src/{{GROUP}}/index.ts
+  - packages/db/src/{{GROUP}}/example.ts (if included)
+  - packages/db/src/{{GROUP}}/client.ts (if included)
+  - packages/db/src/scripts/seed.ts (if included)
+env_vars_added:
+  - {{GROUP_UPPER}}_DATABASE_URL
+scripts_added:
+  db_package:
+    - {{GROUP}}:generate
+    - {{GROUP}}:migrate
+    - drizzle:studio:{{GROUP}}
+    - seed
+  root:
+    - db:generate
+    - db:migrate
+    - db:studio
+    - db:seed
+  turbo_tasks:
+    - {{GROUP}}:generate
+    - {{GROUP}}:migrate
+```
+
+---
+
+## References
+
+- **Drizzle ORM Docs:** https://orm.drizzle.team/docs/overview
+- **Drizzle PostgreSQL Guide:** https://orm.drizzle.team/docs/get-started/postgresql-new
+- **Drizzle Kit CLI:** https://orm.drizzle.team/docs/kit-overview
+- **Drizzle Schema Declaration:** https://orm.drizzle.team/docs/sql-schema-declaration
+- **Drizzle Migrations:** https://orm.drizzle.team/docs/migrations
+- **Drizzle Studio:** https://orm.drizzle.team/docs/drizzle-studio
+- **node-postgres:** https://node-postgres.com/

package/blueprints/features/db-drizzle-postgres/files/db/drizzle.config.ts

@@ -0,0 +1,18 @@
+import { config } from "dotenv";
+import { defineConfig } from "drizzle-kit";
+
+config({ path: "./.env" });
+
+// CONFIGURE: Update this env var name if your group uses a different convention
+const DATABASE_URL = process.env.{{GROUP_UPPER}}_DATABASE_URL!;
+
+export default defineConfig({
+  // List each schema file explicitly — do NOT include index.ts or client.ts
+  // CONFIGURE: Paths are relative to where drizzle-kit runs. Add new schema files here as you create them
+  schema: ["./src/{{GROUP}}/example.ts"],
+  out: "./drizzle/{{GROUP}}",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: DATABASE_URL,
+  },
+});

package/blueprints/features/db-drizzle-postgres/files/db/env.example

@@ -0,0 +1,3 @@
+# {{GROUP_UPPER}}_DATABASE_URL — PostgreSQL connection URL for the {{GROUP}} database
+# Format: postgresql://user:password@host:port/database
+{{GROUP_UPPER}}_DATABASE_URL=postgresql://user:password@localhost:5432/{{GROUP}}_db

package/blueprints/features/db-drizzle-postgres/files/db/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "{{SCOPE}}/db",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./{{GROUP}}": {
+      "import": "./dist/{{GROUP}}/index.js",
+      "types": "./dist/{{GROUP}}/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist",
+    "{{GROUP}}:generate": "drizzle-kit generate --config ./drizzle/{{GROUP}}/drizzle.config.ts",
+    "{{GROUP}}:migrate": "drizzle-kit generate --config ./drizzle/{{GROUP}}/drizzle.config.ts && drizzle-kit migrate --config ./drizzle/{{GROUP}}/drizzle.config.ts",
+    "drizzle:studio:{{GROUP}}": "drizzle-kit studio --config ./drizzle/{{GROUP}}/drizzle.config.ts",
+    "seed": "tsx src/scripts/seed.ts"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "drizzle-orm": "^0.45.1"
+  },
+  "devDependencies": {
+    "{{SCOPE}}/typescript-config": "workspace:*",
+    "@types/pg": "^8.16.0",
+    "drizzle-kit": "^0.31.8",
+    "pg": "^8.18.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0"
+  }
+}

package/blueprints/features/db-drizzle-postgres/files/db/src/client.ts

@@ -0,0 +1,34 @@
+// =============================================================================
+// {{GROUP}} Database Client
+// =============================================================================
+// Provides a ready-to-use Drizzle instance connected to the {{GROUP}} database.
+//
+// Usage in consuming packages:
+//   import { db } from "{{SCOPE}}/db/{{GROUP}}/client";
+//   const rows = await db.query.example.findMany();
+//
+// CONFIGURE: If your app needs custom pool settings per environment (different
+// pool sizes, timeouts, SSL config), consider moving connection setup into each
+// consuming app instead. See BLUEPRINT.md "Connection Patterns" for details.
+// =============================================================================
+
+import { config } from "dotenv";
+import { drizzle } from "drizzle-orm/node-postgres";
+import pg from "pg";
+import * as schema from "./index.js";
+
+config({ path: "./.env" });
+
+const DATABASE_URL = process.env.{{GROUP_UPPER}}_DATABASE_URL;
+if (!DATABASE_URL) {
+  throw new Error(
+    // CONFIGURE: Adjust path reference for your project structure
+    "Missing {{GROUP_UPPER}}_DATABASE_URL — set it in your .env file",
+  );
+}
+
+const pool = new pg.Pool({ connectionString: DATABASE_URL });
+
+export const db = drizzle(pool, { schema });
+
+export type DbClient = typeof db;