📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,87 @@
|
||||
# CI and Team Policy
|
||||
|
||||
Use this reference when the user wants to prevent Drizzle migration conflicts in pull requests,
|
||||
protected branches, or GitHub merge queues.
|
||||
|
||||
## Recommended layers
|
||||
|
||||
1. **Local developer habit**
|
||||
- Pull or merge the parent branch before generating a migration.
|
||||
- Generate migrations once schema source conflicts are resolved.
|
||||
- Run `drizzle-kit check` only after confirming its config/env do not target production.
|
||||
2. **Pull request check**
|
||||
- Run the project's normal static checks.
|
||||
- Run `drizzle-kit check` or the package script that wraps it with explicit non-production config.
|
||||
- Run the read-only helper script to catch legacy journal/snapshot mismatches.
|
||||
3. **Merge queue check**
|
||||
- If GitHub merge queue is enabled, run the same check on `merge_group` events.
|
||||
- Do not assume a successful PR check means the queued merge result is still conflict-free.
|
||||
|
||||
## GitHub Actions skeleton
|
||||
|
||||
Adapt package manager, config path, migration directory, and script location to the target
|
||||
repository. The helper script must be vendored or copied into the repository before CI can run it.
|
||||
Never point CI migration checks at production credentials.
|
||||
|
||||
```yaml
|
||||
name: drizzle-migration-check
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
merge_group:
|
||||
|
||||
jobs:
|
||||
drizzle-migration-check:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 20
|
||||
cache: pnpm
|
||||
- uses: pnpm/action-setup@v4
|
||||
with:
|
||||
version: 9
|
||||
- run: pnpm install --frozen-lockfile
|
||||
# Run only with a non-production or disposable DATABASE_URL if the config requires one.
|
||||
- run: pnpm exec drizzle-kit check --config drizzle.config.ts
|
||||
# Example assumes the helper was copied to scripts/check_drizzle_migrations.py.
|
||||
- run: python3 scripts/check_drizzle_migrations.py --root . --config drizzle.config.ts --migrations-dir drizzle
|
||||
```
|
||||
|
||||
If the repository does not vendor this skill, copy the helper script into the repo or run an
|
||||
equivalent read-only check from the CI tooling repository. In multi-config repositories, pass the
|
||||
same config and matching migration directory to both Drizzle Kit and the helper script.
|
||||
|
||||
The helper script exits with: `0` when all checked directories are clean, `1` when any error or
|
||||
warning issue is found, and `2` when no migration directory was discovered at all. A CI step that
|
||||
runs the script should fail the job on a non-zero exit, but treat exit `2` as "nothing to check"
|
||||
only if the repo is expected to have no Drizzle migrations; otherwise exit `2` usually means
|
||||
detection missed the migration directory and the config should be passed explicitly.
|
||||
|
||||
## What merge queue does and does not solve
|
||||
|
||||
Merge queue can serialize the final merge order and test a temporary merge result. It does not
|
||||
rewrite Drizzle migrations, re-run `drizzle-kit generate`, or choose which branch's snapshots are
|
||||
correct. The check should fail when generated migration history is inconsistent, then the developer
|
||||
updates the branch and regenerates migrations.
|
||||
|
||||
## Policy recommendations
|
||||
|
||||
- Require one migration-generation point per PR after schema conflicts are resolved.
|
||||
- Treat migration artifacts as generated but reviewable files: do not silently rewrite them in CI.
|
||||
- Require `drizzle-kit check` or an equivalent conflict check before merge.
|
||||
- In legacy projects, reject duplicate migration numbers and journal/snapshot drift.
|
||||
- In folder-based projects, reject incomplete migration directories and failed commutativity checks.
|
||||
- Keep production migration execution separate from PR validation.
|
||||
|
||||
## When CI should fail
|
||||
|
||||
Fail the job when any of these are true:
|
||||
|
||||
- `_journal.json` contains duplicate `idx` or `tag` values.
|
||||
- A journal entry references a missing SQL file or snapshot.
|
||||
- Root SQL or snapshot files exist but are not referenced by the journal in a legacy output.
|
||||
- Migration files contain Git conflict markers.
|
||||
- A folder-based migration directory is missing `migration.sql` or `snapshot.json`.
|
||||
- `drizzle-kit check` reports a non-commutative migration conflict.
|
||||
+163
@@ -0,0 +1,163 @@
|
||||
# Conflict Resolution Playbook
|
||||
|
||||
Use this playbook after collecting repo facts. The goal is to preserve schema intent while replacing
|
||||
stale generated migration artifacts with a migration generated from the merged schema.
|
||||
|
||||
## Decision tree
|
||||
|
||||
1. Is the repository currently in a merge or rebase?
|
||||
- Check `git status --short` and `git ls-files -u`.
|
||||
- If yes, identify whether the user is merging the parent branch into a feature branch, rebasing a
|
||||
feature branch, or merging a feature branch into the parent branch.
|
||||
2. Which migration structure is present?
|
||||
- Legacy: `meta/_journal.json`, `meta/*_snapshot.json`, root SQL files.
|
||||
- Folder-based: migration directories with `migration.sql` and `snapshot.json`.
|
||||
- Mixed or unknown: stop and ask for the intended migration output path.
|
||||
- Transitioning (legacy artifacts plus a partial move to folder-based): do not repair until the
|
||||
user confirms the target structure. Treat the legacy artifacts and the folder-based artifacts
|
||||
as one logical history only after the intended end state is clear; otherwise a repair could
|
||||
discard the wrong side.
|
||||
3. Are schema source files already resolved?
|
||||
- If not, resolve those first or tell the user the migration cannot be regenerated safely yet.
|
||||
4. Is the user asking for diagnosis or repair?
|
||||
- Diagnosis stays read-only.
|
||||
- Repair can include file changes only after the exact generated files to discard are understood.
|
||||
|
||||
## Read-only inspection commands
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
git ls-files -u
|
||||
rg --files -g 'drizzle.config.*' -g 'package.json'
|
||||
rg -n "drizzle-kit|drizzle-orm|db:generate|db:check|migrate" package.json pnpm-lock.yaml yarn.lock package-lock.json 2>/dev/null
|
||||
python3 <skill-dir>/scripts/check_drizzle_migrations.py --root .
|
||||
```
|
||||
|
||||
If `rg` is not available, use `find` and `grep` equivalents. Resolve `<skill-dir>` to the installed
|
||||
skill directory before running the helper. Check in order and use the first match that contains
|
||||
`scripts/check_drizzle_migrations.py`: the target repo's vendored
|
||||
`skills/drizzle-migration-conflict`, then `~/.claude/skills/drizzle-migration-conflict`, then any
|
||||
user-reported install location. If none resolve, fall back to the `git`/`rg` inspection commands
|
||||
above and tell the user the helper was not found.
|
||||
|
||||
## Legacy structure repair
|
||||
|
||||
Legacy Drizzle output usually looks like this:
|
||||
|
||||
```text
|
||||
drizzle/
|
||||
0000_initial.sql
|
||||
0001_add_user.sql
|
||||
meta/
|
||||
_journal.json
|
||||
0000_snapshot.json
|
||||
0001_snapshot.json
|
||||
```
|
||||
|
||||
Safe flow for a feature branch updated from the parent branch:
|
||||
|
||||
1. Resolve schema source conflicts first.
|
||||
2. Keep the parent branch's migration history as the baseline.
|
||||
3. Discard generated migration files created on the feature branch after it diverged from the parent
|
||||
branch.
|
||||
4. Re-run the project-approved `drizzle-kit generate` script from `package.json`.
|
||||
5. Validate the regenerated history.
|
||||
|
||||
Do not hand-edit `_journal.json` or snapshot JSON unless the user explicitly asks for an emergency
|
||||
manual repair and accepts the risk. The next generated migration depends on those snapshots.
|
||||
|
||||
### Ours/theirs warning
|
||||
|
||||
`ours` and `theirs` change meaning with merge direction:
|
||||
|
||||
| Situation | `ours` usually means | `theirs` usually means | Safe guidance |
|
||||
| --- | --- | --- | --- |
|
||||
| On feature branch, merging parent branch into it | current feature branch | parent branch being merged in | Parent branch is often `theirs`, but verify before checkout. |
|
||||
| On parent branch, merging feature branch into it | current parent branch | feature branch | Parent branch is often `ours`, but verify before checkout. |
|
||||
| Rebase | meaning can be unintuitive | meaning can be unintuitive | Avoid shorthand; use explicit branch/path restore if possible. |
|
||||
|
||||
When in doubt, ask which branch should be the migration-history source of truth. Do not guess.
|
||||
|
||||
## Folder-based structure repair
|
||||
|
||||
Folder-based Drizzle output usually looks like this:
|
||||
|
||||
```text
|
||||
drizzle/
|
||||
20260618120000_add_user/
|
||||
migration.sql
|
||||
snapshot.json
|
||||
```
|
||||
|
||||
Safe flow:
|
||||
|
||||
1. Inspect the Drizzle config and env first, then run `drizzle-kit check` or the project script
|
||||
wrapping it only with a non-production target.
|
||||
2. If it reports a non-commutative migration conflict, identify the conflicting migration and any
|
||||
later migrations based on it.
|
||||
3. Remove or regenerate only the generated migration artifacts that are downstream of the conflict,
|
||||
after user confirmation.
|
||||
4. Re-run `drizzle-kit generate` from the merged schema.
|
||||
5. Re-run the helper script, and re-run `drizzle-kit check` only after confirming the config/env
|
||||
target is still non-production.
|
||||
|
||||
Use `--ignore-conflicts` only for a known false positive after reviewing why the migrations commute
|
||||
or why the check is wrong. Include that decision in the report.
|
||||
|
||||
## Validation after regeneration
|
||||
|
||||
Run validation in tiers so the agent does not accidentally touch a live database or run arbitrary
|
||||
project scripts.
|
||||
|
||||
### Database-free checks
|
||||
|
||||
```bash
|
||||
python3 <skill-dir>/scripts/check_drizzle_migrations.py --root . --migrations-dir <migration-dir>
|
||||
```
|
||||
|
||||
### Loads project config or environment
|
||||
|
||||
Run `drizzle-kit check` only after inspecting `drizzle.config.*`, package scripts, and relevant env
|
||||
variables. Confirm that any database URL or credentials point to a non-production or disposable
|
||||
target before executing it. Work through this checklist before running the command:
|
||||
|
||||
1. Read `drizzle.config.*` and note any `url`, `dbCredentials`, `credentials`, or connection fields.
|
||||
Determine whether they are literal, read from `process.env`, or loaded via `dotenv`.
|
||||
2. Identify which env vars feed those fields (common names: `DATABASE_URL`, `DB_URL`,
|
||||
`POSTGRES_URL`, `DRIZZLE_DATABASE_URL`). Check `.env`, `.env.local`, and the package script's
|
||||
environment for their values without echoing secrets.
|
||||
3. If a value points at a production host (named `prod`/`production`, a managed cluster endpoint,
|
||||
or a host the user identifies as live), stop and ask for a disposable target. Do not run the check.
|
||||
4. If `drizzle-kit check` needs a real connection for the configured dialect, prefer overriding the
|
||||
URL inline with a disposable/local database, or use a config that disables connection (some
|
||||
dialects allow a schema-only check). If neither is possible, fall back to the database-free
|
||||
helper script and report that `drizzle-kit check` could not be run safely.
|
||||
5. Only after the target is confirmed non-production, run the project-approved check command.
|
||||
|
||||
```bash
|
||||
# Project script names vary; inspect package.json first.
|
||||
# Override with a disposable DATABASE_URL only if the config requires a connection.
|
||||
DATABASE_URL=postgres://localhost/disposable pnpm exec drizzle-kit check --config <drizzle-config>
|
||||
```
|
||||
|
||||
### Project tests
|
||||
|
||||
Run typechecks or tests only after inspecting the script definitions. Tests may run migrations,
|
||||
connect to databases, mutate fixtures, or start services.
|
||||
|
||||
```bash
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
```
|
||||
|
||||
Avoid live database commands unless the user names a disposable database or explicitly requests a
|
||||
migration run.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- Running `drizzle-kit push` to bypass migration history in production.
|
||||
- Keeping both sides' generated migrations and manually renumbering files without regenerating from
|
||||
the merged schema.
|
||||
- Resolving `_journal.json` by accepting both sides without verifying SQL and snapshot pairs.
|
||||
- Using `git checkout --theirs drizzle/` without understanding merge direction.
|
||||
- Ignoring `drizzle-kit check` with `--ignore-conflicts` as the default team workflow.
|
||||
+69
@@ -0,0 +1,69 @@
|
||||
# Report Template
|
||||
|
||||
Use this template for diagnosis and repair recommendations. Keep reports short and evidence-based.
|
||||
|
||||
## Conclusion values
|
||||
|
||||
- `NO_CONFLICT_FOUND` - No migration conflict or structural inconsistency was found from available
|
||||
evidence.
|
||||
- `SAFE_TO_REGENERATE` - The conflict is understood, schema source is resolved, and the recommended
|
||||
next step is to discard generated artifacts and regenerate migrations.
|
||||
- `NEEDS_USER_CONFIRMATION` - A repair path exists, but a destructive step or branch-side decision
|
||||
requires confirmation.
|
||||
- `BLOCKED_BY_AMBIGUITY` - The migration structure, source-of-truth branch, schema state, or
|
||||
migration directory cannot be determined safely.
|
||||
|
||||
## Template
|
||||
|
||||
````markdown
|
||||
# Drizzle Migration Conflict Report
|
||||
|
||||
Conclusion: <NO_CONFLICT_FOUND | SAFE_TO_REGENERATE | NEEDS_USER_CONFIRMATION | BLOCKED_BY_AMBIGUITY>
|
||||
Mode: <diagnose | repair | ci-hardening | explain>
|
||||
|
||||
## Detected Structure
|
||||
- Migration directory: `<path>`
|
||||
- Structure: <legacy | folder-based | mixed | unknown>
|
||||
- Drizzle Kit version: <version or unable to verify>
|
||||
- Git state: <clean | dirty | active merge | active rebase | unable to verify>
|
||||
|
||||
## Conflict State
|
||||
- <confirmed conflict or inconsistency with file paths>
|
||||
- <journal/snapshot/SQL mismatch, non-commutative check, or conflict marker evidence>
|
||||
|
||||
## Recommended Path
|
||||
- <safe next step>
|
||||
- <why this path preserves schema intent and migration history>
|
||||
|
||||
## Commands
|
||||
```bash
|
||||
# Read-only commands first.
|
||||
<commands>
|
||||
|
||||
# Destructive commands only if confirmed by the user.
|
||||
<commands requiring confirmation>
|
||||
```
|
||||
|
||||
## Files At Risk
|
||||
- `<path>` - <why it may be discarded or regenerated>
|
||||
|
||||
## Validation
|
||||
- <drizzle-kit check or project script>
|
||||
- <helper script command>
|
||||
- <typecheck/test command if relevant>
|
||||
|
||||
## Unable To Verify
|
||||
- <missing version, unavailable branch, unknown migration path, or external docs not refreshed>
|
||||
````
|
||||
|
||||
## Reporting rules
|
||||
|
||||
- Put destructive commands in a clearly labeled block.
|
||||
- Do not output `--ours` or `--theirs` commands unless the merge/rebase direction, source-of-truth
|
||||
branch, and exact file paths are confirmed. Otherwise use `BLOCKED_BY_AMBIGUITY`.
|
||||
- If the project has multiple Drizzle configs, report each output independently.
|
||||
- If no conflict is found but the worktree is dirty, state that uncommitted files were not repaired.
|
||||
- Do not include clean checklist categories that are irrelevant to the user's conflict.
|
||||
- Redact secrets. Never include database URLs, passwords, tokens, or connection strings in the
|
||||
report. When a config or env value matters, describe only whether it points at a production-like
|
||||
target and write the value as `<redacted>`.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Source References
|
||||
|
||||
Last verified: 2026-06-18.
|
||||
|
||||
Use this file when an answer depends on upstream Drizzle behavior, community scripts, or CI platform
|
||||
behavior. Drizzle Kit migration internals can change, so prefer current official docs and the
|
||||
project's installed `drizzle-kit` version over memory when resolving a real conflict.
|
||||
|
||||
## Official and semi-official Drizzle sources
|
||||
|
||||
| Source | Link | Use | Trust level |
|
||||
| --- | --- | --- | --- |
|
||||
| Discussion 1104 | https://github.com/drizzle-team/drizzle-orm/discussions/1104 | Original team-collaboration conflict thread for legacy `_journal.json` and snapshot conflicts. Useful for understanding why parallel generated migrations diverge. | Drizzle GitHub discussion; useful but may include outdated comments. |
|
||||
| Discussion 2832 | https://github.com/drizzle-team/drizzle-orm/discussions/2832 | Migration folder structure redesign and reasoning. Use to understand why the old flat structure is git-hostile. | Drizzle GitHub discussion; design context may predate current release behavior. |
|
||||
| Discussion 5005 | https://github.com/drizzle-team/drizzle-orm/discussions/5005 | Commutative migration checking, `drizzle-kit check`, and conflict behavior in newer Drizzle Kit versions. | High value for current direction; verify against installed version. |
|
||||
| Discussion 5581 | https://github.com/drizzle-team/drizzle-orm/discussions/5581 | Practical parent-branch-as-source-of-truth repair workflow. | Community workflow; good playbook, still verify against repo state. |
|
||||
| Generate docs | https://orm.drizzle.team/docs/drizzle-kit-generate | How Drizzle Kit derives migrations from schema and snapshots. | Official docs. |
|
||||
| Check docs | https://orm.drizzle.team/docs/drizzle-kit-check | Migration consistency checking for team workflows. | Official docs. |
|
||||
| Migration overview | https://orm.drizzle.team/docs/migrations | General migration concepts and current official migration overview. | Official docs. |
|
||||
|
||||
## Community scripts
|
||||
|
||||
These scripts are reference material only. Do not copy their destructive behavior into a generic
|
||||
agent workflow without dry-run mode and explicit user confirmation.
|
||||
|
||||
| Source | Link | Use | Caveat |
|
||||
| --- | --- | --- | --- |
|
||||
| Legacy undo script | https://gist.github.com/anthonyjoeseph/102c0e3ea8496fe111029a8b8a95cc3a | Shows a merge-time undo workflow for legacy Drizzle migration artifacts. | Assumes legacy structure and uses git/file operations that can discard local generated files. |
|
||||
| Legacy repair script | https://gist.github.com/anthonyjoeseph/6b99beb34d494acd1dfc83a192ed9388 | Detects duplicate legacy migration numbers and can repair by removing orphaned generated files. | `FORCE_FIX` is destructive; adapt only the read-only checks unless the user confirms. |
|
||||
| Earlier repair variant | https://gist.github.com/gburtini/7e34842c567dd80ee834de74e7b79edd | Useful for historical context and comparing conflict-detection logic. | Earlier variant had caveats fixed by later forks; do not rely on it alone. |
|
||||
|
||||
## CI and merge queue sources
|
||||
|
||||
| Source | Link | Use | Caveat |
|
||||
| --- | --- | --- | --- |
|
||||
| GitHub merge queue docs | https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue | Explains merge queue behavior and why required checks must also run for `merge_group` events. | Merge queue serializes merging; it does not regenerate Drizzle migrations by itself. |
|
||||
|
||||
## Version-sensitive guidance
|
||||
|
||||
Before giving high-confidence advice for a live repository:
|
||||
|
||||
1. Check the local `drizzle-kit` version from `package.json` and the lockfile first.
|
||||
2. Check whether the migration output uses the legacy flat structure or the folder-based structure.
|
||||
3. If command execution is acceptable and dependencies are already installed, use a local-only
|
||||
package-manager command. Prefer `pnpm exec drizzle-kit --version`,
|
||||
`yarn exec drizzle-kit --version`, or `npm exec --no-install drizzle-kit -- --version`. Do not
|
||||
use plain `npx` for version probing because it can download or resolve a different package.
|
||||
4. If online browsing is available and the user asks for current guidance, re-open the official docs
|
||||
and the discussion most relevant to the installed version.
|
||||
5. If a local result conflicts with these sources, trust the local repository state and report the
|
||||
mismatch explicitly.
|
||||
Reference in New Issue
Block a user