Add docs for fetch_all, example for postgres transactions (#1255)

* reference fetch_all() in query macros

* add example for using transactions in postgres

Cargo.toml

@@ -12,6 +12,7 @@ members = [
     "examples/postgres/listen",
     "examples/postgres/todos",
     "examples/postgres/mockable-todos",
+    "examples/postgres/transaction",
     "examples/sqlite/todos",
 ]
 

examples/postgres/transaction/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "sqlx-example-postgres-transaction"
+version = "0.1.0"
+edition = "2018"
+workspace = "../../../"
+
+[dependencies]
+async-std = { version = "1.8.0", features = [ "attributes", "unstable" ] }
+sqlx = { path = "../../../", features = [ "postgres", "tls", "runtime-async-std-native-tls" ] }
+futures = "0.3.1"

examples/postgres/transaction/README.md

@@ -0,0 +1,18 @@
+# Postgres Transaction Example
+
+A simple example demonstrating how to obtain and roll back a transaction with postgres.
+
+## Usage
+
+Declare the database URL. This example does not include any reading or writing of data.
+
+```
+export DATABASE_URL="postgres://postgres@localhost/postgres"
+```
+
+Run.
+
+```
+cargo run
+```
+

examples/postgres/transaction/migrations/20200718111257_todos.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS todos
+(
+    id          BIGSERIAL PRIMARY KEY,
+    description TEXT    NOT NULL,
+    done        BOOLEAN NOT NULL DEFAULT FALSE
+);

examples/postgres/transaction/src/main.rs

@@ -0,0 +1,37 @@
+use sqlx::query;
+
+#[async_std::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let conn_str =
+        std::env::var("DATABASE_URL").expect("Env var DATABASE_URL is required for this example.");
+    let pool = sqlx::PgPool::connect(&conn_str).await?;
+
+    let mut transaction = pool.begin().await?;
+
+    let test_id = 1;
+    query!(
+        r#"INSERT INTO todos (id, description)
+        VALUES ( $1, $2 )
+        "#,
+        test_id,
+        "test todo"
+    )
+    .execute(&mut transaction)
+    .await?;
+
+    // check that inserted todo can be fetched
+    let _ = query!(r#"SELECT FROM todos WHERE id = $1"#, test_id)
+        .fetch_one(&mut transaction)
+        .await?;
+
+    transaction.rollback();
+
+    // check that inserted todo is now gone
+    let inserted_todo = query!(r#"SELECT FROM todos WHERE id = $1"#, test_id)
+        .fetch_one(&pool)
+        .await;
+
+    assert!(inserted_todo.is_err());
+
+    Ok(())
+}

src/macros.rs

@@ -36,6 +36,7 @@
 /// | Zero or One    | `.fetch_optional(...).await`| `sqlx::Result<Option<{adhoc struct}>>`              | Extra rows are ignored. |
 /// | Exactly One    | `.fetch_one(...).await`     | `sqlx::Result<{adhoc struct}>`                      | Errors if no rows were returned. Extra rows are ignored. Aggregate queries, use this. |
 /// | At Least One   | `.fetch(...)`               | `impl Stream<Item = sqlx::Result<{adhoc struct}>>`  | Call `.try_next().await` to get each row result. |
+/// | Multiple   | `.fetch_all(...)`               | `sqlx::Result<Vec<{adhoc struct}>>`  | |
 ///
 /// \* All methods accept one of `&mut {connection type}`, `&mut Transaction` or `&Pool`.
 /// † Only callable if the query returns no columns; otherwise it's assumed the query *may* return at least one row.
@@ -459,6 +460,7 @@ macro_rules! query_file_unchecked (
 /// | Zero or One    | `.fetch_optional(...).await`| `sqlx::Result<Option<T>>`              | Extra rows are ignored. |
 /// | Exactly One    | `.fetch_one(...).await`     | `sqlx::Result<T>`                      | Errors if no rows were returned. Extra rows are ignored. Aggregate queries, use this. |
 /// | At Least One   | `.fetch(...)`               | `impl Stream<Item = sqlx::Result<T>>`  | Call `.try_next().await` to get each row result. |
+/// | Multiple       | `.fetch_all(...)`           | `sqlx::Result<Vec<T>>`  | |
 ///
 /// \* All methods accept one of `&mut {connection type}`, `&mut Transaction` or `&Pool`.
 /// (`.execute()` is omitted as this macro requires at least one column to be returned.)