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.

sqlx.toml is an optional configuration file that lives in your crate root alongside Cargo.toml. It lets you control how the query! macro family maps SQL types to Rust types, override the migration table name, customize the migrations directory, and more. Configuration in sqlx.toml applies only to the crate that contains the file — it is not inherited by workspace members.
The sqlx-toml feature flag must be enabled to parse this file. If SQLx finds a sqlx.toml but the feature is disabled, it will emit a compile error.
[dependencies]
sqlx = { version = "0.9", features = ["sqlx-toml", ...] }

​
File location

Place sqlx.toml next to Cargo.toml in your crate root. The macros locate it using the CARGO_MANIFEST_DIR environment variable that Cargo sets at compile time. sqlx-cli reads the same file from the current working directory when running migrations.

​
[common]

Shared settings used by both the macros and sqlx-cli.
KeyTypeDefaultDescription
database-url-varstring"DATABASE_URL"The environment variable used to find the database URL.
[common]
database-url-var = "MY_APP_DATABASE_URL"

​
[macros]

Configuration for the query!() family of macros. All settings here are applied at compile time only.

​
[macros.preferred-crates]

When two optional type-integration features are both enabled by Cargo’s feature unification (for example, a dependency activates time while your crate uses chrono), SQLx would otherwise pick one arbitrarily. Use preferred-crates to resolve the ambiguity globally.
KeyValuesDefaultDescription
date-time"chrono", "time""inferred"Which crate to use for DATE, TIME, DATETIME, and TIMESTAMP columns.
numeric"bigdecimal", "rust_decimal""inferred"Which crate to use for NUMERIC / DECIMAL columns.
When set to "inferred", time takes precedence over chrono, and rust_decimal takes precedence over bigdecimal.

​
[macros.type-overrides]

Map SQL type names to specific Rust types for all queries in the crate. Keys are SQL type names (case-sensitive, quoted for safety); values are fully-qualified Rust type paths. 
[macros.type-overrides]
# Override the built-in UUID mapping
'UUID' = "crate::types::MyUuid"

# Map a custom Postgres enum to a Rust enum
'status' = "crate::models::Status"

# Schema-qualified type
'my_schema.my_type' = "crate::types::MyType"
Type overrides affect only the inner Rust type. They do not change whether query!() wraps a column in Option<_> — nullability is still inferred from the database schema.

​
[macros.table-overrides]

Override type mappings on a per-table, per-column basis. Useful when the same SQL type name maps to different Rust types in different tables. 
[macros.table-overrides.'users']
# Map column `role` in the `users` table to a Rust enum
'role' = "crate::models::UserRole"

# Schema-qualified table
[macros.table-overrides.'public.orders']
'status' = "crate::models::OrderStatus"

​
[migrate]

Configuration for migrations run via sqlx::migrate!() or sqlx-cli.
Many migration options are potentially destructive if changed after a production database is already set up. Read the documentation for each option carefully before making changes to an existing deployment.
KeyTypeDefaultDescription
table-namestring"_sqlx_migrations"The table used to track applied migrations. May be schema-qualified.
migrations-dirstring"migrations"Directory containing migration files, relative to the crate root (for sqlx::migrate!()) or current directory (for sqlx-cli).
ignored-charsarray of strings[]Characters to strip before hashing migration files (e.g. ["\r"] to normalize line endings).

​
[migrate.defaults]

Default settings used by sqlx migrate create.
KeyValuesDefaultDescription
migration-type"simple", "reversible""inferred"Whether new migrations are simple (up-only) or reversible (up + down). "inferred" matches the last existing migration.
migration-versioning"timestamp", "sequential""inferred"Versioning scheme for new migration filenames. "inferred" matches the last existing migration.

​
Full example

# sqlx.toml

[common]
# Use a custom env var instead of DATABASE_URL
database-url-var = "APP_DATABASE_URL"

[macros.preferred-crates]
# Force chrono even if `time` is pulled in by a dependency
date-time = "chrono"
# Force bigdecimal even if `rust_decimal` is pulled in
numeric = "bigdecimal"

[macros.type-overrides]
# Map all UUID columns to a custom newtype
'UUID' = "crate::types::UserId"

[macros.table-overrides.'users']
# Map the `role` column to an application enum
'role' = "crate::models::Role"

[migrate]
# Use a non-default migrations table (useful for multi-tenant setups)
table-name = "app._sqlx_migrations"
# Store migrations in a non-default directory
migrations-dir = "db/migrations"
# Ignore carriage returns when hashing (normalizes Windows line endings)
ignored-chars = ["\r"]

[migrate.defaults]
migration-type = "reversible"
migration-versioning = "sequential"
Configuration in sqlx.toml is only read at compile time by the query! macros and at runtime by sqlx-cli. A manually constructed Migrator (i.e., sqlx::migrate::Migrator::new(...)) does not read sqlx.toml. Use sqlx::migrate!() to get full sqlx.toml support.

Build docs developers (and LLMs) love

Get started for freeTalk to us