Add mapping information for core types.

refs #183

doc.go

@@ -81,63 +81,39 @@ releasing connections when you do not need that level of control.
         return err
     }
 
-Transactions
+Base Type Mapping
 
-Transactions are started by calling Begin or BeginIso. The BeginIso variant
+pgx maps between all common base types directly between Go and PostgreSQL. In
-creates a transaction with a specified isolation level.
+particular:
 
-    tx, err := conn.Begin()
+    Go           PostgreSQL
-    if err != nil {
+    -----------------------
-        return err
+    string       varchar
-    }
+                 text
-    // Rollback is safe to call even if the tx is already closed, so if
-    // the tx commits successfully, this is a no-op
-    defer tx.Rollback()
 
-    _, err = tx.Exec("insert into foo(id) values (1)")
+    // Integers are automatically be converted to any other integer type if
-    if err != nil {
+    // it can be done without overflow or underflow.
-        return err
+    int8
-    }
+    int16        smallint
+    int32        int
+    int64        bigint
+    int
+    uint8
+    uint16
+    uint32
+    uint64
+    uint
 
-    err = tx.Commit()
+    // Floats are strict and do not automatically convert like integers.
-    if err != nil {
+    float32      float4
-        return err
+    float64      float8
-    }
 
-Copy Protocol
+    time.Time   date
+                timestamp
+                timestamptz
 
-Use CopyTo to efficiently insert multiple rows at a time using the PostgreSQL
+    []byte      bytea
-copy protocol. CopyTo accepts a CopyToSource interface. If the data is already
-in a [][]interface{} use CopyToRows to wrap it in a CopyToSource interface. Or
-implement CopyToSource to avoid buffering the entire data set in memory.
 
-    rows := [][]interface{}{
-        {"John", "Smith", int32(36)},
-        {"Jane", "Doe", int32(29)},
-    }
-
-    copyCount, err := conn.CopyTo(
-        "people",
-        []string{"first_name", "last_name", "age"},
-        pgx.CopyToRows(rows),
-    )
-
-CopyTo can be faster than an insert with as few as 5 rows.
-
-Listen and Notify
-
-pgx can listen to the PostgreSQL notification system with the
-WaitForNotification function. It takes a maximum time to wait for a
-notification.
-
-    err := conn.Listen("channelname")
-    if err != nil {
-        return nil
-    }
-
-    if notification, err := conn.WaitForNotification(time.Second); err != nil {
-        // do something with notification
-    }
 
 Null Mapping
 
@@ -212,6 +188,64 @@ the raw bytes returned by PostgreSQL. This can be especially useful for reading
 varchar, text, json, and jsonb values directly into a []byte and avoiding the
 type conversion from string.
 
+Transactions
+
+Transactions are started by calling Begin or BeginIso. The BeginIso variant
+creates a transaction with a specified isolation level.
+
+    tx, err := conn.Begin()
+    if err != nil {
+        return err
+    }
+    // Rollback is safe to call even if the tx is already closed, so if
+    // the tx commits successfully, this is a no-op
+    defer tx.Rollback()
+
+    _, err = tx.Exec("insert into foo(id) values (1)")
+    if err != nil {
+        return err
+    }
+
+    err = tx.Commit()
+    if err != nil {
+        return err
+    }
+
+Copy Protocol
+
+Use CopyTo to efficiently insert multiple rows at a time using the PostgreSQL
+copy protocol. CopyTo accepts a CopyToSource interface. If the data is already
+in a [][]interface{} use CopyToRows to wrap it in a CopyToSource interface. Or
+implement CopyToSource to avoid buffering the entire data set in memory.
+
+    rows := [][]interface{}{
+        {"John", "Smith", int32(36)},
+        {"Jane", "Doe", int32(29)},
+    }
+
+    copyCount, err := conn.CopyTo(
+        "people",
+        []string{"first_name", "last_name", "age"},
+        pgx.CopyToRows(rows),
+    )
+
+CopyTo can be faster than an insert with as few as 5 rows.
+
+Listen and Notify
+
+pgx can listen to the PostgreSQL notification system with the
+WaitForNotification function. It takes a maximum time to wait for a
+notification.
+
+    err := conn.Listen("channelname")
+    if err != nil {
+        return nil
+    }
+
+    if notification, err := conn.WaitForNotification(time.Second); err != nil {
+        // do something with notification
+    }
+
 TLS
 
 The pgx ConnConfig struct has a TLSConfig field. If this field is