From f6fbd55fcb261a5a4cecad30f426d9e4a7bce84c Mon Sep 17 00:00:00 2001 From: Craig Bester <me@craigbester.com> Date: Sun, 19 Feb 2023 00:10:42 +0200 Subject: [PATCH] chore: update documentation to replace sqlx-data.json with .sqlx --- FAQ.md | 25 +++++++++++++++++-------- sqlx-cli/README.md | 37 ++++++++++++++++++------------------- 2 files changed, 35 insertions(+), 27 deletions(-) diff --git a/FAQ.md b/FAQ.md index 678a3e7527..898097050e 100644 --- a/FAQ.md +++ b/FAQ.md @@ -180,26 +180,35 @@ See Also: ---- ### How do I compile with the macros without needing a database, e.g. in CI? -The macros support an offline mode which saves data for existing queries to a JSON file, -so the macros can just read that file instead of talking to a database. +The macros support an offline mode which saves data for existing queries to a `.sqlx` directory, +so the macros can just read those instead of talking to a database. See the following: * [the docs for `query!()`](https://docs.rs/sqlx/0.5.5/sqlx/macro.query.html#offline-mode-requires-the-offline-feature) * [the README for `sqlx-cli`](sqlx-cli/README.md#enable-building-in-offline-mode-with-query) -To keep `sqlx-data.json` up-to-date you need to run `cargo sqlx prepare` before every commit that +To keep `.sqlx` up-to-date you need to run `cargo sqlx prepare` before every commit that adds or changes a query; you can do this with a Git pre-commit hook: ```shell -$ echo "cargo sqlx prepare > /dev/null 2>&1; git add sqlx-data.json > /dev/null" > .git/hooks/pre-commit +$ echo "cargo sqlx prepare > /dev/null 2>&1; git add .sqlx > /dev/null" > .git/hooks/pre-commit ``` Note that this may make committing take some time as it'll cause your project to be recompiled, and as an ergonomic choice it does _not_ block committing if `cargo sqlx prepare` fails. -We're working on a way for the macros to save their data to the filesystem automatically which should be part of SQLx 0.6, -so your pre-commit hook would then just need to stage the changed files. +We're working on a way for the macros to save their data to the filesystem automatically which should be part of SQLx 0.7, +so your pre-commit hook would then just need to stage the changed files. This can be enabled by creating a directory +and setting the `SQLX_OFFLINE_DIR` environment variable to it before compiling, e.g. + +```shell +$ mkdir .sqlx +$ export SQLX_OFFLINE_DIR="./.sqlx"` +$ cargo check +``` + +However, this behaviour is not considered stable and it is still recommended to use `cargo sqlx prepare`. ---- @@ -253,9 +262,9 @@ Even Sisyphus would pity us. ### Why does my project using sqlx query macros not build on docs.rs? -Docs.rs doesn't have access to your database, so it needs to be provided a `sqlx-data.json` file and be instructed to set the `SQLX_OFFLINE` environment variable to true while compiling your project. Luckily for us, docs.rs creates a `DOCS_RS` environment variable that we can access in a custom build script to achieve this functionality. +Docs.rs doesn't have access to your database, so it needs to be provided prepared queries in a `.sqlx` directory and be instructed to set the `SQLX_OFFLINE` environment variable to true while compiling your project. Luckily for us, docs.rs creates a `DOCS_RS` environment variable that we can access in a custom build script to achieve this functionality. -To do so, first, make sure that you have run `cargo sqlx prepare` to generate a `sqlx-data.json` file in your project. +To do so, first, make sure that you have run `cargo sqlx prepare` to generate a `.sqlx` directory in your project. Next, create a file called `build.rs` in the root of your project directory (at the same level as `Cargo.toml`). Add the following code to it: ```rs diff --git a/sqlx-cli/README.md b/sqlx-cli/README.md index 726ae33cd7..60ed44a6f4 100644 --- a/sqlx-cli/README.md +++ b/sqlx-cli/README.md @@ -106,13 +106,11 @@ error: cannot mix reversible migrations with simple migrations. All migrations s ### Enable building in "offline mode" with `query!()` -There are 3 steps to building with "offline mode": +There are 2 steps to building with "offline mode": -1. Enable the SQLx's Cargo feature `offline` - - E.g. in your `Cargo.toml`, `sqlx = { features = [ "offline", ... ] }` -2. Save query metadata for offline usage +1. Save query metadata for offline usage - `cargo sqlx prepare` -3. Build +2. Build Note: Saving query metadata must be run as `cargo sqlx`. @@ -120,30 +118,31 @@ Note: Saving query metadata must be run as `cargo sqlx`. cargo sqlx prepare ``` -Invoking `prepare` saves query metadata 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. +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. -Has no effect unless the `offline` Cargo 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 --workspace ``` +Check this directory into version control and an active database connection will +no longer be needed to build your project. + --- ```bash cargo sqlx prepare --check +# OR +cargo sqlx prepare --check --workspace ``` -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. +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. ### Force building in offline mode -The presence of a `DATABASE_URL` environment variable will take precedence over the presence of `sqlx-data.json`, 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 +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`. @@ -152,8 +151,8 @@ still do the right thing and connect to the database. ### Include queries behind feature flags (such as queries inside of tests) -In order for sqlx to be able to find queries behind certain feature flags you need to turn them -on by passing arguments to rustc. +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.