@netlify/agent-runner-cli 1.93.1 → 1.94.0-netlifydb.1

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

@@ -0,0 +1,339 @@
+---
+name: netlify-db
+description: Use Netlify DB for relational data storage with a fully managed Postgres database. Use when implementing data models with tables, relationships, SQL queries, transactions, or any data that benefits from a relational schema.
+---
+
+# Netlify DB
+
+Netlify DB 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/db` package.
+
+Prefer Netlify DB over Netlify Blobs when the data is relational or requires SQL queries, unless the user explicitly
+asks for a different storage solution.
+
+## CRITICAL: Temporary package name
+
+The Drizzle ORM Netlify DB adapter has not yet been published to the main `drizzle-orm` package. Until it is, you MUST
+use the `netlify-drizzle-orm-tests` package instead of `drizzle-orm` for ALL Drizzle imports.
+
+This affects:
+- `npm install` commands: use `netlify-drizzle-orm-tests` instead of `drizzle-orm`
+- ALL import statements: use `netlify-drizzle-orm-tests` and `netlify-drizzle-orm-tests/pg-core` and
+  `netlify-drizzle-orm-tests/netlify-db` instead of the `drizzle-orm` equivalents
+
+The `drizzle-kit` package is NOT affected — use the regular `drizzle-kit` package.
+
+## 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/db netlify-drizzle-orm-tests
+npm install -D drizzle-kit
+```
+
+### 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 "netlify-drizzle-orm-tests/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 DB adapter.
+
+```typescript
+// db/index.ts
+import { drizzle } from "netlify-drizzle-orm-tests/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/db/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/db/migrations",
+});
+```
+
+Alternatively, use the helper:
+
+```typescript
+import { defineConfig } from "drizzle-kit";
+import { withNetlifyDB } from "@netlify/db/drizzle";
+
+export default defineConfig({
+  dialect: "postgresql",
+  schema: "./db/schema.ts",
+  ...withNetlifyDB(),
+});
+```
+
+### Step 5: Generate migrations
+
+Run this every time you change the schema:
+
+```bash
+npx drizzle-kit generate
+```
+
+This creates SQL migration files in `netlify/db/migrations/`. DO NOT manually edit the generated migration files.
+DO NOT create the migrations directory manually — `drizzle-kit generate` creates it.
+
+### 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 "netlify-drizzle-orm-tests";
+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/db
+```
+
+### Query with `db.sql`
+
+```typescript
+import { getDatabase } from "@netlify/db";
+
+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/db/migrations/`.
+
+Each migration is a SQL file named `<number>_<slug>.sql`:
+
+```
+netlify/db/migrations/
+├── 001_create-users.sql
+├── 002_add-posts.sql
+└── 003_create-comments.sql
+```
+
+Example migration:
+
+```sql
+-- netlify/db/migrations/001_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 that has already been applied — create a new one instead
+
+## 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/db/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/db/migrations/` to be applied automatically.
+
+Two formats are supported:
+1. SQL files directly in the directory (e.g. `001_create-users.sql`)
+2. Subdirectories containing a `migration.sql` file (e.g. `001_create-users/migration.sql`)
+
+Drizzle Kit generates migrations in the subdirectory format. Both formats can coexist.
+
+## 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.
+
+## Common mistakes to avoid
+
+1. **Wrong migration output directory**: Drizzle Kit defaults to `drizzle/`. You MUST set `out: "netlify/db/migrations"`
+   in `drizzle.config.ts` or use `...withNetlifyDB()`. If migrations are in the wrong directory, they will not be
+   applied.
+
+2. **Using `drizzle-orm` instead of `netlify-drizzle-orm-tests`**: The Netlify DB adapter is not yet in the main
+   `drizzle-orm` package. Use `netlify-drizzle-orm-tests` for all Drizzle imports.
+
+3. **Forgetting to run `drizzle-kit generate`**: After changing `db/schema.ts`, you must run `npx drizzle-kit generate`
+   to create migration files. Schema changes alone do nothing — the migration files are what Netlify applies.
+
+4. **Editing generated migrations**: Never manually edit migrations created by Drizzle Kit. If you need to change
+   something, update the schema and generate a new migration.
+
+5. **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"`).
+
+6. **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.
+
+7. **Applying migrations manually**: NEVER run `drizzle-kit migrate`, `drizzle-kit push`, or execute migration SQL
+   against the database. Only create migration files — the Netlify platform applies them automatically during deploys.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "1.93.1",
+  "version": "1.94.0-netlifydb.1",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",