chore: update documentation to replace sqlx-data.json with .sqlx

Author: cycraig

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

sqlx-cli/README.md

@@ -106,44 +106,43 @@ 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`.
 
 ```bash
 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.