@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/drizzle-orm/examples/02-advanced-migrations.md

@@ -1,191 +0,0 @@
-# Example: Advanced Migrations and Relations
-
-## Scenario
-
-A SaaS application needs to evolve its Drizzle schema. The team must add a multi-tenant structure with organizations, handle a many-to-many relationship between users and organizations with roles, create a custom enum, and write a data migration that backfills existing users into a default organization. The team uses PostgreSQL and `drizzle-kit` for migrations.
-
-## Prompt
-
-"I need to add multi-tenancy to my Drizzle app. Create an organizations table, a junction table linking users to organizations with roles, add a custom status enum, and show me how to write a migration that backfills existing users into a default org. I want both the drizzle-kit workflow and a custom data migration."
-
-## Expected Output
-
-### New Schema Additions
-
-```typescript
-// src/db/schema/organizations.ts
-import {
-  pgTable, serial, varchar, timestamp, pgEnum, integer, index,
-} from "drizzle-orm/pg-core";
-import { relations } from "drizzle-orm";
-
-export const orgStatusEnum = pgEnum("org_status", ["active", "suspended", "archived"]);
-
-export const organizations = pgTable("organizations", {
-  id: serial("id").primaryKey(),
-  name: varchar("name", { length: 200 }).notNull(),
-  slug: varchar("slug", { length: 100 }).notNull().unique(),
-  status: orgStatusEnum("status").notNull().default("active"),
-  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
-  updatedAt: timestamp("updated_at", { withTimezone: true }),
-});
-
-export const organizationsRelations = relations(organizations, ({ many }) => ({
-  memberships: many(orgMemberships),
-}));
-```
-
-```typescript
-// src/db/schema/org-memberships.ts
-import {
-  pgTable, integer, varchar, timestamp, primaryKey, index,
-} from "drizzle-orm/pg-core";
-import { relations } from "drizzle-orm";
-import { users } from "./users";
-import { organizations } from "./organizations";
-
-export const orgMemberships = pgTable(
-  "org_memberships",
-  {
-    userId: integer("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
-    orgId: integer("org_id").notNull().references(() => organizations.id, { onDelete: "cascade" }),
-    role: varchar("role", { length: 20 }).notNull().default("member"),
-    joinedAt: timestamp("joined_at", { withTimezone: true }).notNull().defaultNow(),
-  },
-  (table) => [
-    primaryKey({ columns: [table.userId, table.orgId] }),
-    index("ix_org_memberships_org").on(table.orgId),
-  ]
-);
-
-export const orgMembershipsRelations = relations(orgMemberships, ({ one }) => ({
-  user: one(users, { fields: [orgMemberships.userId], references: [users.id] }),
-  organization: one(organizations, { fields: [orgMemberships.orgId], references: [organizations.id] }),
-}));
-```
-
-### Step 1: Generate the structural migration
-
-```bash
-# Generate migration from schema diff
-npx drizzle-kit generate
-
-# This creates a file like: drizzle/migrations/0003_add_organizations.sql
-# containing CREATE TYPE, CREATE TABLE, and index statements.
-```
-
-### Step 2: Review the generated migration
-
-```sql
--- drizzle/migrations/0003_add_organizations.sql (auto-generated, reviewed)
-CREATE TYPE "org_status" AS ENUM ('active', 'suspended', 'archived');
-
-CREATE TABLE "organizations" (
-  "id" serial PRIMARY KEY NOT NULL,
-  "name" varchar(200) NOT NULL,
-  "slug" varchar(100) NOT NULL,
-  "status" "org_status" DEFAULT 'active' NOT NULL,
-  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
-  "updated_at" timestamp with time zone
-);
-
-CREATE UNIQUE INDEX "organizations_slug_unique" ON "organizations" ("slug");
-
-CREATE TABLE "org_memberships" (
-  "user_id" integer NOT NULL REFERENCES "users"("id") ON DELETE CASCADE,
-  "org_id" integer NOT NULL REFERENCES "organizations"("id") ON DELETE CASCADE,
-  "role" varchar(20) DEFAULT 'member' NOT NULL,
-  "joined_at" timestamp with time zone DEFAULT now() NOT NULL,
-  CONSTRAINT "org_memberships_pkey" PRIMARY KEY ("user_id", "org_id")
-);
-
-CREATE INDEX "ix_org_memberships_org" ON "org_memberships" ("org_id");
-```
-
-### Step 3: Write a custom data migration
-
-```typescript
-// scripts/migrate-backfill-default-org.ts
-import { db } from "../src/db";
-import { organizations, orgMemberships } from "../src/db/schema";
-import { users } from "../src/db/schema";
-
-async function backfillDefaultOrg() {
-  await db.transaction(async (tx) => {
-    // 1. Create the default organization
-    const [defaultOrg] = await tx
-      .insert(organizations)
-      .values({ name: "Default Organization", slug: "default" })
-      .returning();
-
-    // 2. Fetch all existing users
-    const allUsers = await tx.select({ id: users.id }).from(users);
-
-    // 3. Batch insert memberships (500 at a time to avoid parameter limits)
-    const batchSize = 500;
-    for (let i = 0; i < allUsers.length; i += batchSize) {
-      const batch = allUsers.slice(i, i + batchSize);
-      await tx.insert(orgMemberships).values(
-        batch.map((u) => ({
-          userId: u.id,
-          orgId: defaultOrg.id,
-          role: "member" as const,
-        }))
-      );
-    }
-
-    console.log(`Backfilled ${allUsers.length} users into default org.`);
-  });
-}
-
-backfillDefaultOrg().catch(console.error).finally(() => process.exit());
-```
-
-### Step 4: Apply and verify
-
-```bash
-# Apply the structural migration
-npx drizzle-kit migrate
-
-# Run the data backfill
-npx tsx scripts/migrate-backfill-default-org.ts
-
-# Verify: check migration status
-npx drizzle-kit check
-```
-
-### Querying many-to-many relations
-
-```typescript
-// Fetch a user with all their organizations
-const userWithOrgs = await db.query.users.findFirst({
-  where: eq(users.id, userId),
-  with: {
-    memberships: {
-      with: { organization: true },
-    },
-  },
-});
-
-// Access: userWithOrgs.memberships[0].organization.name
-// Access: userWithOrgs.memberships[0].role
-
-// Fetch all members of an organization
-const orgMembers = await db.query.organizations.findFirst({
-  where: eq(organizations.id, orgId),
-  with: {
-    memberships: {
-      with: { user: true },
-    },
-  },
-});
-```
-
-## Key Decisions
-
-- **`pgEnum` for status** — uses PostgreSQL native ENUM, enforced at the database level, fully typed in Drizzle.
-- **Composite primary key on junction table** — prevents duplicate memberships and serves as the clustered index.
-- **Separate data migration script** — drizzle-kit auto-generated migrations handle DDL but not data transformations. Custom scripts wrapped in `db.transaction()` ensure atomicity.
-- **Batch inserts in data migration** — PostgreSQL has a parameter limit (~65535). Batching prevents exceeding it for large user tables.
-- **`onDelete: "cascade"` on junction foreign keys** — removing a user or org automatically cleans up memberships.
-- **`drizzle-kit generate` then review** — never run `drizzle-kit push` in production. Always generate, review, then apply.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/drizzle-orm/references/migrations.md

@@ -1,236 +0,0 @@
-# Migrations
-
-Load this when creating, reviewing, or troubleshooting drizzle-kit migrations, push vs generate workflows, or migration chain management.
-
-## drizzle.config.ts setup
-
-```typescript
-import { defineConfig } from "drizzle-kit";
-
-export default defineConfig({
-  schema: "./src/db/schema/index.ts",  // Must export all tables
-  out: "./drizzle/migrations",          // Migration output directory
-  dialect: "postgresql",                // "postgresql" | "sqlite" | "mysql"
-  dbCredentials: {
-    url: process.env.DATABASE_URL!,
-  },
-  verbose: true,
-  strict: true,   // Fail on destructive changes without confirmation
-});
-```
-
-### Configuration rules
-
-- `schema` must point to a file that exports ALL table definitions. Missing exports = missing migrations.
-- `out` is where migration SQL files are written. Commit this directory to version control.
-- `dialect` must match your schema imports (`pg-core`, `sqlite-core`, `mysql-core`).
-- Use `strict: true` to catch destructive changes (column drops, type changes) before they hit production.
-
-## Generate vs Push
-
-### `drizzle-kit generate` (production workflow)
-
-```bash
-# Generate migration SQL from schema changes
-npx drizzle-kit generate
-
-# Apply pending migrations
-npx drizzle-kit migrate
-```
-
-- Creates versioned SQL files in the `out` directory.
-- Each migration has a timestamp-based name and sequential ordering.
-- Migration files are idempotent: they track which have been applied in a `__drizzle_migrations` table.
-- Always review generated SQL before applying.
-
-### `drizzle-kit push` (development only)
-
-```bash
-# Apply schema directly to database (no migration files)
-npx drizzle-kit push
-```
-
-- Compares schema to live database and applies changes directly.
-- No migration files generated. No rollback capability.
-- Use ONLY for rapid prototyping and development databases.
-- Never use push in CI or production pipelines.
-
-## Migration workflow
-
-### Step-by-step production workflow
-
-```bash
-# 1. Modify schema files
-# Edit src/db/schema/users.ts
-
-# 2. Generate migration
-npx drizzle-kit generate
-
-# 3. Review the generated SQL
-cat drizzle/migrations/0005_add_role_column.sql
-
-# 4. Edit if needed (add data migration, fix rollback)
-# Edit the SQL file directly
-
-# 5. Test locally
-npx drizzle-kit migrate
-
-# 6. Commit schema + migration files together
-git add src/db/schema/ drizzle/migrations/
-git commit -m "feat: add role column to users"
-```
-
-### Running migrations in code
-
-```typescript
-import { drizzle } from "drizzle-orm/postgres-js";
-import { migrate } from "drizzle-orm/postgres-js/migrator";
-import postgres from "postgres";
-
-const migrationClient = postgres(process.env.DATABASE_URL!, { max: 1 });
-const db = drizzle(migrationClient);
-
-await migrate(db, { migrationsFolder: "./drizzle/migrations" });
-await migrationClient.end();
-```
-
-- Use a separate connection for migrations (single connection, not pooled).
-- Run migrations before starting the application server.
-- In serverless, run migrations as a deployment step, not at cold start.
-
-## Common migration patterns
-
-### Adding a non-nullable column to existing table
-
-```sql
--- Generated migration (may need manual editing)
-ALTER TABLE "users" ADD COLUMN "role" varchar(20);
-
--- Manual addition: backfill + set NOT NULL
-UPDATE "users" SET "role" = 'member' WHERE "role" IS NULL;
-ALTER TABLE "users" ALTER COLUMN "role" SET NOT NULL;
-ALTER TABLE "users" ALTER COLUMN "role" SET DEFAULT 'member';
-```
-
-- drizzle-kit generates the `ADD COLUMN` but may not handle the backfill.
-- Edit the migration SQL to add the UPDATE and ALTER steps.
-
-### Renaming a column
-
-```sql
--- drizzle-kit may generate DROP + ADD instead of RENAME
--- Replace with:
-ALTER TABLE "users" RENAME COLUMN "name" TO "display_name";
-```
-
-- drizzle-kit cannot detect renames. It generates a drop + add which loses data.
-- Always review generated migrations for rename scenarios.
-
-### Creating an index concurrently (Postgres)
-
-```sql
--- Add to migration manually
-CREATE INDEX CONCURRENTLY "ix_users_email" ON "users" ("email");
-```
-
-- Standard CREATE INDEX locks the table. CONCURRENTLY avoids this.
-- Must run outside a transaction. May need to split into a separate migration step.
-
-### Data migration
-
-```sql
--- Separate migration file for data changes
-UPDATE "users" SET "slug" = lower(replace("display_name", ' ', '-'))
-  WHERE "slug" IS NULL;
-```
-
-- Keep data migrations in separate files from schema migrations.
-- For large tables, batch the update to avoid long-running transactions.
-
-## CI checks
-
-```bash
-# 1. Generate to check for drift (should produce no new files)
-npx drizzle-kit generate --name drift-check
-# If new files are generated, schema and migrations are out of sync
-
-# 2. Test migration on clean database
-npx drizzle-kit migrate
-
-# 3. Verify schema matches expectations
-npx drizzle-kit introspect
-```
-
-### CI pipeline example
-
-```yaml
-# GitHub Actions
-migration-check:
-  runs-on: ubuntu-latest
-  services:
-    postgres:
-      image: postgres:16
-      env:
-        POSTGRES_PASSWORD: test
-        POSTGRES_DB: test_db
-      ports:
-        - 5432:5432
-  steps:
-    - uses: actions/checkout@v4
-    - run: npm ci
-    - run: npx drizzle-kit migrate
-      env:
-        DATABASE_URL: postgres://postgres:test@localhost:5432/test_db
-    - run: npx drizzle-kit generate --name ci-drift-check
-    - run: |
-        if [ -n "$(git status --porcelain drizzle/)" ]; then
-          echo "Schema drift detected! Run 'npx drizzle-kit generate' locally."
-          exit 1
-        fi
-```
-
-## Migration journal
-
-drizzle-kit maintains a `_journal.json` in the migrations directory:
-
-```json
-{
-  "entries": [
-    { "idx": 0, "when": 1705000000, "tag": "0000_init", "breakpoints": true },
-    { "idx": 1, "when": 1705100000, "tag": "0001_add_teams", "breakpoints": true }
-  ]
-}
-```
-
-- Do not manually edit `_journal.json`. drizzle-kit manages it.
-- If journal gets corrupted, regenerate with `drizzle-kit generate` from a clean state.
-- Merge conflicts in journal should be resolved by keeping both entries in order.
-
-## Rollback strategy
-
-drizzle-kit does not generate down migrations automatically.
-
-### Manual rollback approach
-
-1. Keep a `rollback/` directory with reverse SQL for critical migrations.
-2. Test rollback scripts alongside forward migrations.
-3. For simple additions, rollback is `DROP COLUMN` or `DROP TABLE`.
-4. For data migrations, rollback may require a backup restore.
-
-### Forward-only strategy (recommended for most teams)
-
-1. Never drop columns in the same release that stops reading them.
-2. Deploy in phases: stop writing -> stop reading -> drop column.
-3. Keep old columns nullable during transition.
-4. This avoids needing rollback for schema changes.
-
-## Best practices checklist
-
-- Every schema change has a corresponding generated migration.
-- Migration SQL is reviewed before merge (treat like application code).
-- CI runs full migration chain on a clean database.
-- CI checks for schema-migration drift.
-- Data migrations are separate files from schema migrations.
-- `push` is never used in CI or production.
-- Destructive changes (drops, renames) are deployed in phases.
-- Migration files are committed alongside schema changes in the same PR.