@netlify/agent-runner-cli 1.105.0-netlifydb.0 → 1.106.0

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

@@ -113,12 +113,49 @@ export default defineConfig({
 
 ### Step 5: Generate migrations
 
-Run this every time you change the schema:
+Every time you change the schema, you MUST generate a new migration with a descriptive name.
+
+**Step 5a — Derive a descriptive slug from the schema changes.**
+
+The slug should summarise what the migration does, using lowercase `snake_case`, a leading imperative verb, and at most
+50 characters. It must match the regex `^[a-z0-9_]{1,50}$` — only lowercase letters, digits, and underscores.
+
+Good examples:
+- `add_users_bio` — added a `bio` column to the `users` table
+- `create_comments_table` — added a new `comments` table
+- `index_posts_author_id` — added an index on `posts.author_id`
+- `drop_legacy_sessions` — removed an obsolete table
+
+Bad examples (do NOT use):
+- `update` (not descriptive)
+- `AddUsersBio` (wrong case)
+- `add-users-bio` (hyphens are not allowed)
+- `misc changes` (spaces are not allowed; also not descriptive)
+
+**Step 5b — Write the slug to the file referenced by the `NETLIFY_DB_MIGRATION_NAME_FILE` environment variable.**
+
+The agent runner provides a file path in the `NETLIFY_DB_MIGRATION_NAME_FILE` environment variable. You MUST read this
+environment variable to find the path on disk, then write the slug to that file. The file lives outside the project
+directory and is managed by the agent runner — do NOT try to read, write, or reason about any file inside the project
+itself for this purpose.
+
+Use `>` (overwrite), not `>>` (append), so the latest slug is the only one recorded:
 
 ```bash
-npx drizzle-kit generate
+MIGRATION_NAME="add_users_bio"
+echo "$MIGRATION_NAME" > "$NETLIFY_DB_MIGRATION_NAME_FILE"
 ```
 
+**Step 5c — Run `drizzle-kit generate` with the same slug passed to `--name`.**
+
+```bash
+npx drizzle-kit generate --name "$MIGRATION_NAME"
+```
+
+Both the file write and the `--name` flag are required: the file write lets the agent runner reuse your slug if it
+has to re-run `drizzle-kit generate` as a safety net, and the `--name` flag ensures the migration file is named
+correctly on this run. If you skip the file write, the agent runner may regenerate the migration with a random name.
+
 This creates SQL migration files in `netlify/database/migrations/`.
 
 ### Step 6: Use the database in functions
@@ -420,3 +457,9 @@ leading to unpredictable and broken behavior.
 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.
+
+6. **Skipping the migration name slug**: When using Drizzle ORM, always derive a descriptive `snake_case` slug, write
+   it to the file referenced by `NETLIFY_DB_MIGRATION_NAME_FILE`, and pass it to `drizzle-kit generate --name
+   "$MIGRATION_NAME"`. Running `drizzle-kit generate` with no `--name` produces an auto-generated random name that
+   doesn't describe the change. The file write is important even if you also pass `--name`: the agent runner re-runs
+   `drizzle-kit generate` as a safety net and needs the slug from the file so the migration name stays consistent.

package/package.json

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