@netlify/agent-runner-cli 1.29.1 → 1.30.1-broken.0

package/dist/skills/netlify-database/SKILL.md

@@ -0,0 +1,423 @@
+---
+name: netlify-database
+description: Use Netlify Database to store application data — records, collections, lists, user data, or any structured information. Provides a fully managed Postgres database. Use for CRUD operations, queryable data, or anything you would naturally model as rows in a table. Use Blobs only for files, binary assets, or cached responses.
+---
+
+# Netlify Database
+
+Netlify Database is a fully managed Postgres database built into the Netlify platform. It handles provisioning, migrations,
+and database branching automatically. There is no setup beyond installing the `@netlify/database` package.
+
+Prefer Netlify Database over Netlify Blobs for any application data — records, collections, lists, user-generated content,
+or anything you would store as rows. Use Blobs only for files, binary assets (images, video), or cached responses.
+
+## CRITICAL: Use the `@beta` dist-tag for Drizzle
+
+The Netlify Database adapter for Drizzle ORM only exists on the `beta` release line of `drizzle-orm`. You MUST install
+both `drizzle-orm` and `drizzle-kit` from the `@beta` dist-tag — the default `latest` versions do not include the
+Netlify Database adapter and will fail.
+
+This affects:
+- `npm install` commands: always install `drizzle-orm@beta` and `drizzle-kit@beta` (never `drizzle-orm` or
+  `drizzle-kit` without the tag).
+- Import paths: use `drizzle-orm`, `drizzle-orm/pg-core`, and `drizzle-orm/netlify-db` as normal. No package
+  name rewriting is needed — the `@beta` tag only affects the installed version, not the imports.
+
+If you forget the `@beta` tag, `drizzle-kit generate` will error with a message about being outdated, or the
+`drizzle-orm/netlify-db` import will fail to resolve.
+
+## CRITICAL: Database schema changes always require migrations
+
+Any code change that assumes a different database schema (adding tables, adding columns, renaming fields, changing types,
+adding indexes, etc.) will only work if a corresponding migration exists in `netlify/database/migrations/`. Without a
+migration, the database schema will not change and the application will break at runtime.
+
+This applies regardless of whether you are using Drizzle ORM or the native `@netlify/database` driver:
+- **With Drizzle ORM**: Update the schema definition, then run `npx drizzle-kit generate`
+- **With native driver**: Write a new SQL migration file in `netlify/database/migrations/`
+
+Never consider a schema change complete without a corresponding migration file.
+
+## Setup with Drizzle ORM (recommended)
+
+This is the recommended approach. It gives you type-safe schema definitions, a query builder, and automatic migration
+generation.
+
+### Step 1: Install packages
+
+```bash
+npm install @netlify/database drizzle-orm@beta
+npm install -D drizzle-kit@beta
+```
+
+### Step 2: Create the schema file
+
+Create `db/schema.ts` at the project root. Define all your tables here using Drizzle's schema builder.
+
+```typescript
+// db/schema.ts
+import { pgTable, serial, text, timestamp, integer } from "drizzle-orm/pg-core";
+
+export const users = pgTable("users", {
+  id: serial().primaryKey(),
+  name: text().notNull(),
+  email: text().notNull().unique(),
+  createdAt: timestamp("created_at").defaultNow(),
+});
+```
+
+When adding tables with foreign keys:
+
+```typescript
+export const posts = pgTable("posts", {
+  id: serial().primaryKey(),
+  title: text().notNull(),
+  content: text().notNull().default(""),
+  authorId: integer("author_id").notNull().references(() => users.id),
+  createdAt: timestamp("created_at").defaultNow(),
+});
+```
+
+IMPORTANT: Use snake_case strings for column names (e.g. `"created_at"`, `"author_id"`) to match Postgres conventions.
+The Drizzle column variable names can be camelCase.
+
+### Step 3: Create the database client
+
+Create `db/index.ts`. This file initializes the Drizzle client with the native Netlify Database adapter.
+
+```typescript
+// db/index.ts
+import { drizzle } from "drizzle-orm/netlify-db";
+import * as schema from "./schema.js";
+
+export const db = drizzle({ schema });
+```
+
+The connection is configured automatically — no connection string needed.
+
+### Step 4: Configure Drizzle Kit
+
+Create `drizzle.config.ts` at the project root. The `out` property MUST be set to `netlify/database/migrations` for
+Netlify to automatically apply migrations.
+
+```typescript
+// drizzle.config.ts
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  dialect: "postgresql",
+  schema: "./db/schema.ts",
+  out: "netlify/database/migrations",
+});
+```
+
+### Step 5: Generate migrations
+
+Every time you change the schema, run `drizzle-kit generate`:
+
+```bash
+npx drizzle-kit generate
+```
+
+This creates SQL migration files in `netlify/database/migrations/`.
+
+### Step 6: Use the database in functions
+
+```typescript
+// netlify/functions/api.ts
+import type { Config } from "@netlify/functions";
+import { db } from "../../db/index.js";
+import { users } from "../../db/schema.js";
+
+export default async (req: Request) => {
+  if (req.method === "GET") {
+    const allUsers = await db.select().from(users);
+    return Response.json(allUsers);
+  }
+
+  if (req.method === "POST") {
+    const { name, email } = await req.json();
+    const [user] = await db.insert(users).values({ name, email }).returning();
+    return Response.json(user, { status: 201 });
+  }
+
+  return new Response("Method not allowed", { status: 405 });
+};
+
+export const config: Config = {
+  path: "/api/users",
+};
+```
+
+### Drizzle ORM query reference
+
+```typescript
+import { eq, desc, and, or, like, sql } from "drizzle-orm";
+import { db } from "./db/index.js";
+import { users, posts } from "./db/schema.js";
+
+// Select all
+const allUsers = await db.select().from(users);
+
+// Select with condition
+const user = await db.select().from(users).where(eq(users.id, 1));
+
+// Select with ordering
+const sorted = await db.select().from(users).orderBy(desc(users.createdAt));
+
+// Select with limit
+const first10 = await db.select().from(users).limit(10);
+
+// Select specific columns
+const names = await db.select({ name: users.name }).from(users);
+
+// Insert one row
+const [inserted] = await db.insert(users).values({ name: "Ada", email: "ada@example.com" }).returning();
+
+// Insert multiple rows
+await db.insert(users).values([
+  { name: "Ada", email: "ada@example.com" },
+  { name: "Bob", email: "bob@example.com" },
+]);
+
+// Update
+await db.update(users).set({ name: "Ada Lovelace" }).where(eq(users.id, 1));
+
+// Delete
+await db.delete(users).where(eq(users.id, 1));
+
+// Join
+const postsWithAuthors = await db
+  .select()
+  .from(posts)
+  .innerJoin(users, eq(posts.authorId, users.id));
+```
+
+## Setup with native driver (alternative)
+
+Use this when you prefer raw SQL or don't want Drizzle ORM.
+
+### Install
+
+```bash
+npm install @netlify/database
+```
+
+### Query with `db.sql`
+
+```typescript
+import { getDatabase } from "@netlify/database";
+
+const db = getDatabase();
+
+// Select
+const users = await db.sql`SELECT * FROM users`;
+
+// Select with parameters (automatically parameterized)
+const user = await db.sql`SELECT * FROM users WHERE id = ${userId}`;
+
+// Insert with RETURNING
+const [newUser] = await db.sql`
+  INSERT INTO users (name, email)
+  VALUES (${"Ada"}, ${"ada@example.com"})
+  RETURNING *
+`;
+
+// Update
+await db.sql`UPDATE users SET name = ${"Ada Lovelace"} WHERE id = ${1}`;
+
+// Delete
+await db.sql`DELETE FROM users WHERE id = ${1}`;
+
+// Bulk insert
+const data = db.sql.values([
+  ["Ada", "ada@example.com"],
+  ["Bob", "bob@example.com"],
+]);
+await db.sql`INSERT INTO users (name, email) VALUES ${data}`;
+```
+
+### Transactions with `db.pool`
+
+```typescript
+const db = getDatabase();
+
+const client = await db.pool.connect();
+try {
+  await client.query("BEGIN");
+  await client.query("INSERT INTO users (name, email) VALUES ($1, $2)", ["Ada", "ada@example.com"]);
+  await client.query("INSERT INTO posts (author_id, title) VALUES ($1, $2)", [1, "First post"]);
+  await client.query("COMMIT");
+} catch (e) {
+  await client.query("ROLLBACK");
+  throw e;
+} finally {
+  client.release();
+}
+```
+
+### Write migrations manually
+
+When using the native driver, write SQL migration files by hand in `netlify/database/migrations/`.
+
+Each migration is a SQL file named `<number>_<slug>.sql`:
+
+```
+netlify/database/migrations/
+├── 20260417143022_create-users.sql
+├── 20260418091500_add-posts.sql
+└── 20260419112330_create-comments.sql
+```
+
+Example migration:
+
+```sql
+-- netlify/database/migrations/20260417143022_create-users.sql
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  name TEXT NOT NULL,
+  email TEXT UNIQUE NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+Rules for migration names:
+- `number` is any sequence of digits (e.g. `001`, `0001`, or a Unix timestamp)
+- `slug` contains only lowercase letters, numbers, hyphens, and underscores
+- Migrations are sorted lexicographically and applied in order
+- NEVER modify a migration file once it has been applied to any database (local, preview, or production).
+  Unapplied migration files can be freely deleted and regenerated; see "Iterating on migrations within a
+  session" below.
+
+## Migrations: how they work
+
+IMPORTANT: You must NEVER apply migrations yourself. Your job is only to CREATE migration files — either by running
+`npx drizzle-kit generate` (when using Drizzle ORM) or by writing SQL files in `netlify/database/migrations/` (when using
+the native driver). The Netlify platform applies migrations automatically at the right point in the deploy lifecycle.
+Do NOT run `drizzle-kit migrate`, `drizzle-kit push`, or execute migration SQL directly against the database.
+
+Netlify applies migrations automatically during deploys:
+
+- **Production deploys:** Applied immediately before the deploy is published. A failure blocks publishing.
+- **Deploy previews:** Applied on every new deploy, immediately before it becomes available. A failure fails the deploy.
+
+Migrations MUST be in `netlify/database/migrations/` to be applied automatically.
+
+Two formats are supported:
+1. SQL files directly in the directory (e.g. `20260417143022_create-users.sql`)
+2. Subdirectories containing a `migration.sql` file (e.g. `20260417143022_create-users/migration.sql`)
+
+## Database branches
+
+- **Production deploys** access the main database only.
+- **Deploy previews** get their own isolated database branch with a copy of production data.
+- Changes in a deploy preview's branch never affect the production database.
+- You do NOT need to do anything to enable branching — it is automatic.
+- A preview branch persists across multiple runs in the same session. Migrations you applied in an earlier run
+  remain applied when a later run starts, and any test data you inserted persists too. This matters when iterating
+  on migrations — see "Iterating on migrations within a session" below.
+
+## Inspecting migration state
+
+The current database state — which migrations are already applied to your preview branch, and which migration
+files exist on disk but haven't been applied yet — is included in your context at the start of the run, under
+the "Current Netlify Database state" heading. Read that list before planning any migration work. You do not
+need to run `netlify db status` at the start of a task to get this information.
+
+If you need to re-check state mid-session — typically after generating a new migration, applying migrations, or
+running `netlify db migrations reset` — run:
+
+```bash
+netlify db status
+```
+
+The command targets your preview database branch automatically (`NETLIFY_DB_BRANCH` is pre-set).
+
+It reports:
+- **Applied**: migrations that have been applied to the branch
+- **Pending**: migration files that exist locally but have not been applied
+- **Missing on disk**: migrations applied on the server but not present locally (drift — this is a serious
+  state; never intentionally create it)
+- **Out of order**: pending migrations whose prefix sorts before an already-applied migration. The platform
+  rejects these, so fix via the "Rule of thumb" below (reset + regenerate). If `drizzle-kit generate` then
+  reports no changes, the out-of-order files were redundant and deleting them was the complete fix.
+
+## Iterating on migrations within a session
+
+A single agent session can run multiple times, and all runs share one preview database branch. When you realize
+a migration from an earlier run needs to change, the correct action depends on whether the migration has been
+applied to the database yet.
+
+### Rule of thumb
+
+- If a migration has been **applied** to any database (local dev DB, preview branch, or production), treat it
+  as immutable. Roll forward with a new migration that applies the correction. This is always safe.
+- If a migration is **not yet applied** anywhere (it's only on disk), don't edit it in place. Run
+  `netlify db migrations reset` to delete it, update `db/schema.ts` to reflect your new intent, then run
+  `npx drizzle-kit generate` to produce a fresh migration. Editing SQL or snapshot files directly can
+  desync Drizzle Kit's internal state and produce broken migrations on the next generate.
+
+### `netlify db migrations reset` — cleaning up unapplied migrations
+
+`netlify db migrations reset` deletes local migration files that have **not yet been applied** to your preview
+branch. Applied migrations and their data are left alone.
+
+```bash
+netlify db migrations reset
+```
+
+Typical use: after a rebase pulls in new migrations from main, you may have locally-generated migrations that
+now conflict with or duplicate main's work. Running `netlify db migrations reset` clears those unapplied files
+so you can regenerate cleanly.
+
+The command is safe — it cannot remove migrations that have been applied, so it cannot produce a broken
+database state.
+
+## Connecting to the database
+
+Use `netlify db connect` to query the database directly for troubleshooting or inspecting the current schema. Always use
+the `--query` flag for one-shot execution — do NOT use interactive mode.
+
+```bash
+# Inspect the current schema
+netlify db connect --query "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"
+
+# Check columns on a table
+netlify db connect --query "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = 'users'"
+
+# Read data
+netlify db connect --query "SELECT * FROM users LIMIT 10"
+
+# Get results as JSON
+netlify db connect --query "SELECT * FROM users LIMIT 10" --json
+```
+
+The database connection is read-only. You can use it to inspect the schema and read data, but you cannot insert, update,
+or delete rows.
+
+**CRITICAL: NEVER run DDL statements (CREATE, ALTER, DROP, TRUNCATE) or any other schema-mutating queries through
+`netlify db connect`.** The only supported way to change the database schema is through migration files in
+`netlify/database/migrations/`. Running DDL directly will cause the migration state to diverge from the actual schema,
+leading to unpredictable and broken behavior.
+
+## Common mistakes to avoid
+
+1. **Wrong migration output directory**: Drizzle Kit defaults to `drizzle/`. You MUST set
+   `out: "netlify/database/migrations"` in `drizzle.config.ts`. If migrations are in the wrong directory, they will not
+   be applied.
+
+2. **Forgetting the `@beta` dist-tag**: The Netlify Database adapter only exists on `drizzle-orm@beta` and
+   `drizzle-kit@beta`. Installing `drizzle-orm` or `drizzle-kit` without the `@beta` tag pulls the `latest` releases,
+   which lack the adapter and will fail. Always install with `drizzle-orm@beta` and `drizzle-kit@beta`.
+
+3. **Missing `.js` extension in imports**: When using TypeScript with ES modules, import paths should include the `.js`
+   extension (e.g. `from "./schema.js"`, `from "../../db/index.js"`).
+
+4. **Creating tables with raw SQL when using Drizzle**: If you use Drizzle ORM, define all tables in `db/schema.ts`
+   and generate migrations with `drizzle-kit generate`. Do not write raw `CREATE TABLE` SQL — the schema file is the
+   source of truth.
+
+5. **Misunderstanding `netlify db migrations reset`**: This command only deletes migration files that have
+   **not yet been applied** to your preview branch. It cannot undo an already-applied migration — to change
+   something that's already applied, you must roll forward with a new migration.
+