@jgamaraalv/ts-dev-kit 1.0.0

package/skills/drizzle-pg/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: drizzle-pg
+description: "Drizzle ORM reference for PostgreSQL — schema definition, typesafe queries, relations, and migrations with drizzle-kit. Use when: (1) defining pgTable schemas with column types, indexes, constraints, or enums, (2) writing select/insert/update/delete queries or joins, (3) defining relations and using the relational query API (db.query.*), (4) running drizzle-kit generate/migrate/push/pull, (5) configuring drizzle.config.ts, (6) using the sql`` template operator, or (7) working with PostGIS/pg_vector extensions."
+---
+
+# Drizzle ORM — PostgreSQL
+
+Drizzle is a headless TypeScript ORM. Zero dependencies, SQL-like API, single-query output.
+Packages: `drizzle-orm` (runtime), `drizzle-kit` (CLI/migrations).
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Import Cheat Sheet](#import-cheat-sheet)
+- [Common Patterns](#common-patterns)
+- [Reference Files](#reference-files)
+
+## Quick Start
+
+### Connect
+
+```typescript
+import { drizzle } from "drizzle-orm/node-postgres";
+import * as schema from "./schema";
+import { relations } from "./relations";
+
+const db = drizzle(process.env.DATABASE_URL, { schema, relations });
+```
+
+Or with existing Pool:
+
+```typescript
+import { Pool } from "pg";
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const db = drizzle({ client: pool, schema, relations });
+```
+
+### Define Schema
+
+```typescript
+import {
+  pgTable,
+  pgEnum,
+  serial,
+  text,
+  integer,
+  timestamp,
+  uuid,
+  jsonb,
+  index,
+  uniqueIndex,
+} from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+
+export const statusEnum = pgEnum("status", ["active", "inactive", "banned"]);
+
+export const users = pgTable(
+  "users",
+  {
+    id: uuid("id")
+      .default(sql`gen_random_uuid()`)
+      .primaryKey(),
+    name: text("name").notNull(),
+    email: text("email").notNull().unique(),
+    status: statusEnum().default("active").notNull(),
+    metadata: jsonb("metadata").$type<{ roles: string[] }>(),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  },
+  (t) => [index("users_email_idx").on(t.email)],
+);
+
+export const posts = pgTable("posts", {
+  id: serial("id").primaryKey(),
+  title: text("title").notNull(),
+  authorId: uuid("author_id")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});
+```
+
+### Define Relations
+
+```typescript
+import { defineRelations } from "drizzle-orm";
+import * as schema from "./schema";
+
+export const relations = defineRelations(schema, (r) => ({
+  users: {
+    posts: r.many.posts({ from: r.users.id, to: r.posts.authorId }),
+  },
+  posts: {
+    author: r.one.users({ from: r.posts.authorId, to: r.users.id }),
+  },
+}));
+```
+
+### CRUD
+
+```typescript
+import { eq, and, ilike, sql } from "drizzle-orm";
+
+// SELECT
+const allUsers = await db.select().from(users);
+const user = await db.select().from(users).where(eq(users.id, id));
+
+// INSERT
+const [created] = await db
+  .insert(users)
+  .values({ name: "Dan", email: "dan@example.com" })
+  .returning();
+
+// UPDATE
+await db.update(users).set({ name: "Updated" }).where(eq(users.id, id));
+
+// DELETE
+await db.delete(users).where(eq(users.id, id));
+
+// UPSERT
+await db
+  .insert(users)
+  .values({ id, name: "Dan", email: "dan@ex.com" })
+  .onConflictDoUpdate({ target: users.id, set: { name: "Dan" } });
+```
+
+### Relational Queries
+
+```typescript
+// Nested eager loading (single SQL query)
+const usersWithPosts = await db.query.users.findMany({
+  with: { posts: true },
+  where: { status: "active" },
+  orderBy: { createdAt: "desc" },
+  limit: 10,
+});
+
+const user = await db.query.users.findFirst({
+  where: { id: userId },
+  with: { posts: { columns: { id: true, title: true } } },
+});
+```
+
+### Migrations
+
+```bash
+# drizzle.config.ts -> see references/migrations.md
+npx drizzle-kit generate     # schema diff -> SQL files
+npx drizzle-kit migrate      # apply SQL to database
+npx drizzle-kit push         # direct push (no SQL files)
+npx drizzle-kit pull         # introspect DB -> Drizzle schema
+npx drizzle-kit studio       # visual browser UI
+```
+
+## Import Cheat Sheet
+
+| Import path           | Key exports                                                                                                                                                                                                                                   |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `drizzle-orm/pg-core` | `pgTable`, `pgEnum`, column types (`serial`, `text`, `integer`, `uuid`, `timestamp`, `jsonb`, `varchar`, `boolean`, `numeric`, `bigint`, `geometry`, `vector`, ...), `index`, `uniqueIndex`, `unique`, `check`, `primaryKey`, `foreignKey`    |
+| `drizzle-orm`         | Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `not`, `isNull`, `isNotNull`, `inArray`, `between`, `like`, `ilike`, `exists`, `sql`, `asc`, `desc`. Utilities: `getColumns`, `defineRelations`, `cosineDistance`, `l2Distance` |
+| `drizzle-orm` (types) | `InferSelectModel`, `InferInsertModel`                                                                                                                                                                                                        |
+| `drizzle-zod`         | `createInsertSchema`, `createSelectSchema`                                                                                                                                                                                                    |
+
+## Common Patterns
+
+### Conditional filters
+
+```typescript
+const filters: SQL[] = [];
+if (name) filters.push(ilike(users.name, `%${name}%`));
+if (status) filters.push(eq(users.status, status));
+await db
+  .select()
+  .from(users)
+  .where(and(...filters));
+```
+
+### Transactions
+
+```typescript
+await db.transaction(async (tx) => {
+  const [user] = await tx.insert(users).values({ name: "Dan" }).returning();
+  await tx.insert(posts).values({ title: "Hello", authorId: user.id });
+});
+```
+
+### Type inference
+
+```typescript
+type User = typeof users.$inferSelect;
+type NewUser = typeof users.$inferInsert;
+```
+
+## Reference Files
+
+For detailed API coverage, see:
+
+- **Column types, indexes, constraints, enums, PostGIS, pg_vector**: [references/schema-pg.md](references/schema-pg.md)
+- **Select, insert, update, delete, joins, filters**: [references/queries.md](references/queries.md)
+- **Relations definition, relational query API (findMany/findFirst)**: [references/relations.md](references/relations.md)
+- **sql`` template: raw, empty, join, identifier, placeholders**: [references/sql-operator.md](references/sql-operator.md)
+- **drizzle-kit commands, drizzle.config.ts, migration workflows**: [references/migrations.md](references/migrations.md)
+- **Dynamic queries, transactions, custom types, Zod, utilities**: [references/advanced.md](references/advanced.md)

package/skills/drizzle-pg/references/advanced.md

@@ -0,0 +1,299 @@
+# Advanced Features Reference
+
+## Table of Contents
+
+- [Type Inference](#type-inference)
+- [Dynamic Query Building](#dynamic-query-building)
+- [Transactions](#transactions)
+- [Utility Functions](#utility-functions)
+- [Logging](#logging)
+- [Custom Types](#custom-types)
+- [Table Name Prefixing](#table-name-prefixing)
+- [Standalone Query Builder](#standalone-query-builder)
+- [Zod Integration](#zod-integration)
+- [Anti-Patterns](#anti-patterns)
+
+## Type Inference
+
+```typescript
+// Infer select/insert types from table definition
+type SelectUser = typeof users.$inferSelect;
+type InsertUser = typeof users.$inferInsert;
+
+// Alternative with utility types
+import type { InferSelectModel, InferInsertModel } from "drizzle-orm";
+type SelectUser = InferSelectModel<typeof users>;
+type InsertUser = InferInsertModel<typeof users>;
+```
+
+## Dynamic Query Building
+
+Use `$dynamic()` to remove the restriction that query methods can only be called once:
+
+```typescript
+import type { PgSelect } from "drizzle-orm/pg-core";
+
+function withPagination<T extends PgSelect>(qb: T, page = 1, pageSize = 10) {
+  return qb.limit(pageSize).offset((page - 1) * pageSize);
+}
+
+function withOrderBy<T extends PgSelect>(qb: T, column: PgColumn, dir: "asc" | "desc" = "asc") {
+  return qb.orderBy(dir === "asc" ? asc(column) : desc(column));
+}
+
+// Usage
+const query = db.select().from(users).where(eq(users.active, true)).$dynamic();
+const result = await withPagination(withOrderBy(query, users.createdAt, "desc"), 2, 20);
+```
+
+Available types by operation: `PgSelect`, `PgInsert`, `PgUpdate`, `PgDelete`, `PgSelectQueryBuilder`.
+
+## Transactions
+
+```typescript
+await db.transaction(async (tx) => {
+  const [user] = await tx.insert(users).values({ name: "Dan" }).returning();
+  await tx.insert(posts).values({ title: "Hello", authorId: user.id });
+});
+
+// Nested savepoints
+await db.transaction(async (tx) => {
+  await tx.insert(users).values({ name: "Dan" });
+
+  await tx.transaction(async (tx2) => {
+    // This is a savepoint
+    await tx2.insert(posts).values({ title: "Nested" });
+  });
+});
+
+// Rollback
+await db.transaction(async (tx) => {
+  await tx.insert(users).values({ name: "Dan" });
+  tx.rollback(); // Rolls back entire transaction
+});
+
+// Isolation level
+await db.transaction(
+  async (tx) => {
+    // ...
+  },
+  {
+    isolationLevel: "serializable", // "read uncommitted" | "read committed" | "repeatable read" | "serializable"
+  },
+);
+```
+
+## Utility Functions
+
+### getColumns — extract columns (exclude sensitive fields)
+
+```typescript
+import { getColumns } from "drizzle-orm";
+
+const { password, ...publicColumns } = getColumns(users);
+await db.select(publicColumns).from(users);
+```
+
+### getTableConfig — table metadata
+
+```typescript
+import { getTableConfig } from "drizzle-orm/pg-core";
+
+const config = getTableConfig(users);
+// config.columns, config.indexes, config.foreignKeys, config.checks, config.primaryKeys, config.name, config.schema
+```
+
+### toSQL — inspect generated SQL
+
+```typescript
+const query = db.select().from(users).where(eq(users.id, 1)).toSQL();
+// { sql: "select ... from \"users\" where \"users\".\"id\" = $1", params: [1] }
+```
+
+### db.execute — raw SQL
+
+```typescript
+const result = await db.execute(sql`SELECT * FROM users WHERE id = ${userId}`);
+```
+
+### is — runtime type checking
+
+```typescript
+import { is, Column } from "drizzle-orm";
+
+if (is(value, Column)) {
+  // value narrowed to Column type
+}
+```
+
+## Logging
+
+```typescript
+// Built-in logger
+const db = drizzle(process.env.DATABASE_URL, { logger: true });
+
+// Custom logger
+import type { Logger } from "drizzle-orm";
+
+class MyLogger implements Logger {
+  logQuery(query: string, params: unknown[]): void {
+    console.log({ query, params });
+  }
+}
+
+const db = drizzle(process.env.DATABASE_URL, { logger: new MyLogger() });
+```
+
+## Custom Types
+
+Define custom column types for special mappings:
+
+```typescript
+import { customType } from "drizzle-orm/pg-core";
+
+// Example: monetary type stored as integer cents
+const money = customType<{ data: number; driverData: number }>({
+  dataType() {
+    return "integer";
+  },
+  fromDriver(value: number): number {
+    return value / 100;
+  },
+  toDriver(value: number): number {
+    return Math.round(value * 100);
+  },
+});
+
+// Usage
+const products = pgTable("products", {
+  price: money("price_cents").notNull(),
+});
+
+// Example: JSONB with typed shape
+const typedJsonb = <T>(name: string) =>
+  customType<{ data: T; driverData: string }>({
+    dataType() {
+      return "jsonb";
+    },
+    toDriver(value: T): string {
+      return JSON.stringify(value);
+    },
+  })(name);
+
+const settings = pgTable("settings", {
+  config: typedJsonb<{ theme: string; lang: string }>("config"),
+});
+```
+
+### customType parameters
+
+```typescript
+customType<{
+  data: AppType;           // Required — the TS type for select/insert
+  driverData: DriverType;  // Type the driver returns
+  config: ConfigType;      // Config object shape for dataType()
+}>({
+  dataType(config): string;          // Returns SQL type string
+  toDriver?(value): driverData;     // App → Database
+  fromDriver?(value): data;         // Database → App
+})
+```
+
+## Table Name Prefixing
+
+Useful for multi-project schemas sharing one database:
+
+```typescript
+import { pgTableCreator } from "drizzle-orm/pg-core";
+
+const pgTable = pgTableCreator((name) => `myapp_${name}`);
+
+const users = pgTable("users", {
+  id: serial("id").primaryKey(),
+});
+// Creates table "myapp_users" in database
+```
+
+## Standalone Query Builder
+
+Build queries without a database connection (for inspection or testing):
+
+```typescript
+import { QueryBuilder } from "drizzle-orm/pg-core";
+
+const qb = new QueryBuilder();
+const query = qb.select().from(users).where(eq(users.name, "Dan"));
+const { sql, params } = query.toSQL();
+```
+
+## Zod Integration
+
+Generate Zod schemas from Drizzle tables:
+
+```typescript
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+
+const insertUserSchema = createInsertSchema(users);
+const selectUserSchema = createSelectSchema(users);
+
+// With refinements
+const insertUserSchema = createInsertSchema(users, {
+  email: (schema) => schema.email(),
+  name: (schema) => schema.min(1).max(100),
+});
+
+// Usage with Fastify/Express
+const parsed = insertUserSchema.parse(req.body);
+await db.insert(users).values(parsed);
+```
+
+Requires `drizzle-zod` package: `npm i drizzle-zod`
+
+## Anti-Patterns
+
+### Raw SQL with user input (SQL injection risk)
+
+```typescript
+// BAD -- string interpolation bypasses parameterization
+const name = req.query.name;
+await db.execute(sql.raw(`SELECT * FROM users WHERE name = '${name}'`));
+
+// GOOD -- use sql template literal for automatic parameterization
+await db.execute(sql`SELECT * FROM users WHERE name = ${name}`);
+
+// GOOD -- use Drizzle operators
+await db.select().from(users).where(eq(users.name, name));
+```
+
+`sql.raw()` should only be used for trusted, static SQL fragments (column names, table names), never for user-provided values.
+
+### Missing `.returning()` on insert/update/delete
+
+```typescript
+// BAD -- no way to get the created record without a second query
+await db.insert(users).values({ name: "Dan", email: "dan@ex.com" });
+const user = await db.select().from(users).where(eq(users.email, "dan@ex.com"));
+
+// GOOD -- get the result in a single round-trip
+const [user] = await db.insert(users).values({ name: "Dan", email: "dan@ex.com" }).returning();
+```
+
+Always use `.returning()` when you need the inserted/updated/deleted row. PostgreSQL supports this natively with no performance penalty.
+
+### Mixing relational query API with SQL-like joins
+
+```typescript
+// BAD -- cannot use db.query.* (relational API) and then chain .leftJoin()
+// The relational API (findMany/findFirst) and SQL-like API (select/from/join) are separate systems
+const result = await db.query.users.findMany({
+  with: { posts: true },
+}); // This returns nested objects
+
+const result2 = await db.select().from(users).leftJoin(posts, eq(users.id, posts.authorId)); // This returns flat rows
+
+// Pick one approach per query:
+// - Relational API (db.query.*) for nested/eager loading with `with`
+// - SQL-like API (db.select().from()) for joins, aggregations, complex SQL
+```
+
+Do not attempt to mix `db.query.*` with `.leftJoin()`, `.innerJoin()`, or other SQL-like methods. They are different query builders with different return shapes.

package/skills/drizzle-pg/references/migrations.md

@@ -0,0 +1,214 @@
+# Drizzle Kit & Migrations Reference
+
+## Table of Contents
+
+- [Commands Overview](#commands-overview)
+- [drizzle.config.ts](#drizzleconfigts)
+- [Workflow: Code-First](#workflow-code-first)
+- [Workflow: Direct Push](#workflow-direct-push)
+- [Programmatic Migrations](#programmatic-migrations)
+- [Custom Migrations](#custom-migrations)
+- [CLI Flags](#cli-flags)
+
+## Commands Overview
+
+| Command                    | Purpose                                       |
+| -------------------------- | --------------------------------------------- |
+| `npx drizzle-kit generate` | Generate SQL migration files from schema diff |
+| `npx drizzle-kit migrate`  | Apply pending SQL migrations to database      |
+| `npx drizzle-kit push`     | Push schema directly to DB (no SQL files)     |
+| `npx drizzle-kit pull`     | Introspect DB and generate Drizzle schema     |
+| `npx drizzle-kit check`    | Check migrations for race conditions          |
+| `npx drizzle-kit up`       | Upgrade migration snapshots to latest format  |
+| `npx drizzle-kit studio`   | Open Drizzle Studio UI (browser)              |
+
+## drizzle.config.ts
+
+### Minimal (PostgreSQL)
+
+```typescript
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  dialect: "postgresql",
+  schema: "./src/db/schema.ts",
+});
+```
+
+### Full options
+
+```typescript
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  // Required
+  dialect: "postgresql", // "postgresql" | "mysql" | "sqlite" | "turso" | "singlestore" | "mssql" | "cockroachdb"
+  schema: "./src/db/schema.ts", // string | string[] — glob patterns supported
+
+  // Migration output
+  out: "./drizzle", // default: "./drizzle"
+  breakpoints: true, // add statement breakpoints in SQL
+
+  // Database connection (for migrate/push/pull/studio)
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+    // or individual fields:
+    // host: "localhost", port: 5432, user: "postgres", password: "pass", database: "mydb", ssl: true
+  },
+
+  // Migration tracking table
+  migrations: {
+    table: "__drizzle_migrations", // default
+    schema: "drizzle", // default (PG schema)
+  },
+
+  // Filtering
+  tablesFilter: ["*"], // include specific tables: ["users", "posts"]
+  schemaFilter: ["public"], // PG schemas to include
+  extensionsFilters: ["postgis"], // skip extension-managed tables
+
+  // Introspection (pull)
+  introspect: {
+    casing: "camel", // "camel" (default) | "preserve"
+  },
+
+  // Push behavior
+  strict: false, // require approval before executing
+  verbose: true, // print SQL before execution
+
+  // Roles (PG-specific)
+  entities: {
+    roles: false, // true | false | { provider: "neon" | "supabase", include/exclude: [...] }
+  },
+});
+```
+
+### Environment variables pattern
+
+```typescript
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  dialect: "postgresql",
+  schema: "./src/db/schema.ts",
+  out: "./drizzle",
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});
+```
+
+### Multiple schema files
+
+```typescript
+schema: "./src/db/schema/*.ts"; // glob
+schema: ["./src/db/users.ts", "./src/db/posts.ts"]; // explicit array
+```
+
+## Workflow: Code-First
+
+Best for production, team collaboration, and audit trails.
+
+```
+1. Edit TypeScript schema
+2. npx drizzle-kit generate          → creates timestamped SQL in ./drizzle/
+3. Review generated .sql files
+4. npx drizzle-kit migrate           → applies to database
+```
+
+Output structure:
+
+```
+drizzle/
+├── 0000_init.sql
+├── 0001_add_posts.sql
+├── meta/
+│   ├── 0000_snapshot.json
+│   ├── 0001_snapshot.json
+│   └── _journal.json
+```
+
+Applied migrations tracked in `__drizzle_migrations` table.
+
+### Programmatic migrate
+
+```typescript
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+
+const db = drizzle(process.env.DATABASE_URL);
+
+await migrate(db, { migrationsFolder: "./drizzle" });
+```
+
+## Workflow: Direct Push
+
+Best for rapid prototyping, local dev, serverless databases.
+
+```
+1. Edit TypeScript schema
+2. npx drizzle-kit push              → diffs and applies directly
+```
+
+No SQL files generated. Use `--strict` for approval prompts, `--force` to auto-accept data-loss.
+
+## Custom Migrations
+
+Generate empty migration for manual SQL (seeding, unsupported DDL):
+
+```bash
+npx drizzle-kit generate --custom --name=seed-users
+```
+
+Creates empty `.sql` file to fill in:
+
+```sql
+-- Custom migration: seed-users
+INSERT INTO "users" ("name", "email") VALUES ('Dan', 'dan@example.com');
+INSERT INTO "users" ("name", "email") VALUES ('Andrew', 'andrew@example.com');
+```
+
+## CLI Flags
+
+### generate
+
+```
+--name=<name>         Custom migration name
+--custom              Generate empty SQL for manual migration
+--config=<path>       Config file path (default: drizzle.config.ts)
+```
+
+### migrate
+
+```
+--config=<path>       Config file path
+```
+
+### push
+
+```
+--strict              Require approval before executing SQL
+--verbose             Print all SQL before execution
+--force               Auto-accept data-loss statements
+--config=<path>       Config file path
+```
+
+### pull
+
+```
+--config=<path>       Config file path
+```
+
+### studio
+
+```
+--port=<number>       Studio port (default: 4983)
+--host=<string>       Studio host (default: localhost)
+--config=<path>       Config file path
+```
+
+### Global
+
+```
+--config=<path>       Path to drizzle.config.ts (works with all commands)
+```