@netlify/agent-runner-cli 1.103.1 → 1.104.0

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

@@ -1,6 +1,6 @@
 ---
 name: netlify-database
-description: Use Netlify Database 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.
+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
@@ -8,8 +8,8 @@ description: Use Netlify Database for relational data storage with a fully manag
 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 when the data is relational or requires SQL queries, unless the user explicitly
-asks for a different storage solution.
+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
 
@@ -119,8 +119,7 @@ Run this every time you change the schema:
 npx drizzle-kit generate
 ```
 
-This creates SQL migration files in `netlify/database/migrations/`. DO NOT manually edit the generated migration files.
-DO NOT create the migrations directory manually — `drizzle-kit generate` creates it.
+This creates SQL migration files in `netlify/database/migrations/`.
 
 ### Step 6: Use the database in functions
 
@@ -150,17 +149,6 @@ export const config: Config = {
 };
 ```
 
-### Modifying an existing schema
-
-When adding columns, tables, or changing the schema in an existing project:
-
-1. Update the Drizzle schema definition with your changes
-2. Run `npx drizzle-kit generate` — this is REQUIRED, not optional
-3. Verify new migration files appear in `netlify/database/migrations/`
-4. Update any application code that uses the changed tables
-
-Do NOT skip step 2. The database will not reflect your schema changes without a generated migration.
-
 ### Drizzle ORM query reference
 
 ```typescript
@@ -276,15 +264,15 @@ Each migration is a SQL file named `<number>_<slug>.sql`:
 
 ```
 netlify/database/migrations/
-├── 001_create-users.sql
-├── 002_add-posts.sql
-└── 003_create-comments.sql
+├── 20260417143022_create-users.sql
+├── 20260418091500_add-posts.sql
+└── 20260419112330_create-comments.sql
 ```
 
 Example migration:
 
 ```sql
--- netlify/database/migrations/001_create-users.sql
+-- netlify/database/migrations/20260417143022_create-users.sql
 CREATE TABLE users (
   id SERIAL PRIMARY KEY,
   name TEXT NOT NULL,
@@ -297,7 +285,9 @@ 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
+- 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
 
@@ -314,10 +304,8 @@ Netlify applies migrations automatically during deploys:
 Migrations MUST be in `netlify/database/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.
+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
 
@@ -325,6 +313,92 @@ Drizzle Kit generates migrations in the subdirectory format. Both formats can co
 - **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
+
+Before acting on migrations (generating, deleting, regenerating, resetting), check the current state. The
+`netlify db status` command is the source of truth for which migrations are applied where.
+
+```bash
+netlify db status
+```
+
+The command automatically targets your preview database branch — `NETLIFY_DB_BRANCH` is pre-set for you, so
+no flags are needed.
+
+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 — stop and investigate)
+- **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.
+
+Run this before any migration change you're not sure about. If `missing on disk` is non-empty, run
+`netlify db migrations pull --force` to restore the missing files from the branch before generating any new
+migrations. Note that this also overwrites any unapplied migration files you have locally — regenerate those
+with `npx drizzle-kit generate` afterwards if needed.
+
+## 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
 
@@ -336,20 +410,13 @@ Drizzle Kit generates migrations in the subdirectory format. Both formats can co
    `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. **NEVER skip migration generation after schema changes**: Any code that assumes a different database schema requires
-   a corresponding migration in `netlify/database/migrations/`. With Drizzle ORM, run `npx drizzle-kit generate` after
-   updating the schema definition. With the native driver, write a SQL migration file. Schema changes alone do
-   nothing — the migration files are what Netlify applies. The application WILL break without them.
-
-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`
+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"`).
 
-6. **Creating tables with raw SQL when using Drizzle**: If you use Drizzle ORM, define all tables in `db/schema.ts`
+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.
 
-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.
+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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "1.103.1",
+  "version": "1.104.0",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -83,7 +83,8 @@
   "dependencies": {
     "@anthropic-ai/claude-code": "2.1.111",
     "@anthropic-ai/sdk": "0.90.0",
-    "@google/gemini-cli": "0.38.1",
+    "@google/gemini-cli": "0.38.2",
+    "@netlify/database-proxy": "^0.1.2",
     "@netlify/otel": "^5.1.5",
     "@netlify/ts-cli": "^1.0.4",
     "@openai/codex": "0.121.0",