Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/launchbadge/sqlx/llms.txt

Use this file to discover all available pages before exploring further.

The sqlx migrate command group (alias sqlx mig) manages the versioned SQL files that keep your database schema in sync with your application code. You can create new migration files, apply pending ones, revert the most recently applied migration, and check the current status of your database at a glance.

​
sqlx migrate add

Creates a new migration file in the migrations/ directory (created automatically if it does not exist). SQLx assigns a timestamp-based version prefix in the format YYYYMMDDHHmmss unless sequential versioning is detected. 
sqlx migrate add <name>
For example: 
sqlx migrate add create_users
# Creates: migrations/20211001154420_create_users.sql

​
Reversible migrations

Pass -r (or --reversible) to create a matched pair of .up.sql and .down.sql files. The up file is applied when you run sqlx migrate run; the down file is used when you run sqlx migrate revert. 
sqlx migrate add -r <name>

Creating migrations/20211001154420_create_users.up.sql
Creating migrations/20211001154420_create_users.down.sql
Once you create a reversible migration, all subsequent migrations added in that directory are also created as reversible pairs. You can override this with --simple to force a plain .sql file.

​
Versioning options

FlagDescription
-r / --reversibleCreate an .up.sql / .down.sql pair
--simpleCreate a plain .sql file (non-reversible)
-t / --timestampForce timestamp versioning (YYYYMMDDHHmmss)
-s / --sequentialForce sequential versioning (0001, 0002, …)
SQLx infers the versioning style from your existing migrations: if the last two version numbers differ by exactly 1, sequential versioning is assumed; otherwise timestamps are used.

​
sqlx migrate run

Compares the migration history recorded in the _sqlx_migrations table against the files on disk and applies every pending migration in ascending version order. 
sqlx migrate run

​
Dry run

Use --dry-run to list the migrations that would be applied without actually executing them: 
sqlx migrate run --dry-run

​
Target version

Apply migrations only up to a specific version: 
sqlx migrate run --target-version 20211001154420

​
sqlx migrate revert

Reverts the most recently applied migration by running its .down.sql file. Only reversible migrations can be reverted. Attempting to revert a simple migration returns an error. 
sqlx migrate revert
Example output: 
Applied 20211001154420/revert create_users (14.832ms)
Use --target-version to revert all migrations down to a specific version. Set it to 0 to revert everything: 
sqlx migrate revert --target-version 0
Reverting a migration is destructive. Any data discarded by the up-migration (dropped columns, deleted rows, removed tables) is not restored. Always back up your database before reverting in production.

​
sqlx migrate info

Shows the status of every migration — whether it is installed (applied) or pending. Also flags migrations whose on-disk checksum does not match the checksum recorded when they were applied. 
sqlx migrate info
Example output: 
20211001154420/installed create_users
20211002090000/installed add_email_index
20211015143000/pending   create_posts

​
sqlx migrate build-script

Generates a build.rs that tells Cargo to recompile your project whenever a new migration file is added. Run this once from your Cargo project root: 
sqlx migrate build-script
This creates a build.rs containing: 
fn main() {
    println!("cargo:rerun-if-changed=migrations");
}
Commit the generated file to version control.

​
Common flags

All sqlx migrate subcommands accept:
FlagShortDescription
--source <DIR>Path to the migrations directory (default: migrations/)
--database-url <URL>-DOverride DATABASE_URL for this invocation
--connect-timeout <SECONDS>Maximum seconds to wait for a connection (default: 10)
--no-dotenvDo not load .env files automatically
--config <PATH>Path to sqlx.toml
The run and revert subcommands also accept:
FlagDescription
--dry-runList migrations without applying them
--ignore-missingIgnore applied migrations that are no longer present on disk
--target-version <VERSION>Apply or revert only up to this version

​
Custom migrations directory

Pass --source to use a directory other than migrations/: 
sqlx migrate run --source db/migrations
sqlx migrate info --source ../relative/migrations
You can also set a default source directory in sqlx.toml so you do not have to pass --source on every invocation.

Build docs developers (and LLMs) love

Get started for freeTalk to us