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

* reference fetch_all() in query macros

* add example for using transactions in postgres

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(())
+}