{"record":{"id":"2a486a962c4bd8e3","repo":"golang-migrate/migrate","slug":"database-is-dirty-2a486a","errorCode":null,"errorMessage":"database is dirty","messagePattern":"database is dirty","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"database/sqlite/sqlite.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_ \"modernc.org/sqlite\"\n)\n\nfunc init() {\n\tdatabase.Register(\"sqlite\", &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/sqlite/sqlite.go#L6-L42","documentation":"ErrDatabaseDirty is a sentinel error returned by the sqlite driver when the schema_migrations table indicates a previous migration run did not complete (a row is marked dirty). The driver refuses further migrations to protect against an inconsistently migrated schema. It is returned from WithInstance/Open during RunMigrations until the dirty state is cleared.","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) leaving the schema in an unknown state.","commonSituations":"Killing a deploy mid-migration (Ctrl+C, SIGKILL, OOM, container restart); power loss during a large ALTER TABLE; SQLite file lock timeout or disk-full 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>;\"","If it did not apply, manually undo the 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 touching the migrations table; never blind-force the version."],"exampleFix":"// before\n// migrate.Up fails: ErrDatabaseDirty (version 7|1)\n// after (sqlite3 shell)\n// sqlite3 app.db \"SELECT * FROM schema_migrations;\"   -- 7|1\n// sqlite3 app.db \"UPDATE schema_migrations SET dirty=0 WHERE version=7;\"","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, sqlite.ErrDatabaseDirty)\n}","tryCatchPattern":"if err := m.Up(); err != nil {\n    if errors.Is(err, sqlite.ErrDatabaseDirty) {\n        // halt pipeline; inspect schema and clear dirty flag only after verification\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 SQLite 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":["sqlite","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"}