[offline] Change prepare to one-file-per-query

[cycraig]

Description

Copy of #2110.
Continuation of/supersedes #1770 (comment) and #1183.

Overhauls offline query metadata from being saved in a single sqlx-data.json file, to every query being saved separately in a .sqlx directory (either in the package or workspace root depending on the --workspace flag).

E.g.

.sqlx
├── query-2b192bf413d46a28226de2ad754a382043c483cf55c04d19bdfa916dcbf0e7ae.json
├── query-95d796755ea0ade4578c91d102407ae003487e40922284cdd6f5c8cbc8d0b5e2.json
└── query-e46f12d720e0911c9280a1b43d7aab30beef94861713fa686db77cfe30702792.json

Changed

Many of the changes are from #1770 and #1183. I updated the previous work on this with the latest changes from the main branch, implemented outstanding things like cargo sqlx prepare --check, and fixed several bugs.

• Change sqlx prepare to save queries individually in a .sqlx directory.
• Rename --merged flag to --workspace for sqlx prepare.
• Test offline query macros in GitHub Actions.

Related issues

Closes #570
#1005 Edit: this PR is no longer related to MSSQL.

Supersedes #2322

Type of change

Breaking change. Developers will need to install the latest sqlx-cli and re-run cargo sqlx prepare in their projects.

How does it work?

Saving offline queries

1. When running cargo sqlx prepare, the command will execute cargo check with the SQLX_OFFLINE_DIR environment variable set to <package or workspace>/.sqlx, depending on the --workspace flag.
2. Then, expand_with_data in sqlx-macros saves the query metadata to a temporary file, before moving it to the SQLX_OFFLINE_DIR path (the move/rename operation should be atomic).
   • Note that this, in conjunction with queries not being saved when SQLX_OFFLINE_DIR is not set (either manually or by sqlx prepare), should avoid any race conditions with IDEs building at the same time like cargo sqlx prepare picks up queries from another crate #2049.

Note that SQLX_OFFLINE_DIR can be set manually so cargo check without cargo sqlx prepare can generate query files---useful for the CI---but the environment variable doesn't override the directories used by sqlx prepare or sqlx prepare --check, should it? I'm concerned about data loss if it's set to another directory and sqlx prepare tries to delete it. Edit: changed removal behaviour so only query-*.json files are deleted.

Loading offline queries

When loading query metadata offline, expand_input in sqlx-macros will check if the query is saved in SQLX_OFFLINE_DIR if set, then <package>/.sqlx, then <workspace>/.sqlx.

Checking offline queries

Running cargo sqlx prepare --check will generate queries and place them in target/sqlx-prepare-check and compare the contents to <package or workspace>/.sqlx, depending on the --workspace flag.

If there are queries in target/sqlx-prepare-check that aren't in <package or workspace>/.sqlx (indicating new queries were probably added), the command will fail with an error: prepare check failed: .sqlx is missing one or more queries; you should re-run sqlx prepare.

If there are unused queries in <package or workspace>/.sqlx that aren't in target/sqlx-prepare-check (indicating old queries were probably removed), the command will succeed with a warning: potentially unused queries found in .sqlx; you may want to re-run sqlx prepare.

Finally, it will compare the JSON contents of files in both directories to ensure they match.

[cycraig]

See comments on previous PR. #2110 (comment)

[cycraig]

Hmm, bad rebase. Going back to draft for now until I can clean out the differences from 0.7-dev and main.

Edit: seems to have been due to the force-push to main. Un-drafting again to check CI.

[mrl5]

worth mentioning that:

• sqlx-cli version needs to be in sync with sqlx version used in a project
• offline feature is no longer available for sqlx package (seems like it's present only for sqlx-core package)

more context in #1163 (comment)

[exFalso]

Is there a way to switch back to the sqlx-data.json behaviour? All these files are bloating github reviews with sometimes hundreds of changed files, and the newly created files always need to be manually staged.