From baa9cd614d22ffb19ebbb5d75abbedacb3eee53f Mon Sep 17 00:00:00 2001 From: Jonas Platte Date: Sun, 30 May 2021 19:36:41 +0200 Subject: [PATCH 1/6] readme: Fix inconsistent list style --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index df8a0e056d..79e145e274 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ SQLx is an async, pure Rust† SQL crate featuring compile-time check - **Pure Rust**. The Postgres and MySQL/MariaDB drivers are written in pure Rust using **zero** unsafe†† code. -* **Runtime Agnostic**. Works on different runtimes ([async-std](https://crates.io/crates/async-std) / [tokio](https://crates.io/crates/tokio) / [actix](https://crates.io/crates/actix-rt)) and TLS backends ([native-tls](https://crates.io/crates/native-tls), [rustls](https://crates.io/crates/rustls)). +- **Runtime Agnostic**. Works on different runtimes ([async-std](https://crates.io/crates/async-std) / [tokio](https://crates.io/crates/tokio) / [actix](https://crates.io/crates/actix-rt)) and TLS backends ([native-tls](https://crates.io/crates/native-tls), [rustls](https://crates.io/crates/rustls)). † The SQLite driver uses the libsqlite3 C library as SQLite is an embedded database (the only way we could be pure Rust for SQLite is by porting _all_ of SQLite to Rust). From d1dc6e858516194a74b7d6d8866226935ef81aec Mon Sep 17 00:00:00 2001 From: Jonas Platte Date: Sun, 30 May 2021 19:40:19 +0200 Subject: [PATCH 2/6] readme: Improve text alignment --- README.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 79e145e274..365df56482 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@
- Built with ❤️ by The LaunchBadge team + Built with ❤️ by The LaunchBadge team

@@ -68,11 +68,15 @@ SQLx is an async, pure Rust† SQL crate featuring compile-time check - **Runtime Agnostic**. Works on different runtimes ([async-std](https://crates.io/crates/async-std) / [tokio](https://crates.io/crates/tokio) / [actix](https://crates.io/crates/actix-rt)) and TLS backends ([native-tls](https://crates.io/crates/native-tls), [rustls](https://crates.io/crates/rustls)). -† The SQLite driver uses the libsqlite3 C library as SQLite is an embedded database (the only way -we could be pure Rust for SQLite is by porting _all_ of SQLite to Rust). + -†† SQLx uses `#![forbid(unsafe_code)]` unless the `sqlite` feature is enabled. As the SQLite driver interacts -with C, those interactions are `unsafe`. +† The SQLite driver uses the libsqlite3 C library as SQLite is an embedded database (the only way +we could be pure Rust for SQLite is by porting _all_ of SQLite to Rust). + +†† SQLx uses `#![forbid(unsafe_code)]` unless the `sqlite` feature is enabled. As the SQLite driver interacts +with C, those interactions are `unsafe`. + + [postgresql]: http://postgresql.org/ [sqlite]: https://sqlite.org/ @@ -118,7 +122,7 @@ sqlx = { version = "0.5", features = [ "runtime-tokio-rustls" ] } sqlx = { version = "0.5", features = [ "runtime-async-std-native-tls" ] } ``` -The runtime and TLS backend not being separate feature sets to select is a workaround for a [Cargo issue](https://github.com/rust-lang/cargo/issues/3494). +The runtime and TLS backend not being separate feature sets to select is a workaround for a [Cargo issue](https://github.com/rust-lang/cargo/issues/3494). #### Cargo Feature Flags From a6ab7c4eb1904f5724641b32dd7578f2b9710298 Mon Sep 17 00:00:00 2001 From: Jonas Platte Date: Sun, 30 May 2021 19:41:46 +0200 Subject: [PATCH 3/6] readme: Fix missing links --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 365df56482..5c8a2a1887 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,8 @@ SQLx is compatible with the [`async-std`], [`tokio`] and [`actix`] runtimes; and [`async-std`]: https://github.com/async-rs/async-std [`tokio`]: https://github.com/tokio-rs/tokio [`actix`]: https://github.com/actix/actix-net +[`native-tls`]: https://crates.io/crates/native-tls +[`rustls`]: https://crates.io/crates/rustls ```toml # Cargo.toml From cde3df5e337984416aada044ec886653967dd629 Mon Sep 17 00:00:00 2001 From: Jonas Platte Date: Sun, 30 May 2021 19:43:34 +0200 Subject: [PATCH 4/6] readme: Consistently use code formatting for runtime & TLS crates and dedup links --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5c8a2a1887..5206c3a3a1 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ SQLx is an async, pure Rust† SQL crate featuring compile-time check - **Pure Rust**. The Postgres and MySQL/MariaDB drivers are written in pure Rust using **zero** unsafe†† code. -- **Runtime Agnostic**. Works on different runtimes ([async-std](https://crates.io/crates/async-std) / [tokio](https://crates.io/crates/tokio) / [actix](https://crates.io/crates/actix-rt)) and TLS backends ([native-tls](https://crates.io/crates/native-tls), [rustls](https://crates.io/crates/rustls)). +- **Runtime Agnostic**. Works on different runtimes ([`async-std`] / [`tokio`] / [`actix`]) and TLS backends ([`native-tls`], [`rustls`]). From 87bd50e46a608f8086a949b737e16ad4e85a386e Mon Sep 17 00:00:00 2001 From: Jonas Platte Date: Sun, 30 May 2021 20:16:45 +0200 Subject: [PATCH 5/6] readme: Add SQLx is not an ORM section --- README.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5206c3a3a1..7019dedebb 100644 --- a/README.md +++ b/README.md @@ -59,8 +59,7 @@ SQLx is an async, pure Rust† SQL crate featuring compile-time check - **Truly Asynchronous**. Built from the ground-up using async/await for maximum concurrency. -- **Type-safe SQL** (if you want it) without DSLs. Use the `query!()` macro to check your SQL and bind parameters at - compile time. (You can still use dynamic SQL queries if you like.) +- **Compile-time checked queries** (if you want). See [SQLx is not an ORM](#sqlx-is-not-an-orm). - **Database Agnostic**. Support for [PostgreSQL], [MySQL], [SQLite], and [MSSQL]. @@ -174,6 +173,24 @@ sqlx = { version = "0.5", features = [ "runtime-async-std-native-tls" ] } - `tls`: Add support for TLS connections. +## SQLx is not an ORM! + +SQLx supports **compile-time checked queries**. It does not, however, do this by providing a Rust +API or DSL (domain-specific language) for building queries. Instead, it provides macros that take +regular SQL as an input and ensure that it is valid for your database. The way this works is that +SQLx connects to your development DB at compile time to have the database itself verify (and return +some info on) your SQL queries. This has some potentially surprising implications: + +- Since SQLx never has to parse the SQL string itself, any syntax that the development DB accepts + can be used (including things added by database extensions) +- Due to the different amount of information databases let you retrieve about queries, the extent of + SQL verification you get from the query macros depends on the database + +**If you are looking for an (asynchronous) ORM,** you can check out [`ormx`], which is built on top +of SQLx. + +[`ormx`]: https://crates.io/crates/ormx + ## Usage ### Quickstart From 823d393cd882163966db2fe10e842ea634a191c9 Mon Sep 17 00:00:00 2001 From: Jonas Platte Date: Sun, 30 May 2021 20:25:32 +0200 Subject: [PATCH 6/6] readme: Improve documentation about offline mode --- README.md | 9 +++++++-- sqlx-cli/README.md | 17 ++++++++++++----- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 7019dedebb..7b14e4574b 100644 --- a/README.md +++ b/README.md @@ -359,8 +359,8 @@ Differences from `query()`: ``` The biggest downside to `query!()` is that the output type cannot be named (due to Rust not -officially supporting anonymous records). To address that, there is a `query_as!()` macro that is identical -except that you can name the output type. +officially supporting anonymous records). To address that, there is a `query_as!()` macro that is +mostly identical except that you can name the output type. ```rust // no traits are needed @@ -382,6 +382,11 @@ WHERE organization = ? // countries[0].count ``` +To avoid the need of having a development database around to compile the project even when no +modifications (to the database-accessing parts of the code) are done, you can enable "offline mode" +to cache the results of the SQL query analysis using the `sqlx` command-line tool. See +[sqlx-cli/README.md](./sqlx-cli/README.md#enable-building-in-offline-mode-with-query). + ## Safety This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in 100% Safe Rust. diff --git a/sqlx-cli/README.md b/sqlx-cli/README.md index 0c47941c4e..f098dad8ab 100644 --- a/sqlx-cli/README.md +++ b/sqlx-cli/README.md @@ -49,17 +49,19 @@ $ sqlx migrate 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!()` +#### 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: +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. + +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 { @@ -67,10 +69,12 @@ Has no effect unless the `offline` feature of `sqlx` is enabled in your project. } ``` ----- +--- + ```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. @@ -79,3 +83,6 @@ database schema and queries in the project. Intended for use in Continuous Integ 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`. + +If you want to make this the default, just add it to your `.env` file. `cargo sqlx prepare` will +still do the right thing and connect to the database.