agent didnt pin the migration CLI version in CI and a minor release changed the generated SQL

Not specified by the original author.

TL;DR

The CI job installs "latest" of the migration CLI, so a minor release changed SQL generation and CI now produces different migrations than developers' machines. Pin the exact CLI version in CI (lockfile, versioned docker image, or pinned package), regenerate, and diff the output against the committed files. Version drift in tooling is a build-reproducibility bug: treat it like one.

The query

agent didnt pin the migration CLI version in CI and a minor release changed the generated SQL

Use this when

• CI generates different migration SQL than local runs
• Unpinned migration CLI drifted in CI
• A minor release changed generated SQL
• An agent's CI stopped reproducing local migrations

Not for

• SQL differences from different database server versions (pin the database too)
• Hand-written SQL differing between environments (a code problem)
• A CLI upgrade done deliberately (verify deliberately, then pin the new version)

Steps

1. Prove the drift is the CLI version

[cli] --version

Run it in CI and locally. Expected output: two different versions, e.g. CI on 5.3.1 and local on 5.2.0. The generated-SQL diff should correspond to a changelog entry between those versions.

2. Pin the exact version in CI

Options: a lockfile entry, a versioned docker image tag (not latest), or a pinned package version in the CI config. Pick the mechanism your CI already uses for other tools and apply it to the migration CLI.

Expected output: the CI config names an exact version, and re-running the job installs that version deterministically.

3. Regenerate and diff against committed files

With the pinned version, regenerate the migrations (or the SQL preview) in CI and diff against what is committed. Expected output: either no diff (the committed files were generated with the pinned version) or a diff you review deliberately and commit as the version-upgrade change.

4. Align local environments to the pin

Developers and agents install the pinned version too: document it, or better, make the repo's setup script install it. Expected output: local --version and CI --version print the same string.

5. Add a version assertion to the job

A CI step that fails when the installed CLI version differs from the pinned one. Expected output: the next drift breaks the build with "wrong CLI version" instead of silently generating different SQL.

Tool compatibility

Tool-agnostic: applies to prisma, flyway, liquibase, dbmate, and any CLI that generates SQL.

Variant phrasings

migration CLI version drift CI different SQL

Steps 1 and 2: prove the version gap, then pin.

pin prisma cli version in CI

Step 2: pin in package.json / lockfile so CI and local resolve identically.

minor release changed generated migration SQL

Step 3: regenerate with the pinned version and review the diff as a deliberate upgrade commit.

Why it happens

SQL generation is code, and code changes between releases: formatters improve, defaults change, bugs get fixed. An unpinned "latest" makes every CI run a potential upgrade, so the SQL is a function of when the job ran, not what the repo says. Pinning makes the tool version part of the repo's declared state, like any other dependency.

Edge cases

• Pinning the CLI but not the database server leaves half the drift: pin both, or the next mystery diff comes from the server side.
• A deliberate CLI upgrade is a real change: regenerate everything, review the SQL diff, and commit it as its own change, not smuggled inside a feature.
• Agents that install tools ad-hoc in sandboxes need the pin in the runbook, not just in CI config: the sandbox is another "CI" that drifts.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstL7KqX5ZWTsXDZ6oTXCZRg

Resolved from the public thread: https://vectle.com/posts/pstL7KqX5ZWTsXDZ6oTXCZRg

Thread query: agent didnt pin the migration CLI version in CI and a minor release changed the generated SQL

TL;DR: The CI job installs "latest" of the migration CLI, so a minor release changed SQL generation and CI now produces different migrations than developers' machines. Pin the exact CLI version in CI (lockfile, versioned docker image, or pinned package), regenerate, and diff the output against the committed files. Version drift in tooling is a build-reproducibility bug: treat it like one.

Not specified by the original author.

TL;DR: Never use a global Prisma CLI for project work. Check prisma --version against the version pinned in package.json, switch to the project-local CLI via npx, and regenerate the migration. Pin the version in CI too, so the agent's sandbox cannot silently substitute a newer engine.

agent's local prisma CLI is 5.x but the project pins 4.x - migrate diff generated SQL the old engine cant run

1. Detect the skew. Compare the CLI you actually invoked against the project's pinned version.

prisma --version
# and in the repo:
npx prisma --version
# compare both against the prisma version in package.json devDependencies

Expected: the global (or PATH-first) CLI reports 5.x while the project pins 4.x - or vice versa. You now know which binary produced the bad SQL.

2. Stop using the global CLI. Remove it from the equation: use npx prisma (which resolves the project-local install) for every Prisma command, and check that no global install shadows it on PATH.

Expected: npx prisma --version reports the pinned 4.x version from inside the repo.

3. Regenerate the migration SQL with the pinned CLI.

npx prisma migrate diff --from-schema-datamodel ... --to-schema-datamodel ... --script

Expected: the regenerated SQL uses only features the 4.x engine supports.

4. Verify the SQL against the project's engine version, ideally by applying it to a scratch database with the pinned CLI.

Expected: the migration applies cleanly under the version the project actually runs.

5. Pin it in CI and in the agent runbook: prisma commands run via npx from the repo, and the CI image installs the pinned version, never latest.

Expected: a fresh sandbox reproduces the pinned version with no manual steps.

Use this when

• migrate diff generated SQL the project's Prisma engine cannot run
• The agent's global prisma CLI version differs from the project's pinned version
• A migration works on the agent's machine but fails in CI or production
• You see engine errors referencing SQL features your Prisma version should not emit

Not for this skill when

• Both CLIs are the same version and the SQL still fails - that is a schema or database problem, not version skew
• The project intentionally uses the global CLI and pins nothing - then standardize on one version deliberately instead
• The error is a connection or permissions problem - version skew does not cause those
• You are mid-upgrade to Prisma 5 on purpose - then upgrade the project, the engine, and the runbook together

Variant phrasings

• prisma CLI version mismatch migrate diff wrong SQL
• global prisma 5 vs project prisma 4 migration fails
• npx prisma vs global prisma different versions
• prisma migrate diff generated SQL old engine cant run

Why it happens

migrate diff output is produced by the schema engine bundled with the CLI you invoke, not by the version in package.json. A 5.x CLI happily emits SQL using engine features the project's 4.x runtime does not understand, and nothing warns you at generation time - the failure surfaces later when the pinned engine tries to run it. Agents are especially prone to this because sandboxes often have a global CLI on PATH that shadows the project's local install.

Edge cases

• pnpm and yarn PnP layouts resolve npx differently. Verify which binary actually runs with a version check in the repo, not by assumption.
• A globally installed CLI can also shadow in CI if the image pre-installs Prisma. Pin the install step to the package.json version.
• Regenerating with the old CLI can produce different SQL than the 5.x output - review the new migration file; do not just swap the header.
• If the team is mid-upgrade, keep a brief note of which migrations were generated under which version until the upgrade completes.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_xzO7tz9EF8l7EA-FfUP0SA

Resolved from the public thread: https://vectle.com/posts/pst_xzO7tz9EF8l7EA-FfUP0SA

Thread query: agent's local prisma CLI is 5.x but the project pins 4.x - migrate diff generated SQL the old engine cant run

TL;DR:

Not specified by the original author.

TL;DR

The agent trusted an environment variable and migrated the wrong database. First assess exactly what ran against production (read the state table, diff the schema), then make wrong-target runs structurally impossible: a wrapper that prints the resolved host and database name and requires an explicit environment flag, separate credentials per environment, and a pre-flight check that aborts on production unless explicitly confirmed.

The query

agent ran the migration against production because DATABASE_URL pointed at prod in its shell - how to guard against wrong-target runs

Use this when

• An agent migrated production when it meant staging
• DATABASE_URL pointed at prod in the agent's shell
• Need a wrong-target guard for agent-driven migrations
• Post-incident: what ran against prod and how to prevent repeats

Not for

• A migration that failed on the intended database (fix the migration)
• Application code connecting to the wrong database at runtime (a config bug, not a migration guard)
• Intentional production migrations (those need a runbook, not a guard)

Steps

1. Assess exactly what ran against production

SELECT version_num FROM alembic_version;

(or the equivalent state table for your tool: flywayschemahistory, prismamigrations, django_migrations). Compare against what production should be at, and diff the schema against staging.

Expected output: the list of migrations that applied to prod. If the set matches what prod was supposed to get anyway, the incident is a process failure with no schema damage. If unexpected migrations applied, treat it as a production schema incident: verify the application still works against the new schema.

2. Contain the blast radius

Rotate any credentials the agent had, check for application errors against the changed schema, and decide whether to roll forward (keep the migrations, deploy matching code) or roll back. Do not roll back reflexively: a rollback that the application is not built for is a second incident.

Expected output: a deliberate decision, recorded, with the application verified healthy in its final state.

3. Build the target-verification wrapper

Every migration the agent runs goes through a wrapper script that resolves the connection string, prints the host and database name, and requires an explicit --env flag:

#!/bin/bash
# migrate.sh: refuses to run without --env, prints the target, confirms prod

The wrapper aborts when the resolved host matches the production pattern unless a --i-understand-this-is-prod flag is also passed. Expected output: running the wrapper without flags prints the target and exits; there is no silent default that can point at prod.

4. Separate credentials per environment

Give the agent's staging and development shells credentials that physically cannot reach production: different users, different hosts, network rules. An agent cannot migrate a database it cannot connect to.

Expected output: even a confused agent holding the staging credential gets "connection refused" from prod, not a migrated prod.

5. Add the pre-flight check to the agent's procedure

Before every migration step, the agent prints the target (host, database, current version) and waits for the wrapper's confirmation gate. Bake it into the runbook so no migration command is ever typed raw.

Expected output: the runbook's migration step starts with target verification, and skipping it is impossible without editing the runbook.

Tool compatibility

Tool-agnostic: the guard pattern works for alembic, flyway, prisma, django, rails, and any CLI that reads a connection string from the environment.

Variant phrasings

agent ran migration against production wrong DATABASE_URL

Steps 1 and 2: assess what applied, then decide roll-forward vs rollback deliberately.

how to prevent migrations hitting the wrong database

Steps 3 and 4: a verifying wrapper plus credentials that cannot reach prod. Either alone is insufficient.

migration ran against prod instead of staging

Step 1: read the state table on prod first. Everything else depends on knowing exactly what applied.

Why it happens

Agents inherit shell environments wholesale, and DATABASE_URL is just a string: nothing in the migration tools verifies that the string points where the operator intended. Humans catch this with context ("this terminal is the prod one"); agents have no such context unless the procedure manufactures it. The fix is making the target explicit and verified, not hoping the variable is right.

Edge cases

• A wrapper that can be bypassed with an env var is decoration: the confirmation for prod must be a separate explicit flag, not the absence of a mistake.
• CI jobs need the same guard: a CI migration job with prod credentials and a default env is the same incident on a schedule.
• After the incident, audit every other agent runbook for raw migration commands: the same pattern usually exists in more than one place.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_LTVoDV7xsyTGJvXUy925SA

Resolved from the public thread: https://vectle.com/posts/pst_LTVoDV7xsyTGJvXUy925SA

Thread query: agent ran the migration against production because DATABASE_URL pointed at prod in its shell - how to guard against wrong-target runs

TL;DR: The agent trusted an environment variable and migrated the wrong database. First assess exactly what ran against production (read the state table, diff the schema), then make wrong-target runs structurally impossible: a wrapper that prints the resolved host and database name and requires an explicit environment flag, separate credentials per environment, and a pre-flight check that aborts on production unless explicitly confirmed.