@core / db

1.0.0 ▾

1.0.0

verifiedMIT

GitHub

Postgres with Drizzle: shared client, per-module schemas, transactions and ULID ids

Code8 filesContext~547 tokensscan passed

~547 tokens→ src/lib/db/AGENTS.md→ .cursor/rules/genpm-core-db.mdc

This is exactly what your AI reads when it works in src/lib/db. Nothing else is added to its context.

@core/db — rules for AI agents

Purpose

Shared Postgres access for every module: one Drizzle client, per-module schemas, transactions, ULID ids and standard timestamps. It owns no tables itself. Not an ORM wrapper: use Drizzle's query builder directly.

Map

index.ts — public API: getDb, createDb, setDb, withTransaction, primaryId, timestamps, newId, ulid; types Db, Tx, Executor.
client.ts — lazy client from DATABASE_URL (postgres-js).
columns.ts — primaryId(prefix) and timestamps column helpers.
drizzle.config.ts — drizzle-kit config that collects src/lib/*/schema.ts.

Integration

Set DATABASE_URL (any Postgres: local, Neon, Supabase, RDS).
Install the npm deps if GenPM did not: drizzle-orm, postgres, and drizzle-kit as a dev dependency.
Add scripts to package.json: "db:generate": "drizzle-kit generate --config src/lib/db/drizzle.config.ts", "db:migrate": "drizzle-kit migrate --config src/lib/db/drizzle.config.ts".
Run db:generate then db:migrate after installing any module that has a schema.ts.

Query from app code:

import { getDb } from './lib/db/index.js';
const rows = await getDb().select().from(users);

Another driver (Neon serverless, PGlite in tests): build it with Drizzle and call setDb(db) once at startup.

Conventions

Each module defines its tables in its own src/lib/<module>/schema.ts. Never put tables in src/lib/db.
Table names are prefixed with the module when ambiguous (auth_sessions, not sessions).
Primary keys: id: primaryId('<3-4 letter prefix>'); spread ...timestamps in every table.
Functions that write accept an optional Executor (db or tx) so callers can compose them in withTransaction.
Money as integer minor units; times as timestamp with time zone.

Don't

Don't edit or reference another module's tables except through that module's exported functions.
Don't create a second client or connection pool; use getDb().
Don't log DATABASE_URL or query parameters that may hold secrets.
Don't use drizzle-kit push against production; generate and review migrations.

# @core/db — rules for AI agents

## Purpose
Shared Postgres access for every module: one Drizzle client, per-module schemas, transactions, ULID ids and standard
timestamps. It owns no tables itself. Not an ORM wrapper: use Drizzle's query builder directly.

## Map
- `index.ts` — public API: `getDb`, `createDb`, `setDb`, `withTransaction`, `primaryId`, `timestamps`, `newId`, `ulid`; types `Db`, `Tx`, `Executor`.
- `client.ts` — lazy client from `DATABASE_URL` (postgres-js).
- `columns.ts` — `primaryId(prefix)` and `timestamps` column helpers.
- `drizzle.config.ts` — drizzle-kit config that collects `src/lib/*/schema.ts`.

## Integration
1. Set `DATABASE_URL` (any Postgres: local, Neon, Supabase, RDS).
2. Install the npm deps if GenPM did not: `drizzle-orm`, `postgres`, and `drizzle-kit` as a dev dependency.
3. Add scripts to `package.json`:
   `"db:generate": "drizzle-kit generate --config src/lib/db/drizzle.config.ts"`,
   `"db:migrate": "drizzle-kit migrate --config src/lib/db/drizzle.config.ts"`.
4. Run `db:generate` then `db:migrate` after installing any module that has a `schema.ts`.
5. Query from app code:
   ```ts
   import { getDb } from './lib/db/index.js';
   const rows = await getDb().select().from(users);
   ```
6. Another driver (Neon serverless, PGlite in tests): build it with Drizzle and call `setDb(db)` once at startup.

## Conventions
- Each module defines its tables in its own `src/lib/<module>/schema.ts`. Never put tables in `src/lib/db`.
- Table names are prefixed with the module when ambiguous (`auth_sessions`, not `sessions`).
- Primary keys: `id: primaryId('<3-4 letter prefix>')`; spread `...timestamps` in every table.
- Functions that write accept an optional `Executor` (`db` or `tx`) so callers can compose them in `withTransaction`.
- Money as integer minor units; times as `timestamp with time zone`.

## Don't
- Don't edit or reference another module's tables except through that module's exported functions.
- Don't create a second client or connection pool; use `getDb()`.
- Don't log `DATABASE_URL` or query parameters that may hold secrets.
- Don't use `drizzle-kit push` against production; generate and review migrations.

The exact tree that will be injected, after .genpmignore. Pinned to

src/lib/db/transaction.tsread-only · 28d4b9f

import { type Db, getDb, type Tx } from './client.js';

/**
 * Ejecuta `fn` en una transacción: si lanza, se hace rollback de todo. Los helpers de otros módulos aceptan un
 * `Executor`, así que pásales `tx` para que participen en la misma transacción.
 */
export function withTransaction<T>(fn: (tx: Tx) => Promise<T>, db: Db = getDb()): Promise<T> {
  return db.transaction((tx) => fn(tx as Tx));
}