Unknown Migration in Database
You fix an unknown migration in database by matching your local files with the tracking table. This error happens when the database records a schema change that your local folder lacks. Teams often see this issue when multiple developers push schema updates from separate code branches. Broad database roles make this worse by letting people run ad-hoc changes outside the normal pipeline. Those manual edits or deleted files leave the tracking table out of sync with your code. Why an unknown migr
Just-in-Time Access + Database Access Proxy: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You fix an unknown migration in database by matching your local files with the tracking table. This error happens when the database records a schema change that your local folder lacks. Teams often see this issue when multiple developers push schema updates from separate code branches. Broad database roles make this worse by letting people run ad-hoc changes outside the normal pipeline. Those manual edits or deleted files leave the tracking table out of sync with your code.
Why an unknown migration in database happens
Schema migration tools track changes by saving a history table inside your target database. Each time a deployment runs, the tool reads your local folder of migration scripts. It compares the file names and checksums against the rows in that history table. When the database lists a version ID that is missing from your folder, the tool stops. It raises an error to protect your data from an out-of-order schema update.
This mismatch usually starts during a branch switch or a failed release rollback. A developer might run a new migration on a shared staging database from a feature branch. When the main branch runs its pipeline, the main code lacks that feature branch file. The migration tool sees the extra row in the database table and halts the build. Deleting old migration files from source control without rolling them back causes the exact same failure.
How to resolve schema history mismatches
Start by checking the migration history table in your database to find the extra version ID. Search your git commit history and open branches to locate the missing script file. If the change belongs in the release, merge that missing file into your current branch. Once the file is back in the folder, the migration tool can verify the sequence.
Sometimes the extra database row came from a test branch that your team dropped. If you are on a local or staging server, revert the schema changes by hand. Then delete the orphaned version row from the tracking table so the state matches your code. In production, you can also mark the missing version as ignored if your tool supports repair actions. Always back up the database before you edit the tracking table or drop columns.
Just-in-Time Access + Database Access Proxy: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Where native database roles fall short
Standard database setups use static users and broad role grants to control schema updates. A shared admin account often runs both the migration pipeline and manual debugging sessions. Native roles decide who can log in and alter tables at the session level. They do not inspect what individual SQL statements or commands do while in flight.
When engineers use that shared role to fix a bug, they can alter the tracking table. They might also read sensitive customer tables while checking if a migration worked. Native permissions cannot require peer approval for a single table drop or history delete. They also fail to mask fields like emails, phone numbers, or card numbers in query results.
Check database and API queries on the wire
Identity tools, roles, and network rules decide who opens a session. Setup alone cannot check what each query does or mask sensitive values in a response once a session starts. When workflows touch Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, or internal HTTP APIs, hoop.dev runs beside those services as an open-source proxy, a sidecar for your Postgres or API. It inspects requests coming in and results going back on the wire.
Your login details and client tools stay as they are while hoop.dev guardrails refuse bad deletes or drops before they run. On responses, hoop.dev data masking rewrites matched sensitive values in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and writes every query and decision to an audit trail that generates evidence for HIPAA, GDPR, and PCI DSS. See the source on GitHub.
Frequently asked questions
Can I delete the extra row from the migration tracking table?
You can delete the row if you also undo the schema changes that migration made. If you only delete the tracking row, the tables and columns stay in the database. Future migrations may fail later when they try to create objects that already exist.
Why did this error appear after switching git branches?
Your previous git branch had a newer migration file that you already ran against the database. Your current branch does not have that file in its local migration folder yet. The database state is now ahead of the code on your current branch.
How do we stop unknown migration errors in shared staging databases?
Restrict write permissions on the schema and history table to your automated deployment pipeline. Give developers separate local database instances to test branch changes before merging to main. Require peer review before anyone runs manual repair queries against shared database servers.