Added FORMAT(binary) copy capability and example

.gitignore

@@ -5,3 +5,4 @@ dub.selections.json
 *.lst
 docs
 docs.json
+example/dpq2_example*

README.md

@@ -38,6 +38,16 @@ _Please help us to make documentation better!_
 * On Linux, you may install `libpq-dev` for dynamic linking e.g. `sudo apt-get install libpq-dev`
 
 ## Example
+
+To build the included example, run commands similar to the following.
+```bash
+dub build --single example/example.d
+./example/dpq2_example --conninfo postgresql://postgres@/template1
+```
+Exact details vary based on your PostgreSQL setup and operating system.
+
+A condensed version of `example.d` follows.
+
 ```D
 #!/usr/bin/env rdmd
 

example/example.d

@@ -1,17 +1,40 @@
-#!/usr/bin/env rdmd
+#!/usr/bin/env dub
+/+ dub.sdl:
+   name "dpq2_example"
+   dependency "dpq2" version="*" path="../"
++/
 
 import dpq2;
+import std.system;
+import std.bitmanip;
 import std.getopt;
+import std.range;
 import std.stdio: writeln;
 import std.typecons: Nullable;
 import vibe.data.bson;
 
-void main(string[] args)
+alias BE = Endian.bigEndian;
+
+int main(string[] args)
 {
     string connInfo;
     getopt(args, "conninfo", &connInfo);
 
-    Connection conn = new Connection(connInfo);
+    Connection conn;
+    try{
+        conn = new Connection(connInfo);
+    }
+    catch(ConnectionException ex){
+        writeln(ex.msg);
+        writeln("Try adding the arguments:
+
+   '--conninfo postgresql://postgres@/template1' or
+   '--conninfo postgresql://postgres@localhost/template1'
+
+to set the DB connection info.  The first version has no host part
+and so it tries a local unix-domain socket.");
+        return 3;
+    }
 
     // Only text query result can be obtained by this call:
     auto answer = conn.exec(
@@ -88,4 +111,64 @@ void main(string[] args)
     // Signal that the COPY is finished. Let Postgresql finalize the command
     // and return any errors with the data.
     conn.putCopyEnd();
+    writeln("CSV copy-in worked.");
+
+
+    // It is also possible to send raw binary data.  It's even faster, and can
+    // handle any PostgreSQL type, including BYTEA, but it's more complex than
+    // sending parsable text streams
+    conn.exec("CREATE TEMP TABLE test_dpq2_blob (item BIGINT, data BYTEA)");
+
+    // Init the COPY command, this time for direct binary input
+    conn.exec("COPY test_dpq2_blob (item, data) FROM STDIN WITH (FORMAT binary)");
+
+    // For FORMAT binary, send over the 19 byte PostgreSQL header manually
+    //                   P    G    C    O    P    Y   \n  255   \r   \n
+    conn.putCopyData(cast(ubyte[])[
+        0x50,0x47,0x43,0x4F,0x50,0x59,0x0A,0xFF,0x0D,0x0A,0,0,0,0,0,0,0,0,0
+    ]);
+
+    // Write 10 rows of variable length binary data. PostgreSQL internal 
+    // storage is big endian and the number of values and the length of each
+    // must be provided.  Since binary copy-in is likely to be used in 
+    // "tight-loop" code, we'll use a stack memory. Stack buffer size is:
+    // 
+    //   2 bytes for the number of values
+    //   plus 4 length bytes for each value
+    //   plus total size of all values in the largest row
+    //
+    enum LOOPS = 10;
+    ubyte[2 + 2*4 + 8 + (2*LOOPS + 7)] buf;
+    foreach(i;0..LOOPS){
+        size_t offset = 0;
+        buf[].write!(short, BE)(2, &offset);            // Sending two fields
+
+        buf[].write!(int,   BE)(long.sizeof, &offset);  // BIGINT == long
+        buf[].write!(long,  BE)(i, &offset);            // add the item value
+
+        // Generate some data.  Here's we're making the blob larger for each
+        // iteration just to emphasize that BYTEA is not fixed length value type.
+        ubyte[] blob = iota(cast(ubyte)1, cast(ubyte)(2*i + 7), 1).array;
+
+        buf[].write!(int, BE)(cast(int)blob.length, &offset);
+
+        buf[offset..offset+blob.length] = blob;
+        offset += blob.length;
+
+        // Send the variable length buffer
+        conn.putCopyData(buf[0..offset]);
+    }
+
+    // Signal that the copy is finished. PostgreSQL will check constraints at
+    // this point.
+    conn.putCopyEnd();
+    writeln("Direct binary copy-in worked.");
+
+    // Read binary blobs back as hex-string data. 
+    // For more precise type handling use QueryParams objects with execParams and
+    // convert the output using the as!(PGbytea) template from to_d_types.d
+    foreach(row; conn.exec("SELECT item, data from test_dpq2_blob").rangify())
+        writeln(row[0], ", ", row[1]);
+
+    return 0;
 }

src/dpq2/query.d

@@ -207,6 +207,30 @@ mixin template Queries()
         return r != 0;
     }
 
+    /// Sends a buffer of binary data to the COPY command
+    ///
+    /// A details example setup and iteration for binary data copy-in 
+    /// can be found in example/example.d
+    ///
+    /// Before using this function execute a command similar to the 
+    /// the following:
+    /// ---
+    /// conn.exec("COPY mytable (col1, col2) FROM STDIN WITH (FORMAT binary)");
+    /// ---
+    ///
+    /// where the column names an types depend on the destination table.
+    /// Returns:
+    ///   true if the data was queued, false if it was not queued because of
+    ///   full buffers (this will only happen in nonblocking mode)
+    bool putCopyData(const(ubyte)[] data )
+    {
+        const int r = PQputCopyData(conn, cast(const char*)data.ptr, data.length.to!int);
+
+        if(r == -1) throw new ConnectionException(this);
+
+        return r != 0;
+    }
+
     /// Signals that COPY data send is finished. Finalize and flush the COPY command.
     immutable(Answer) putCopyEnd()
     {
@@ -501,8 +525,6 @@ void _integration_test( string connParam ) @trusted
     conn.socket.shutdown(SocketShutdown.BOTH); // breaks connection
 
     {
-        import dpq2.result: ResponseException;
-
         bool exceptionFlag = false;
         string errorMsg;
 
@@ -513,12 +535,6 @@ void _integration_test( string connParam ) @trusted
             errorMsg = e.msg;
             assert(e.msg.length > 15); // error message check
         }
-        catch(ResponseException e)
-        {
-            exceptionFlag = true;
-            errorMsg = e.msg;
-            assert(e.msg.length > 15); // error message check
-        }
         finally {
             assert(exceptionFlag, errorMsg);
         }