Pretty much a complete rewrite/reorganization

Author: xaprb

_includes/toc.md

@@ -1,13 +1,10 @@
 1. [Overview of Go's database/sql Package](/overview/)
+1. [Importing a Database Driver](/importing/)
 1. [Accessing the Database](/accessing/)
-1. [Common Database Operations](/operations/)
-1. [Fetching Data from the Database](/fetching/)
-1. [Assigning Results to Variables](/assigning/)
-1. [Preparing Queries](/preparing/)
-1. [Single-Row Queries](/single-row-queries/)
-1. [Statements that Modify Data](/modifying/)
-1. [Working with Transactions](/transactions/)
-1. [Error Handling](/errors/)
+1. [Retrieving Result Sets](/retrieving/)
+1. [Modifying Data and Using Transactions](/modifying/)
+1. [Working with NULLs](/nulls/)
+1. [Working with Unknown Columns](/varcols/)
 1. [The Connection Pool](/connection-pool/)
 1. [Surprises, Antipatterns and Limitations](/surprises/)
 1. [Related Reading and Resources](/references/)

accessing.md

@@ -5,26 +5,12 @@ title: Accessing the Database
 tags: 
 image:
   feature: abstract-5.jpg
-share: true
+share: false
 ---
 
-
 Now that you've loaded the driver package, you're ready to create a database
 object, a `sql.DB`.
 
-The first thing you should know is that **a `sql.DB` isn't a
-database connection**. It also doesn't map to any particular database software's
-notion of a "database" or "schema." It's an abstraction of the interface and
-existence of a database, which might be a local file, accessed through a network
-connection, in-memory and in-process, or what have you.
-
-The `sql.DB` performs some important tasks for you behind the scenes:
-
-* It opens and closes connections to the actual underlying database, via the driver.
-* It manages a pool of connections as needed.
-
-These "connections" may be file handles, sockets, network connections, or other ways to access the database. The `sql.DB` abstraction is designed to keep you from worrying about how to manage concurrent access to the underlying datastore. A connection is marked in-use when you use it to perform a task, and then returned to the available pool when it's not in use anymore. One consequence of this is that **if you fail to release connections back to the pool, you can cause `db.SQL` to open a lot of connections**, potentially running out of resources (too many connections, too many open file handles, lack of available network ports, etc). We'll discuss more about this later.
-
 To create a `sql.DB`, you use `sql.Open()`. This returns a `*sql.DB`:
 
 	func main() {
@@ -40,18 +26,38 @@ In the example shown, we're illustrating several things:
 
 1. The first argument to `sql.Open` is the driver name. This is the string that the driver used to register itself with `database/sql`, and is conventionally the same as the package name to avoid confusion.
 2. The second argument is a driver-specific syntax that tells the driver how to access the underlying datastore. In this example, we're connecting to the "hello" database inside a local MySQL server instance.
-3. You should (almost) always check and handle errors returned from all `database/sql` operations.
+3. You should (almost) always check and handle errors returned from all `database/sql` operations.  There are a few special cases that we'll discuss later where it doesn't make sense to do this.
 4. It is idiomatic to `defer db.Close()` if the `sql.DB` should not have a lifetime beyond the scope of the function.
 
-Perhaps counter-intuitively, `sql.Open()` **does not establish any connections to the database**, nor does it validate driver connection parameters. Instead, it simply prepares the database abstraction for later use. The first actual connection to the underlying datastore will be established lazily, when it's needed for the first time. If you want to check right away that the database is available and accessible (for example, check that you can establish a network connection and log in), use `db.Ping()` to do that, and remember to check for errors:
+Perhaps counter-intuitively, `sql.Open()` **does not establish any connections
+to the database**, nor does it validate driver connection parameters. Instead,
+it simply prepares the database abstraction for later use. The first actual
+connection to the underlying datastore will be established lazily, when it's
+needed for the first time. If you want to check right away that the database is
+available and accessible (for example, check that you can establish a network
+connection and log in), use `db.Ping()` to do that, and remember to check for
+errors:
 
 	err = db.Ping()
 	if err != nil {
 		// do something here
 	}
 
-Although it's idiomatic to `Close()` the database when you're finished with it, **the `sql.DB` object is designed to be long-lived.** Don't `Open()` and `Close()` databases frequently. Instead, create **one** `sql.DB` object for each distinct datastore you need to access, and keep it until the program is done accessing that datastore. Pass it around as needed, or make it available somehow globally, but keep it open. And don't `Open()` and `Close()` from a short-lived function. Instead, pass the `sql.DB` into that short-lived function as an argument.
-
-If you don't treat the `sql.DB` as a long-lived object, you could experience problems such as poor reuse and sharing of connections, running out of available network resources, sporadic failures due to a lot of TCP connections remaining in TIME_WAIT status, and so on.
+Although it's idiomatic to `Close()` the database when you're finished with it,
+**the `sql.DB` object is designed to be long-lived.** Don't `Open()` and
+`Close()` databases frequently. Instead, create **one** `sql.DB` object for each
+distinct datastore you need to access, and keep it until the program is done
+accessing that datastore. Pass it around as needed, or make it available somehow
+globally, but keep it open. And don't `Open()` and `Close()` from a short-lived
+function. Instead, pass the `sql.DB` into that short-lived function as an
+argument.
+
+If you don't treat the `sql.DB` as a long-lived object, you could experience
+problems such as poor reuse and sharing of connections, running out of available
+network resources, or sporadic failures due to a lot of TCP connections
+remaining in `TIME_WAIT` status. Such problems are signs that you're not using
+`database/sql` as it was designed.
+
+Now it's time to use your `sql.DB` object.
 
 {% include toc.md %}

assigning.md

@@ -5,15 +5,25 @@ title: The Connection Pool
 tags: 
 image:
   feature: abstract-5.jpg
-share: true
+share: false
 ---
 
-There is a basic connection pool in the `database/sql` package. There isn't a lot of ability to control or inspect it, but here are some things you might find useful to know:
+There is a basic connection pool in the `database/sql` package. There isn't a
+lot of ability to control or inspect it, but here are some things you might find
+useful to know:
 
 * Connections are created when needed and there isn't a free connection in the pool.
 * There's no limit on the number of connections. If you try to do a lot of things at once, you can create an arbitrary number of connections. This can cause the database to return an error such as "too many connections."
 * In Go 1.1, you can use `db.SetMaxIdleConns(N)` to limit the number of *idle* connections in the pool. This doesn't limit the pool size, though. That will probably come in Go 1.3 or later.
 * Connections are recycled rather fast. Setting the number of idle connections with `db.SetMaxIdleConns(N)` can reduce this churn, and help keep connections around for reuse.
 
+In a future version of Go, the `database/sql` package will have the ability to
+[limit open connections](https://code.google.com/p/go/issues/detail?id=4805). In
+the meantime, it's still rather easy to run out of database connections by
+exceeding the limit set in the database itself (e.g. `max_connections` in
+MySQL). To avoid this, you'll need to limit your application's concurrent use of
+the `sql.DB` object. The idiomatic way to do that is described in the [channels
+section of the Effective Go](http://golang.org/doc/effective_go.html#channels)
+document.
 
 {% include toc.md %}

connection-pool.md

@@ -0,0 +1,40 @@
+---
+layout: page
+permalink: /importing/
+title: Importing a Database Driver
+tags: 
+image:
+  feature: abstract-5.jpg
+share: false
+---
+
+To use `database/sql` you'll need the package itself, as well as a driver for
+the specific database you want to use.
+
+You generally shouldn't use driver packages directly, although some drivers
+encourage you to do so. (In our opinion, it's usually a bad idea.) Instead, your
+code should only refer to types defined in `database/sql`, if possible. This
+helps avoid making your code dependent on the driver, so that you can change the
+underlying driver (and thus the database you're accessing) with minimal code
+changes. It also forces you to use the Go idioms instead of ad-hoc idioms that a
+particular driver author may have provided.
+
+In this documentation, we'll use the excellent [MySQL
+drivers](https://github.com/go-sql-driver/mysql) from @arnehormann and
+@julienschmidt for examples.
+
+Add the following to the top of your Go source file:
+
+	import (
+		"database/sql"
+		_ "github.com/go-sql-driver/mysql"
+	)
+
+Notice that we're loading the driver anonymously, aliasing its package qualifier
+to `_` so none of its exported names are visible to our code. Under the hood,
+the driver registers itself as being available to the `database/sql` package,
+but in general nothing else happens.
+
+Now you're ready to access a database.
+
+{% include toc.md %}

errors.md

@@ -5,15 +5,18 @@ title: Go database/sql tutorial
 tags: 
 image:
   feature: abstract-5.jpg
-share: true
+share: false
 ---
 
-This is a tutorial on [Go's database/sql package](http://golang.org/pkg/database/sql/). 
-The package's documentation tells you
-what everything does, but it doesn't tell you how to use the package. Many of us
-find ourselves wishing for a quick-reference and a "getting started"
-orientation. This website is an attempt to provide that. Contributions are
-welcome; please send pull requests
-[here](https://github.com/VividCortex/go-database-sql-tutorial).
+The idiomatic way to use a SQL, or SQL-like, database in Go is through the
+[database/sql package](http://golang.org/pkg/database/sql/).  It provides a
+lightweight interface to a row-oriented database. This website is a
+reference for the most common aspects of how to use it.
+
+Why is this needed? The package's documentation tells you what everything does,
+but it doesn't tell you how to use the package. Many of us find ourselves
+wishing for a quick-reference and a "getting started" orientation that tells
+stories instead of listing facts. Contributions are welcome; please send pull
+requests [here](https://github.com/VividCortex/go-database-sql-tutorial).
 
 {% include toc.md %}

fetching.md

@@ -1,44 +1,83 @@
 ---
 layout: page
 permalink: /modifying/
-title: Statements that Modify Data
+title: Modifying Data and Using Transactions
 tags: 
 image:
   feature: abstract-5.jpg
-share: true
+share: false
 ---
 
-As mentioned previously, you should only use `Query` functions to execute queries -- statements that return rows. Use `Exec`, preferably with a prepared statement, to accomplish an INSERT, UPDATE, DELETE, or other statement that doesn't return rows. The following example shows how to insert a row:
-
-```go
-stmt, err := db.Prepare("INSERT INTO users(name) VALUES(?)")
-if err != nil {
-	log.Fatal(err)
-}
-res, err := stmt.Exec("Dolly")
-if err != nil {
-	log.Fatal(err)
-}
-lastId, err := res.LastInsertId()
-if err != nil {
-	log.Fatal(err)
-}
-rowCnt, err := res.RowsAffected()
-if err != nil {
-	log.Fatal(err)
-}
-log.Printf("ID = %d, affected = %d\n", lastId, rowCnt)
-```
-
-Executing the statement produces a `sql.Result` that gives access to statement metadata: the last inserted ID and the number of rows affected.
-
-What if you don't care about the result? What if you just want to execute a statement and check if there were any errors, but ignore the result? Wouldn't the following two statements do the same thing?
-
-```go
-_, err := db.Exec("DELETE FROM users")  // OK
-_, err := db.Query("DELETE FROM users") // BAD
-```
-
-The answer is no. They do **not** do the same thing, and **you should never use `Query()` like this.** The `Query()` will return a `sql.Rows`, which will not be released until it's garbage collected, which can be a long time. During that time, it will continue to hold open the underlying connection, and this anti-pattern is therefore a good way to run out of resources (too many connections, for example).
+Now we're ready to see how to modify data and work with transactions. The
+distinction might seem artificial if you're used to programming languages that
+use a "statement" object for fetching rows as well as updating data, but in Go,
+there's an important reason for the difference.
+
+Statements that Modify Data
+===========================
+
+Use `Exec()`, preferably with a prepared statement, to accomplish an `INSERT`,
+`UPDATE`, `DELETE`, or other statement that doesn't return rows. The following
+example shows how to insert a row and inspect metadata about the operation:
+
+	stmt, err := db.Prepare("INSERT INTO users(name) VALUES(?)")
+	if err != nil {
+		log.Fatal(err)
+	}
+	res, err := stmt.Exec("Dolly")
+	if err != nil {
+		log.Fatal(err)
+	}
+	lastId, err := res.LastInsertId()
+	if err != nil {
+		log.Fatal(err)
+	}
+	rowCnt, err := res.RowsAffected()
+	if err != nil {
+		log.Fatal(err)
+	}
+	log.Printf("ID = %d, affected = %d\n", lastId, rowCnt)
+
+Executing the statement produces a `sql.Result` that gives access to statement
+metadata: the last inserted ID and the number of rows affected.
+
+What if you don't care about the result? What if you just want to execute a
+statement and check if there were any errors, but ignore the result? Wouldn't
+the following two statements do the same thing?
+
+	_, err := db.Exec("DELETE FROM users")  // OK
+	_, err := db.Query("DELETE FROM users") // BAD
+
+The answer is no. They do **not** do the same thing, and **you should never use
+`Query()` like this.** The `Query()` will return a `sql.Rows`, which will not be
+released until it's garbage collected, which can be a long time. During that
+time, it will continue to hold open the underlying connection, and this
+anti-pattern is therefore a good way to run out of resources (too many
+connections, for example).
+
+Working with Transactions
+=========================
+
+In Go, a transaction is essentially an object that reserves a connection to the
+datastore. It lets you do all of the operations we've seen thus far, but
+guarantees that they'll be executed on the same connection.
+
+You begin a transaction with a call to `db.Begin()`, and close it with a
+`Commit()` or `Rollback()` method on the resulting `Tx` variable. Under the
+covers, the `Tx` gets a connection from the pool, and reserves it for use only
+with that transaction. The methods on the `Tx` map one-for-one to methods you
+can call on the database itself, such as `Query()` and so forth.
+
+Prepared statements that are created in a transaction are bound exclusively to
+that transaction, and can't be used outside of it. Likewise, prepared statements
+created only on a database handle can't be used within a transaction.
+
+You should not mingle the use of transaction-related functions such as `Begin()`
+and `Commit()` with SQL statements such as `BEGIN` and `COMMIT` in your SQL
+code. Bad things might result:
+
+* The `Tx` objects could remain open, reserving a connection from the pool and not returning it.
+* The state of the database could get out of sync with the state of the Go variables representing it.
+* You could believe you're executing queries on a single connection, inside of a transaction, when in reality Go has created several connections for you invisibly and some statements aren't part of the transaction.
 
 {% include toc.md %}

importing.md

@@ -0,0 +1,43 @@
+---
+layout: page
+permalink: /nulls/
+title: Working with NULLs
+tags: 
+image:
+  feature: abstract-5.jpg
+share: false
+---
+
+Nullable columns are annoying and lead to a lot of ugly code. If you can, avoid
+them. If not, then you'll need to use special types from the `database/sql`
+package to handle them, or define your own.
+
+There are types for nullable booleans, strings, integers, and floats. Here's how
+you use them:
+
+	for rows.Next() {
+		var s sql.NullString
+		err := rows.Scan(&s)
+		// check err
+		if s.Valid {
+		   // use s.String
+		} else {
+		   // NULL value
+		}
+	}
+
+Limitations of the nullable types, and reasons to avoid nullable columns in case
+you need more convincing:
+
+1. There's no `sql.NullUint64` or `sql.NullYourFavoriteType`. You'd need to
+	define your own for this.
+1. Nullability can be tricky, and not future-proof. If you think something won't
+	be null, but you're wrong, your program will crash, perhaps rarely enough
+	that you won't catch errors before you ship them.
+1. One of the nice things about Go is having a useful default zero-value for
+	every variable. This isn't the way nullable things work.
+
+If you need to define your own types to handle NULLs, you can copy the design of
+`sql.NullString` to achieve that.
+
+{% include toc.md %}

index.md

@@ -5,48 +5,33 @@ title: Overview
 tags: 
 image:
   feature: abstract-5.jpg
-share: true
+share: false
 ---
 
-The idiomatic way to use a SQL, or SQL-like, database in Go is through the
-`database/sql` package. It provides a lightweight interface to a row-oriented
-database. This documentation is a reference for the most common aspects of how
-to use it.
+To access databases in Go, you use a `sql.DB`. You use this type to create
+statements and transactions, execute queries, and fetch results.
 
-The first thing to do is import the `database/sql` package, and a driver
-package. You generally shouldn't use the driver package directly, although some
-drivers encourage you to do so. (In our opinion, it's usually a bad idea.)
-Instead, your code should only refer to `database/sql`. This helps avoid making
-your code dependent on the driver, so that you can change the underlying driver
-(and thus the database you're accessing) without changing your code. It also
-forces you to use the Go idioms instead of ad-hoc idioms that a particular
-driver author may have provided.
+The first thing you should know is that **a `sql.DB` isn't a database
+connection**. It also doesn't map to any particular database software's notion
+of a "database" or "schema." It's an abstraction of the interface and existence
+of a database, which might be as varied as a local file, accessed through a network
+connection, or in-memory and in-process.
 
-Keep in mind that only the `database/sql` API provides this abstraction.
-Specific databases and drivers can differ in behavior and/or syntax.  One
-example is the syntax for placeholder parameters in prepared statements. For
-example, comparing MySQL, PostgreSQL, and Oracle:
+The `sql.DB` performs some important tasks for you behind the scenes:
 
-	MySQL               PostgreSQL            Oracle
-	=====               ==========            ======
-	WHERE col = ?       WHERE col = $1        WHERE col = :col
-	VALUES(?, ?, ?)     VALUES($1, $2, $3)    VALUES(:val1, :val2, :val3)
+* It opens and closes connections to the actual underlying database, via the driver.
+* It manages a pool of connections as needed, which may be a variety of things as mentioned.
 
-In this documentation, we'll use the excellent
-[MySQL drivers](https://github.com/go-sql-driver/mysql) from @arnehormann and @julienschmidt for examples.
+The `sql.DB` abstraction is designed to keep you from worrying about how to
+manage concurrent access to the underlying datastore.  A connection is marked
+in-use when you use it to perform a task, and then returned to the available
+pool when it's not in use anymore. One consequence of this is that **if you fail
+to release connections back to the pool, you can cause `db.SQL` to open a lot of
+connections**, potentially running out of resources (too many connections, too
+many open file handles, lack of available network ports, etc). We'll discuss
+more about this later.
 
-Add the following to the top of your Go source file:
-
-	import (
-		"database/sql"
-		_ "github.com/go-sql-driver/mysql"
-	)
-
-Notice that we're loading the driver anonymously, aliasing its package qualifier
-to `_` so none of its exported names are visible to our code. Under the hood,
-the driver registers itself as being available to the `database/sql` package,
-but in general nothing else happens.
-
-Now you're ready to access a database.
+After creating a `sql.DB`, you can use it to query the database that it
+represents, as well as creating statements and transactions.
 
 {% include toc.md %}

modifying.md

@@ -5,12 +5,17 @@ title: Related Reading and Resources
 tags: 
 image:
   feature: abstract-5.jpg
-share: true
+share: false
 ---
 
 Here are some external sources of information we've found to be helpful.
 
 * http://golang.org/pkg/database/sql/
 * http://jmoiron.net/blog/gos-database-sql/
+* http://jmoiron.net/blog/built-in-interfaces/
+
+We hope you've found this website to be helpful. If you have any suggestions for
+improvements, please send pull requests or open an issue report at
+https://github.com/VividCortex/go-database-sql-tutorial.
 
 {% include toc.md %}

nulls.md

@@ -0,0 +1,173 @@
+---
+layout: page
+permalink: /retrieving/
+title: Retrieving Result Sets
+tags: 
+image:
+  feature: abstract-5.jpg
+share: false
+---
+
+There are several idiomatic operations to retrieve results from the datastore.
+
+1. Execute a query that returns rows.
+1. Prepare a statement for repeated use, execute it multiple times, and destroy it.
+1. Execute a statement in a once-off fashion, without preparing it for repeated use.
+1. Execute a query that returns a single row. There is a shortcut for this special case.
+
+Go's `database/sql` function names are significant. **If a function name
+includes `Query`, it is designed to ask a question of the database, and will
+return a set of rows**, even if it's empty. Statements that don't return rows
+should not use `Query` functions; they should use `Exec()`.
+
+Fetching Data from the Database
+===============================
+
+Let's take a look at an example of how to query the database, working with
+results. We'll query the `users` table for a user whose `id` is 1, and print out
+the user's `id` and `name`.  We will assign results to variables, a row at a
+time, with `rows.Scan()`. 
+
+	var (
+		id int
+		name string
+	)
+	rows, err := db.Query("select id, name from users where id = ?", 1)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer rows.Close()
+	for rows.Next() {
+		err := rows.Scan(&id, &name)
+		if err != nil {
+			log.Fatal(err)
+		}
+		log.Println(id, name)
+	}
+	err = rows.Err()
+	if err != nil {
+		log.Fatal(err)
+	}
+
+Here's what's happening in the above code:
+
+1. We're using `db.Query()` to send the query to the database. We check the error, as usual.
+2. We defer `rows.Close()`. This is very important.
+3. We iterate over the rows with `rows.Next()`.
+4. We read the columns in each row into variables with `rows.Scan()`.
+5. We check for errors after we're done iterating over the rows.
+
+A couple parts of this are easy to get wrong, and can have bad consequences.
+
+First, as long as there's an open result set (represented by `rows`), the
+underlying connection is busy and can't be used for any other query. That means
+it's not available in the connection pool. If you iterate over all of the rows
+with `rows.Next()`, eventually you'll read the last row, and `rows.Next()` will
+encounter an internal EOF error and call `rows.Close()` for you. But if for any
+reason you exit that loop -- an error, an early return, or so on -- then the
+`rows` doesn't get closed, and the connection remains open. This is an easy way
+to run out of resources. This is why **you should always `defer rows.Close()`**,
+even if you also call it explicitly at the end of the loop, which isn't a bad
+idea. `rows.Close()` is a harmless no-op if it's already closed, so you can call
+it multiple times. Notice, however, that we check the error first, and only do
+`rows.Close()` if there isn't an error, in order to avoid a runtime panic.
+
+Second, you should always check for an error at the end of the `for rows.Next()`
+loop. If there's an error during the loop, you need to know about it. Don't just
+assume that the loop iterates until you've processed all the rows.
+
+The error returned by `rows.Close()` is the only exception to the general rule
+that it's best to capture and check for errors in all database operations. If
+`rows.Close()` throws an error, it's unclear what is the right thing to do.
+Logging the error message or panicing might be the only sensible thing to do,
+and if that's not sensible, then perhaps you should just ignore the error.
+
+This is pretty much the only way to do it in Go. You can't
+get a row as a map, for example. That's because everything is strongly typed.
+You need to create variables of the correct type and pass pointers to them, as
+shown.
+
+Preparing Queries
+=================
+
+You should, in general, always prepare queries to be used multiple times. The
+result of preparing the query is a prepared statement, which can have
+placeholders (a.k.a. bind values) for parameters that you'll provide when you
+execute the statement.  This is much better than concatenating strings, for all
+the usual reasons (avoiding SQL injection attacks, for example).
+
+In MySQL, the parameter placeholder is `?`, and in PostgreSQL it is `$N`, where
+N is a number. In Oracle placeholders begin with a colon and are named, like
+`:param1`. We'll use `?` because we're using MySQL as our example.
+
+	stmt, err := db.Prepare("select id, name from users where id = ?")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer stmt.Close()
+	rows, err := stmt.Query(1)
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer rows.Close()
+	for rows.Next() {
+		// ...
+	}
+
+Under the hood, `db.Query()` actually prepares, executes, and closes a prepared
+statement. That's three round-trips to the database. If you're not careful, you
+can triple the number of database interactions your application makes! Some
+drivers can avoid this in specific cases with an addition to `database/sql` in
+Go 1.1, but not all drivers are smart enough to do that. Caveat Emptor.
+
+Statements are like results: they claim a connection and should be closed. It's
+idiomatic to `defer stmt.Close()` if the prepared statement `stmt` should not
+have a lifetime beyond the scope of the function. If you don't, it'll reserve a
+connection from the pool, and can cause resource exhaustion. (Note that for
+efficiency you should always close statements, rows, transactions, etc as soon
+as you can.)
+
+Single-Row Queries
+==================
+
+If a query returns at most one row, you can use a shortcut around some of the
+lengthy boilerplate code:
+
+	var name string
+	err = db.QueryRow("select name from users where id = ?", 1).Scan(&name)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println(name)
+
+Errors from the query are deferred until `Scan()` is called, and then are
+returned from that. You can also call `QueryRow()` on a prepared statement:
+
+	stmt, err := db.Prepare("select id, name from users where id = ?")
+	if err != nil {
+		log.Fatal(err)
+	}
+	var name string
+	err = stmt.QueryRow(1).Scan(&name)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println(name)
+
+Go defines a special error constant, called `sql.ErrNoRows`, which is returned
+from `QueryRow()` when the result is empty. This needs to be handled as a
+special case in most circumstances. An empty result is often not considered an
+error by application code, and if you don't check whether an error is this
+special constant, you'll cause application-code errors you didn't expect.
+
+One might ask why an empty result set is considered an error. There's nothing
+erroneous about an empty set. The reason is that the `QueryRow()` method needs
+to use this special-case in order to let the caller distinguish whether
+`QueryRow()` in fact found a row; without it, `Scan()` wouldn't do anything and
+you might not realize that your variable didn't get any value from the database
+after all.
+
+You should not run into this error when you're not using `QueryRow()`. If you
+encounter this error elsewhere, you're doing something wrong.
+
+{% include toc.md %}

operations.md

@@ -5,35 +5,70 @@ title: Surprises, Antipatterns and Limitations
 tags: 
 image:
   feature: abstract-5.jpg
-share: true
+share: false
 ---
 
-We've documented several surprises and antipatterns throughout this tutorial, so please refer back to them if you didn't read them already:
+Although `database/sql` is simple once you're accustomed to it, you might be
+surprised by the subtlety of use cases it supports. This is common to Go's core
+libraries.
+
+Resource Exhaustion
+===================
+
+As mentioned throughtout this site, if you don't use `database/sql` as intended,
+you can certainly cause trouble for yourself, usually by consuming some
+resources or preventing them from being reused effectively:
 
 * Opening and closing databases can cause exhaustion of resources.
-* Failing to use `rows.Close()` or `stmt.Close()` can cause exhaustion of resources.
-* Mixing transactional methods and transactional SQL commands can cause exhaustion of resources.
-* Using `Query()` for a statement that doesn't return rows is a bad idea.
+* Failing to use `rows.Close()` or `stmt.Close()` reserves connections from the pool.
+* Using `Query()` for a statement that doesn't return rows will reserve a connection from the pool.
 * Failing to use prepared statements can lead to a lot of extra database activity.
-* Nulls cause annoying problems, which may show up only in production.
-* There's a special error when there's an empty result set, which should be checked to avoid application bugs.
 
-There are also a couple of limitations in the `database/sql` package. The interface doesn't give you all-encompassing access to what's happening under the hood. For example, you don't have much control over the pool of connections.
+Large uint64 Values
+===================
+
+Here's a surprising error. You can't pass big unsigned integers as parameters to
+statements if their high bit is set:
+
+	_, err := db.Exec("INSERT INTO users(id) VALUES", math.MaxUint64)
+
+This will throw an error. Be careful if you use `uint64` values, as they may
+start out small and work without error, but increment over time and start
+throwing errors.
+
+Connection State Mismatch
+=========================
+
+Some things can change connection state, and that can cause problems for two
+reasons:
+
+1. Some connection state, such as whether you're in a transaction, should be
+	handled through the Go types instead.
+2. You might be assuming that your queries run on a single connection when they
+	don't.
+
+For example, setting the current database with a `USE` statement is a typical
+thing for many people to do. But in Go, it will affect only the connection that
+you run it in. Unless you are in a transaction, other statements that you think
+are executed on that connection may actually run on different connections gotten
+from the pool, so they won't see the effects of such changes.
 
-Another limitation, which can be a surprise, is that you can't pass big unsigned integers as parameters to statements if their high bit is set:
+Additionally, after you've changed the connection, it'll return to the pool and
+potentially pollute the state for some other code. This is one of the reasons
+why you should never issue BEGIN or COMMIT statements as SQL commands directly,
+too.
 
-```go
-_, err := db.Exec("INSERT INTO users(id) VALUES", math.MaxUint64)
-```
+Database-Specific Syntax
+========================
 
-This will throw an error. Be careful if you use `uint64` values, as they may start out small and work without error, but increment over time and start throwing errors.
+The `database/sql` API provides an abstraction of a row-oriented database, but
+specific databases and drivers can differ in behavior and/or syntax.  One
+example is the syntax for placeholder parameters in prepared statements. For
+example, comparing MySQL, PostgreSQL, and Oracle:
 
-Another possible surprise is the effects of doing things that change connection state, such as
-setting the current database with a `USE` statement. This will affect only the connection
-that you run it in. Unless you are in a transaction, other statements that you think are
-executed on that connection may actually run on different connections gotten from the pool, so they won't see
-the effects of such changes. Additionally, after you've changed the connection, it'll return
-to the pool and potentially pollute the state for some other code. This is one of the reasons
-why you should never issue BEGIN or COMMIT statements as SQL commands directly, too.
+	MySQL               PostgreSQL            Oracle
+	=====               ==========            ======
+	WHERE col = ?       WHERE col = $1        WHERE col = :col
+	VALUES(?, ?, ?)     VALUES($1, $2, $3)    VALUES(:val1, :val2, :val3)
 
 {% include toc.md %}

overview.md

@@ -0,0 +1,58 @@
+---
+layout: page
+permalink: /varcols/
+title: Working with Unknown Columns
+tags: 
+image:
+  feature: abstract-5.jpg
+share: false
+---
+
+The `Scan()` function requires you to pass exactly the right number of
+destination variables. What if you don't know what the query will return?
+
+If you don't know how many columns the query will return, you can use
+`Columns()` to find a list of column names. You can examine the length of this
+list to see how many columns there are, and you can pass a slice into `Scan()`
+with the correct number of values. For example, some forks of MySQL return
+different columns for the `SHOW PROCESSLIST` command, so you have to be prepared
+for that or you'll cause an error. Here's one way to do it; there are others:
+
+	cols, err := rows.Columns()
+	if err != nil {
+		// handle the error
+	} else {
+		dest := []interface{}{ // Standard MySQL columns
+			new(uint64), // id
+			new(string), // host
+			new(string), // user
+			new(string), // db
+			new(string), // command
+			new(uint32), // time
+			new(string), // state
+			new(string), // info
+		}
+		if len(cols) == 11 {
+			// Percona Server
+		} else if len(cols) > 8 {
+			// Handle this case
+		}
+		err = rows.Scan(dest...)
+		// Work with the values in dest
+	}
+
+If you don't know the columns or their types, you should use `sql.RawBytes`.
+
+	cols, err := rows.Columns() // Remember to check err afterwards
+	vals := make([]interface{}, len(cols))
+	for i, _ := range cols {
+		ints[i] = new(sql.RawBytes)
+	}
+	for rows.Next() {
+		err = rows.Scan(vals...)
+		// Now you can check each element of vals for nil-ness,
+		// and you can use type introspection and type assertions
+		// to fetch the column into a typed variable.
+	}
+
+{% include toc.md %}