Crates.io | sqlx-cli |
lib.rs | sqlx-cli |
version | 0.7.4 |
source | src |
created_at | 2020-05-16 03:11:43.583748 |
updated_at | 2024-03-12 05:14:22.772586 |
description | Command-line utility for SQLx, the Rust SQL toolkit. |
homepage | https://github.com/launchbadge/sqlx |
repository | https://github.com/launchbadge/sqlx |
max_upload_size | |
id | 242238 |
size | 1,005,433 |
SQLx's associated command-line utility for managing databases, migrations, and enabling "offline"
mode with sqlx::query!()
and friends.
# supports all databases supported by SQLx
$ cargo install sqlx-cli
# only for postgres
$ cargo install sqlx-cli --no-default-features --features native-tls,postgres
# use vendored OpenSSL (build from source)
$ cargo install sqlx-cli --features openssl-vendored
# use Rustls rather than OpenSSL (be sure to add the features for the databases you intend to use!)
$ cargo install sqlx-cli --no-default-features --features rustls
All commands require that a database url is provided. This can be done either with the --database-url
command line option or by setting DATABASE_URL
, either in the environment or in a .env
file
in the current working directory.
For more details, run sqlx <command> --help
.
# Postgres
DATABASE_URL=postgres://postgres@localhost/my_database
DATABASE_URL
sqlx database create
sqlx database drop
sqlx migrate add <name>
Creates a new file in migrations/<timestamp>-<name>.sql
. Add your database schema changes to
this new file.
sqlx migrate run
Compares the migration history of the running database against the migrations/
folder and runs
any scripts that are still pending.
Users can provide the directory for the migration scripts to sqlx migrate
subcommands with the --source
flag.
sqlx migrate info --source ../relative/migrations
If you would like to create reversible migrations with corresponding "up" and "down" scripts, you use the -r
flag when creating the first migration:
$ sqlx migrate add -r <name>
Creating migrations/20211001154420_<name>.up.sql
Creating migrations/20211001154420_<name>.down.sql
After that, you can run these as above:
$ sqlx migrate run
Applied migrations/20211001154420 <name> (32.517835ms)
And reverts work as well:
$ sqlx migrate revert
Applied 20211001154420/revert <name>
Note: All the subsequent migrations will be reversible as well.
$ sqlx migrate add <name1>
Creating migrations/20211001154420_<name>.up.sql
Creating migrations/20211001154420_<name>.down.sql
query!()
There are 2 steps to building with "offline mode":
cargo sqlx prepare
Note: Saving query metadata must be run as cargo sqlx
.
cargo sqlx prepare
Invoking prepare
saves query metadata to .sqlx
in the current directory.
For workspaces where several crates are using query macros, pass the --workspace
flag
to generate a single .sqlx
directory at the root of the workspace.
cargo sqlx prepare --workspace
Check this directory into version control and an active database connection will no longer be needed to build your project.
cargo sqlx prepare --check
# OR
cargo sqlx prepare --check --workspace
Exits with a nonzero exit status if the data in .sqlx
is out of date with the current
database schema or queries in the project. Intended for use in Continuous Integration.
The presence of a DATABASE_URL
environment variable will take precedence over the presence of .sqlx
, meaning SQLx will default to building against a database if it can. To make sure an accidentally-present DATABASE_URL
environment variable or .env
file does not
result in cargo build
(trying to) access the database, you can set the SQLX_OFFLINE
environment
variable to true
.
If you want to make this the default, just add it to your .env
file. cargo sqlx prepare
will
still do the right thing and connect to the database.
In order for sqlx to be able to find queries behind certain feature flags or in tests, you need to turn them
on by passing arguments to cargo
.
This is how you would turn all targets and features on.
cargo sqlx prepare -- --all-targets --all-features