{"record":{"id":"7639c4b37470f60a","repo":"golang-migrate/migrate","slug":"database-is-dirty-7639c4","errorCode":null,"errorMessage":"database is dirty","messagePattern":"database is dirty","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"database/sqlite3/sqlite3.go","lineNumber":24,"sourceCode":"\t\"fmt\"\n\t\"io\"\n\tnurl \"net/url\"\n\t\"strconv\"\n\t\"strings\"\n\t\"sync/atomic\"\n\n\t\"github.com/golang-migrate/migrate/v4\"\n\t\"github.com/golang-migrate/migrate/v4/database\"\n\t_ \"github.com/mattn/go-sqlite3\"\n)\n\nfunc init() {\n\tdatabase.Register(\"sqlite3\", &Sqlite{})\n}\n\nvar DefaultMigrationsTable = \"schema_migrations\"\nvar (\n\tErrDatabaseDirty  = fmt.Errorf(\"database is dirty\")\n\tErrNilConfig      = fmt.Errorf(\"no config\")\n\tErrNoDatabaseName = fmt.Errorf(\"no database name\")\n)\n\ntype Config struct {\n\tMigrationsTable string\n\tDatabaseName    string\n\tNoTxWrap        bool\n}\n\ntype Sqlite struct {\n\tdb       *sql.DB\n\tisLocked atomic.Bool\n\n\tconfig *Config\n}\n\nfunc WithInstance(instance *sql.DB, config *Config) (database.Driver, error) {","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/golang-migrate/migrate/blob/01a9643f1475e75bb6d6224ddeaf9d8e2434ca8a/database/sqlite3/sqlite3.go#L6-L42","documentation":"ErrDatabaseDirty is a sentinel error returned by the sqlite3 driver when the schema_migrations table indicates a previous migration run did not complete (a row marked dirty). The driver blocks further migrations to avoid operating on an inconsistently migrated schema. It is returned from WithInstance/Open during RunMigrations until the dirty state is resolved.","triggerScenarios":"Calling WithInstance or Open (then Up/Down) on a SQLite database whose migrations table has dirty=true — a previous migration was interrupted mid-run (process killed, crash, disk full, lost lock).","commonSituations":"Deploy pipeline killed mid-migration (Ctrl+C, SIGKILL, OOM, pod restart); power loss during a large ALTER TABLE; disk-full or SQLite lock timeout aborting a migration halfway.","solutions":["Inspect the schema to determine whether the last partial migration actually applied.","If it applied, clean the flag: sqlite3 app.db \"UPDATE schema_migrations SET dirty=0 WHERE version=<version>;\" (or use migrate force <version>).","If it did not apply, manually undo partial changes and delete the dirty row, then re-run migrations.","Restore from a pre-migration backup and re-run migrations cleanly.","Verify schema state before modifying the migrations table; never blind-force a version."],"exampleFix":"// before\n// migrate.Up fails: ErrDatabaseDirty (version 3|1)\n// after (CLI)\n// migrate -path ./migrations -database sqlite3://app.db force 3\n// sqlite3 app.db \"UPDATE schema_migrations SET dirty=0 WHERE version=3;\"","handlingStrategy":"type-guard","validationCode":"// before migrating\nrows, err := db.Query(\"SELECT version, dirty FROM schema_migrations\")\nif err == nil {\n    for rows.Next() {\n        var v int; var d bool\n        rows.Scan(&v, &d)\n        if d { return fmt.Errorf(\"db dirty at version %d; resolve before migrating\", v) }\n    }\n}","typeGuard":"func isDirtyErr(err error) bool {\n    return errors.Is(err, sqlite3.ErrDatabaseDirty)\n}","tryCatchPattern":"if err := m.Up(); err != nil {\n    if errors.Is(err, sqlite3.ErrDatabaseDirty) {\n        // halt pipeline; use `migrate force <v>` only after verifying schema\n        return fmt.Errorf(\"migration halted: dirty database: %w\", err)\n    }\n    return err\n}","preventionTips":["Never SIGKILL a running migrator; use graceful shutdown with migration-aware timeouts.","Back up the database file before each migration run.","Run migrations in a dedicated deploy step, not alongside app boot in crash-looping containers.","Monitor schema_migrations for dirty=true."],"tags":["sqlite3","migration","dirty-database","go"],"backgroundTag":"database-migration-dirty-state","analyzedSha":"01a9643f1475e75bb6d6224ddeaf9d8e2434ca8a","analyzedAt":"2026-09-02T19:38:29.671Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}