From febcd9eb1f4990bcca21cb09231879c2228918ae Mon Sep 17 00:00:00 2001
From: Ryan Leckey <ryan@launchbadge.com>
Date: Sun, 9 Jun 2019 09:31:37 -0700
Subject: [PATCH] Add some experimental usage thoughts

---
 README.md   | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 src/main.rs |  7 -------
 2 files changed, 46 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 00825e66..7423d294 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,52 @@ This is an experiment being worked on in stages. The first stage
 will be a very low-level, generic database driver (hopefully) capable of basic execution of
 simple queries.
 
+## Usage
+
+What follows is _experimental_ usage (for thinking on API design) that is not currently implemented.
+
+```rust
+#![feature(async_await)]
+
+use mason::pg::Connection;
+
+#[runtime::main]
+async fn main() -> Result<(), failure::Error> {
+    // this will likely be something like eventually:
+    //  mason::Connection::<Pg>::establish(...)
+
+    let mut conn = Connection::establish(ConnectOptions::new().user("postgres")).await?;
+    // or: Connection::establish("postgres://postgres@localhost/").await?;
+    // or: ConnectOptions::new().user("postgres").establish().await?;
+
+    // Execute a "simple" query. Can consist of N statements separated by semicolons.
+    // No results are returned.
+
+    conn.execute("CREATE TABLE IF NOT EXISTS users ( id UUID PRIMARY KEY, name TEXT NOT NULL );")
+        .await?;
+
+    // prepare() -> Statement
+    //  - A `Statement` can be cached and re-bound later for improved performance
+    conn.prepare("SELECT id FROM users WHERE name ilike $1")
+        // bind() -> Cursor (named [Cursor] in mysql or sqlite but [Portal] in postgres)
+        .bind(&["bob"])
+        // execute() -> u64
+        //  - execute may be used instead of fetch to ignore all results and only
+        //    return the "affected" rows
+        // fetch() -> Stream<Item = Row>
+        .fetch()
+        .collect::<Vec<Row>>()
+        .await?;
+
+    // Close is not strictly needed but this makes sure any pending writes to the connection
+    // are flushed and gracefully closes the connection
+
+    conn.close().await?;
+
+    Ok(())
+}
+```
+
 ## License
 
 Licensed under either of
diff --git a/src/main.rs b/src/main.rs
index 9126e59e..6a01e47d 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,15 +1,8 @@
 #![feature(async_await)]
 
-use mason::pg::Connection;
-
 #[runtime::main]
 async fn main() -> Result<(), failure::Error> {
     env_logger::try_init()?;
 
-    let mut conn = Connection::open("127.0.0.1:5432").await?;
-
-    conn.startup("postgres", "", "postgres").await?;
-    conn.terminate().await?;
-
     Ok(())
 }