From d223ba1decc5bf4ba56dbed1bb1173252a0dab67 Mon Sep 17 00:00:00 2001
From: Joshua Davey <josh@joshuadavey.com>
Date: Mon, 22 Jul 2019 21:21:46 -0400
Subject: [PATCH] Add basic usage instructions

---
 README.org | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 108 insertions(+), 1 deletion(-)

diff --git a/README.org b/README.org
index 276cc15..ac42178 100644
--- a/README.org
+++ b/README.org
@@ -3,6 +3,113 @@
 Import data into postgres quickly, implemented using postgresql's
 =COPY= in binary format.
 
+Because sometimes =jdbc/insert!= and friends aren't fast enough.
+
+This library uses type-based dispatch for determining the correct
+postgres binary format. See the [[Input Type mapping][mapping]] section for more info.
+
+* Usage
+
+#+BEGIN_SRC clojure :exports none
+(require '[clojure.java.jdbc :as jdbc])
+
+(def conn-spec "jdbc:postgresql://localhost:5432/test_pgcopy")
+#+END_SRC
+
+#+RESULTS:
+: nil#'user/conn-spec
+
+Given a table and some data:
+
+#+BEGIN_SRC clojure :exports code
+(require '[clj-pgcopy.core :as pgcopy])
+
+(jdbc/with-db-connection [conn conn-spec]
+  (jdbc/db-do-commands conn
+                       ["drop table if exists example"
+                        "create table example(
+  internal_id bigint primary key,
+  external_id uuid,
+  height float8,
+  title varchar(64) not null,
+  description text,
+  values bytea,
+  dob date,
+  created_at timestamptz
+)"]))
+
+(def data
+  [{:internal_id 201223123
+    :external_id #uuid "1902c205-2bc6-40b8-943b-f5b199241316"
+    :height nil
+    :title "Mr. Sandman"
+    :description nil
+    :values (.getBytes "not very secret" "UTF-8")
+    :dob (java.time.LocalDate/of 1954 8 20)
+    :created_at (java.util.Date.)}
+   {:internal_id 2012391238
+    :external_id nil
+    :height 160.2
+    :title "Prince"
+    :description "Tonight we're gonna party"
+    :values (.getBytes "2000 Two Zero" "UTF-8")
+    :dob (java.time.LocalDate/of 1999 12 31)
+    :created_at (java.util.Date.)}])
+
+#+END_SRC
+
+#+RESULTS:
+: nil(0 0)#'user/data
+
+With =clojure.java.jdbc=, open a connection, prepare data rows (as
+tuples, not maps), and call =clj-pgcopy.core/copy-into!=:
+
+#+BEGIN_SRC clojure :exports both
+(let [columns [:internal_id :external_id :height
+               :title :description :values :dob :created_at]]
+  (jdbc/with-db-connection [conn conn-spec]
+    (pgcopy/copy-into! (:connection conn)
+                       :example
+                       columns
+                       (map (apply juxt columns) data))))
+#+END_SRC
+
+#+RESULTS:
+: 2
+
+The table has been populated with the data:
+
+#+BEGIN_SRC clojure :exports both :results pp
+(jdbc/with-db-connection [conn conn-spec]
+  (jdbc/query conn "table example"))
+#+END_SRC
+
+#+RESULTS:
+#+begin_example
+({:internal_id 201223123,
+  :external_id #uuid "1902c205-2bc6-40b8-943b-f5b199241316",
+  :height nil,
+  :title "Mr. Sandman",
+  :description nil,
+  :values
+  [110, 111, 116, 32, 118, 101, 114, 121, 32, 115, 101, 99, 114, 101,
+   116],
+  :dob #inst "1954-08-20T04:00:00.000-00:00",
+  :created_at #inst "2019-07-23T01:24:38.466000000-00:00"}
+ {:internal_id 2012391238,
+  :external_id nil,
+  :height 160.2,
+  :title "Prince",
+  :description "Tonight we're gonna party",
+  :values [50, 48, 48, 48, 32, 84, 119, 111, 32, 90, 101, 114, 111],
+  :dob #inst "1999-12-31T05:00:00.000-00:00",
+  :created_at #inst "2019-07-23T01:24:38.466000000-00:00"})
+#+end_example
+
+Note: depending on how you've set up =clojure.java.jdbc= and its
+=IResultSetReadColumn= protocol, the types that come back on query may
+differ from the above.
+
 * Input Type mapping
 
 ** Basic type mapping
@@ -66,7 +173,7 @@ Impemented for the following JVM-typed arrays for:
 
 Currently, only 1-dimensional Postgres arrays are supported.
 
-** TODO
+** Not Yet Implemented
 
 - hstore (wrapper?)
 - inet, cidr, macaddr, macaddr8