Skip to content

Commit a3417e7

Browse files
committed
Reword "building in offline mode"
Sometimes people do a bad job of reading comprehension (see launchbadge#1813). This rewords a little to be even more prescriptive about how to build in offline mode.
1 parent b934f82 commit a3417e7

File tree

1 file changed

+12
-4
lines changed

1 file changed

+12
-4
lines changed

sqlx-cli/README.md

+12-4
Original file line numberDiff line numberDiff line change
@@ -106,16 +106,24 @@ error: cannot mix reversible migrations with simple migrations. All migrations s
106106

107107
#### Enable building in "offline mode" with `query!()`
108108

109-
Note: must be run as `cargo sqlx`.
109+
There are 3 steps to building with "offline mode":
110+
111+
1. Enable the Cargo feature `offline`
112+
- E.g. in your `Cargo.toml`, ensure: `sqlx = { features = [ "offline", ... ] }`
113+
2. Save query metadata for offline usage
114+
- `cargo sqlx prepare`
115+
3. Build
116+
117+
Note: Saving query metadata must be run as `cargo sqlx`.
110118

111119
```bash
112120
cargo sqlx prepare
113121
```
114122

115-
Saves query metadata to `sqlx-data.json` in the current directory; check this file into version
123+
Invoking `prepare` saves query metadata to `sqlx-data.json` in the current directory; check this file into version
116124
control and an active database connection will no longer be needed to build your project.
117125

118-
Has no effect unless the `offline` feature of `sqlx` is enabled in your project. Omitting that
126+
Has no effect unless the `offline` Cargo feature of `sqlx` is enabled in your project. Omitting that
119127
feature is the most likely cause if you get a `sqlx-data.json` file that looks like this:
120128

121129
```json
@@ -135,7 +143,7 @@ database schema and queries in the project. Intended for use in Continuous Integ
135143

136144
#### Force building in offline mode
137145

138-
To make sure an accidentally-present `DATABASE_URL` environment variable or `.env` file does not
146+
The presence of a `DATABASE_URL` will take precedence over the presence of `sqlx-data.json`. To make sure an accidentally-present `DATABASE_URL` environment variable or `.env` file does not
139147
result in `cargo build` (trying to) access the database, you can set the `SQLX_OFFLINE` environment
140148
variable to `true`.
141149

0 commit comments

Comments
 (0)