mirror of
https://github.com/launchbadge/sqlx.git
synced 2025-12-29 21:00:54 +00:00
84 lines
2.1 KiB
Markdown
84 lines
2.1 KiB
Markdown
# SQLx CLI
|
|
|
|
SQLx's associated command-line utility for managing databases, migrations, and enabling "offline"
|
|
mode with `sqlx::query!()` and friends.
|
|
|
|
### Install
|
|
|
|
#### With Rust toolchain
|
|
|
|
```bash
|
|
# supports all databases supported by SQLx
|
|
$ cargo install sqlx-cli
|
|
|
|
# only for postgres
|
|
$ cargo install sqlx-cli --no-default-features --features postgres
|
|
```
|
|
|
|
### Usage
|
|
|
|
All commands require `DATABASE_URL` to be set, either in the environment or in a `.env` file
|
|
in the current working directory.
|
|
|
|
`database` and `migrate` subcommands support only Postgres; MySQL and SQLite are TODO.
|
|
|
|
For more details, run `sqlx <command> --help`.
|
|
|
|
```dotenv
|
|
# Postgres
|
|
DATABASE_URL=postgres://postgres@localhost/my_database
|
|
```
|
|
|
|
#### Create/drop the database at `DATABASE_URL`
|
|
|
|
```bash
|
|
sqlx database create
|
|
sqlx database drop
|
|
```
|
|
|
|
#### Create and run migrations
|
|
|
|
```bash
|
|
$ sqlx migrate add <name>
|
|
```
|
|
Creates a new file in `migrations/<timestamp>-<name>.sql`. Add your database schema changes to
|
|
this new file.
|
|
|
|
---
|
|
```bash
|
|
$ sqlx migration run
|
|
```
|
|
Compares the migration history of the running database against the `migrations/` folder and runs
|
|
any scripts that are still pending.
|
|
|
|
#### Enable building in "offline" mode with `query!()`
|
|
|
|
Note: must be run as `cargo sqlx`.
|
|
|
|
```bash
|
|
cargo sqlx prepare
|
|
```
|
|
Saves query data to `sqlx-data.json` in the current directory; check this file into version control
|
|
and an active database connection will no longer be needed to build your project.
|
|
|
|
Has no effect unless the `offline` feature of `sqlx` is enabled in your project. Omitting that feature is the most likely cause if you get a `sqlx-data.json` file that looks like this:
|
|
|
|
```json
|
|
{
|
|
"database": "PostgreSQL"
|
|
}
|
|
```
|
|
|
|
----
|
|
```bash
|
|
cargo sqlx prepare --check
|
|
```
|
|
Exits with a nonzero exit status if the data in `sqlx-data.json` is out of date with the current
|
|
database schema and queries in the project. Intended for use in Continuous Integration.
|
|
|
|
#### Force building in offline mode
|
|
|
|
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.
|