From 11a7dcab197e89966497c715616f5593f9b3f9a4 Mon Sep 17 00:00:00 2001
From: Marko Tiikkaja <marko@joh.to>
Date: Thu, 26 Jun 2014 02:00:51 +0200
Subject: [PATCH 01/47] Warn about deferring the closure of a txn-scoped Stmt

---
 surprises.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/surprises.md b/surprises.md
index f20cc2d..c9f40ef 100644
--- a/surprises.md
+++ b/surprises.md
@@ -119,5 +119,43 @@ you attempt to perform another statement before the first has released that reso
 and cleaned up after itself.  This also means that each statement in a transaction
 results in a separate set of network round-trips to the database.
 
+Prepared Statements in Transactions
+===================================
+
+Caution must be exercised when working with prepared statements in
+transactions.  Consider the following example:
+
+<pre class="prettyprint lang-go">
+tx, err := db.Begin()
+if err != nil {
+	log.Fatal(err)
+}
+defer tx.Rollback()
+stmt, err := tx.Prepare("INSERT INTO foo VALUES (?)")
+if err != nil {
+	log.Fatal(err)
+}
+defer stmt.Close() // danger!
+for i := 0; i < 10; i++ {
+	_, err = stmt.Exec(i)
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+err = tx.Commit()
+if err != nil {
+	log.Fatal(err)
+}
+// stmt.Close() runs here!
+</pre>
+
+Closing a `*sql.Tx` releases the connection associated with it back into the
+pool, but the deferred call to Close on the prepared statement is executed
+**after** that has happened, which could lead to concurrent access to the
+underlying connection, rendering the connection state inconsistent.
+`database/sql` does not guard you against this particular behaviour.  Instead,
+you should make sure the statement is always closed before the transaction is
+committed or rolled back.
+
 **Previous: [The Connection Pool](connection-pool.html)**
 **Next: [Related Reading and Resources](references.html)**

From 2aa0fe91744d284cc1105220c5ee3afde881a5ef Mon Sep 17 00:00:00 2001
From: gauravagarwal <gauravagarwal4@gmail.com>
Date: Fri, 19 Sep 2014 12:23:54 +0530
Subject: [PATCH 02/47] Update modifying.md

---
 modifying.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/modifying.md b/modifying.md
index 324a961..5c74d44 100644
--- a/modifying.md
+++ b/modifying.md
@@ -74,7 +74,8 @@ 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.
+created only on a database handle can't be used within a transaction. In order to 
+use a Prepared statement prepared outside the transaction, use `Tx.Stmt()`.
 
 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

From 445cd734d013910063a6cf96f353e375a1dc9949 Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 15:01:07 -0500
Subject: [PATCH 03/47] Minor tweaks

---
 modifying.md  | 6 ++++--
 retrieving.md | 3 +++
 surprises.md  | 5 ++++-
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/modifying.md b/modifying.md
index 5c74d44..3a011f9 100644
--- a/modifying.md
+++ b/modifying.md
@@ -74,8 +74,10 @@ 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. In order to 
-use a Prepared statement prepared outside the transaction, use `Tx.Stmt()`.
+created only on a database handle can't be used within a transaction. To 
+use a prepared statement prepared outside the transaction, use `Tx.Stmt()`,
+which will create a new transaction-specific statement from the one prepared
+outside the 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
diff --git a/retrieving.md b/retrieving.md
index d774a7e..e1d184c 100644
--- a/retrieving.md
+++ b/retrieving.md
@@ -112,6 +112,9 @@ defer rows.Close()
 for rows.Next() {
 	// ...
 }
+if err = rows.Err(); err != nil {
+	log.Fatal(err)
+}
 </pre>
 
 Under the hood, `db.Query()` actually prepares, executes, and closes a prepared
diff --git a/surprises.md b/surprises.md
index c9f40ef..e332302 100644
--- a/surprises.md
+++ b/surprises.md
@@ -123,7 +123,7 @@ Prepared Statements in Transactions
 ===================================
 
 Caution must be exercised when working with prepared statements in
-transactions.  Consider the following example:
+transactions. Consider the following example:
 
 <pre class="prettyprint lang-go">
 tx, err := db.Begin()
@@ -157,5 +157,8 @@ underlying connection, rendering the connection state inconsistent.
 you should make sure the statement is always closed before the transaction is
 committed or rolled back.
 
+This is a [known issue](https://code.google.com/p/go/issues/detail?id=4459) that
+will probably be fixed in Go 1.4 by [CR 131650043](https://codereview.appspot.com/131650043).
+
 **Previous: [The Connection Pool](connection-pool.html)**
 **Next: [Related Reading and Resources](references.html)**

From efee3d3b7aaadae054c8df322e285acbcb0ae308 Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 15:35:05 -0500
Subject: [PATCH 04/47] Reorganize error code; fix #58

---
 errors.md     | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++
 modifying.md  |   2 +-
 nulls.md      |   2 +-
 retrieving.md |  32 ++----------
 4 files changed, 140 insertions(+), 29 deletions(-)
 create mode 100644 errors.md

diff --git a/errors.md b/errors.md
new file mode 100644
index 0000000..37d7eb9
--- /dev/null
+++ b/errors.md
@@ -0,0 +1,133 @@
+---
+layout: article
+title: Handling Errors
+---
+
+Almost all operations with `database/sql` types return an error as the last
+value. You should always check these errors, never ignore them.
+
+There are a few places where error behavior is special-case, or there's
+something additional you might need to know.
+
+Errors From Iterating Resultsets
+================================
+
+Consider the following code:
+
+<pre class="prettyprint lang-go">
+for rows.Next() {
+   // ...
+}
+if err = rows.Err(); err != nil {
+   // handle the error here
+}
+</pre>
+
+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.
+
+Errors From QueryRow()
+======================
+
+Consider the following code to fetch a single row:
+
+<pre class="prettyprint lang-go">
+var name string
+err = db.QueryRow("select name from users where id = ?", 1).Scan(&amp;name)
+if err != nil {
+	log.Fatal(err)
+}
+fmt.Println(name)
+</pre>
+
+What if there was no user with `id = 1`? Then there would be no row in the
+result, and `.Scan()` would not scan a value into `name`. What happens then?
+
+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.
+
+Errors from the query are deferred until `Scan()` is called, and then are
+returned from that. The above code is better written like this instead:
+
+<pre class="prettyprint lang-go">
+var name string
+err = db.QueryRow("select name from users where id = ?", 1).Scan(&amp;name)
+if err != nil {
+	if err != sql.ErrNoRows {
+		// there were no rows, but otherwise no error occurred
+	} else {
+		log.Fatal(err)
+	}
+}
+fmt.Println(name)
+</pre>
+
+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.
+
+Identifying Specific Database Errors
+====================================
+
+It can be tempting to write code like the following:
+
+<pre class="prettyprint lang-go">
+rows, err := db.Query("SELECT someval FROM sometable")
+// err contains:
+// ERROR 1045 (28000): Access denied for user 'foo'@'::1' (using password: NO)
+if strings.Contains(err.Error(), "Access denied") {
+	// Handle the permission-denied error
+}
+</pre>
+
+This is not the best way to do it, though. For example, the string value might
+vary depending on what language the server uses to send error messages.  It's
+much better to compare error numbers to identify what a specific error is.
+
+The mechanism to do this varies between drivers, however, because this isn't
+part of `database/sql` itself. In the MySQL driver that this tutorial focuses
+on, you could write the following code:
+
+<pre class="prettyprint lang-go">
+if driverErr, ok := err.(*mysql.MySQLError); ok { // Now the error number is accessible directly
+	if driverErr.Number == 1045 {
+		// Handle the permission-denied error
+	}
+}
+</pre>
+
+Again, the `MySQLError` type here is provided by this specific driver, and the
+`.Number` field may differ between drivers. The value of the number, however,
+is taken from MySQL's error message, and is therefore database specific, not
+driver specific.
+
+This code is still ugly. Comparing to 1045, a magic number, is a code smell.
+Some drivers (though not the MySQL one, for reasons that are off-topic here)
+provide a list of error identifiers. The `libpq` driver does, for example, in
+[error.go](https://github.com/lib/pq/blob/master/error.go). And there's an
+external package of [MySQL error numbers maintained by
+VividCortex](https://github.com/VividCortex/mysqlerr). Using such a list, the
+above code is better written thus:
+
+<pre class="prettyprint lang-go">
+if driverErr, ok := err.(*mysql.MySQLError); ok {
+	if driverErr.Number == mysqlerr.ER_ACCESS_DENIED_ERROR {
+		// Handle the permission-denied error
+	}
+}
+</pre>
+
+**Previous: [Modifying Data and Using Transactions](modifying.html)**
+**Next: [Working with NULLs](nulls.html)**
diff --git a/modifying.md b/modifying.md
index 3a011f9..6fe57d5 100644
--- a/modifying.md
+++ b/modifying.md
@@ -88,4 +88,4 @@ code. Bad things might result:
 * 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.
 
 **Previous: [Retrieving Result Sets](retrieving.html)**
-**Next: [Working with NULLs](nulls.html)**
+**Next: [Handling Errors](errors.html)**
diff --git a/nulls.md b/nulls.md
index fc18831..baba7d9 100644
--- a/nulls.md
+++ b/nulls.md
@@ -37,5 +37,5 @@ you need more convincing:
 If you need to define your own types to handle NULLs, you can copy the design of
 `sql.NullString` to achieve that.
 
-**Previous: [Modifying Data and Using Transactions](modifying.html)**
+**Previous: [Handling Errors](errors.html)**
 **Next: [Working with Unknown Columns](varcols.html)**
diff --git a/retrieving.md b/retrieving.md
index e1d184c..01d3fdd 100644
--- a/retrieving.md
+++ b/retrieving.md
@@ -54,6 +54,11 @@ Here's what's happening in the above code:
 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.
 
+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.
+
 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
@@ -73,17 +78,6 @@ 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
 =================
 
@@ -157,21 +151,5 @@ if err != nil {
 fmt.Println(name)
 </pre>
 
-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.
-
 **Previous: [Accessing the Database](accessing.html)**
 **Next: [Modifying Data and Using Transactions](modifying.html)**

From 50b2d1e8aa2b2213c9066c37756f8dff4672ad71 Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 15:37:10 -0500
Subject: [PATCH 05/47] Reference to transparent encryption blog post

---
 references.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/references.md b/references.md
index 86ca6da..ae4de6e 100644
--- a/references.md
+++ b/references.md
@@ -8,6 +8,7 @@ Here are some external sources of information we've found to be helpful.
 * [http://golang.org/pkg/database/sql/](http://golang.org/pkg/database/sql/)
 * [http://jmoiron.net/blog/gos-database-sql/](http://jmoiron.net/blog/gos-database-sql/)
 * [http://jmoiron.net/blog/built-in-interfaces/](http://jmoiron.net/blog/built-in-interfaces/)
+* The VividCortex blog, e.g. [transparent encryption](https://vividcortex.com/blog/2014/11/11/encrypting-data-in-mysql-with-go/)
 
 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

From aa73780532e7d8441be14e86e5baefaf0ec7eaff Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 15:45:36 -0500
Subject: [PATCH 06/47] note on cxn state; fix #57

---
 connection-pool.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/connection-pool.md b/connection-pool.md
index 3237dd1..ae1dc6f 100644
--- a/connection-pool.md
+++ b/connection-pool.md
@@ -7,6 +7,7 @@ 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:
 
+* Connection pooling means that executing two consecutive statements on a single database might open two connections and execute them separately. It is fairly common for programmers to be confused as to why their code misbehaves. For example, `LOCK TABLES` followed by an `INSERT` can block because the `INSERT` is on a connection that does not hold the table lock.
 * Connections are created when needed and there isn't a free connection in the pool.
 * By default, 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 or newer, you can use `db.SetMaxIdleConns(N)` to limit the number of *idle* connections in the pool. This doesn't limit the pool size, though.

From 5cb5fdcbc87fb2003417322ffeee02caa29e8852 Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 15:47:57 -0500
Subject: [PATCH 07/47] tweak rows.Close() err handling; fix #46

---
 retrieving.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/retrieving.md b/retrieving.md
index 01d3fdd..7245a21 100644
--- a/retrieving.md
+++ b/retrieving.md
@@ -65,9 +65,10 @@ 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
+encounter an internal EOF error and call `rows.Close()` for you. But if for some
+reason you exit that loop -- an early return, or so on -- then the
+`rows` doesn't get closed, and the connection remains open. (It is auto-closed
+if `rows.Next()` returns false due to an error, though). 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

From 36fa3827df663aec4f93cd5e9934bae28e541b3f Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 15:50:21 -0500
Subject: [PATCH 08/47] Upgrade to kramdown; fix #45

---
 config.yml => _config.yml | 1 +
 1 file changed, 1 insertion(+)
 rename config.yml => _config.yml (88%)

diff --git a/config.yml b/_config.yml
similarity index 88%
rename from config.yml
rename to _config.yml
index 3d59ecd..953722e 100644
--- a/config.yml
+++ b/_config.yml
@@ -4,3 +4,4 @@ safe: true
 lsi: false
 pygments: true
 timezone: UTC
+markdown: kramdown

From 5be9c38c715ebb2c40add3a79d802a7c8b53195d Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 16:03:43 -0500
Subject: [PATCH 09/47] Add notes about prep stmt support; fix #41

---
 retrieving.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/retrieving.md b/retrieving.md
index 7245a21..572696f 100644
--- a/retrieving.md
+++ b/retrieving.md
@@ -121,6 +121,31 @@ Go 1.1, but not all drivers are smart enough to do that. Caveat Emptor.
 Naturally prepared statements and the management of prepared statements cost
 resources. You should take care to close statements when they are not used again.
 
+Avoiding Prepared Statements
+============================
+
+Go creates prepared statements for you under the covers. A simple
+`db.Query(sql, param1, param2)`, for example, works by preparing the sql, then
+executing it with the parameters and finally closing the statement.
+
+Sometimes a prepared statement is not what you want, however. There might be
+several reasons for this:
+
+1. The database doesn't support prepared statements. When using the MySQL
+	driver, for example, you can connect to MemSQL and Sphinx, because they
+	support the MySQL wire protocol. But they don't support the "binary" protocol
+	that includes prepared statements, so they can fail in confusing ways.
+2. The statements aren't reused enough to make them worthwhile, and security
+	issues are handled in other ways, so performance overhead is undesired. An
+	example of this can be seen at the
+	[VividCortex blog](https://vividcortex.com/blog/2014/11/19/analyzing-prepared-statement-performance-with-vividcortex/).
+
+If you don't want to use a prepared statement, you need to use `fmt.Sprint()` or
+similar to assemble the SQL, and pass this as the only argument to `db.Query()`
+or `db.QueryRow()`. And your driver needs to support plaintext query execution,
+which is added in Go 1.1 via the `Execer` interface,
+[documented here](http://golang.org/pkg/database/sql/driver/#Execer).
+
 Single-Row Queries
 ==================
 

From 56d6796419efcce327475eef9f568011d1f633de Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 16:28:45 -0500
Subject: [PATCH 10/47] Document type-conversions in Scan(); fix #38

---
 retrieving.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/retrieving.md b/retrieving.md
index 572696f..f01edc9 100644
--- a/retrieving.md
+++ b/retrieving.md
@@ -79,6 +79,27 @@ 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.
 
+How Scan() Works
+================
+
+When you iterate over rows and scan them into destination variables, Go performs data
+type conversions work for you, behind the scenes. It is based on the type of the
+destination variable. Being aware of this can clean up your code and help avoid
+repetitive work.
+
+For example, suppose you select some rows from a table that is defined with
+string columns, such as `VARCHAR(45)` or similar. You happen to know, however,
+that the table always contains numbers. If you pass a pointer to a string, Go
+will copy the bytes into the string. Now you can use `strconv.ParseInt()` or
+similar to convert the value to a number. You'll have to check for errors in the
+SQL operations, as well as errors parsing the integer. This is messy and
+tedious.
+
+Or, you can just pass `Scan()` a pointer to an integer. Go will detect that and
+call `strconv.ParseInt()` for you. If there's an error in conversion, the call
+to `Scan()` will return it. Your code is neater and smaller now. This is the
+recommended way to use `database/sql`.
+
 Preparing Queries
 =================
 

From 65d597b6ca4b0e1f20726377bb275d4c962304a4 Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 16:38:37 -0500
Subject: [PATCH 11/47] Document txn and cxn state; fix #37

---
 modifying.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/modifying.md b/modifying.md
index 6fe57d5..4cff52f 100644
--- a/modifying.md
+++ b/modifying.md
@@ -87,5 +87,21 @@ code. Bad things might result:
 * 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.
 
+While you are working inside a transaction you should be careful not to make
+calls to the `Db` variable. Make all of your calls to the `Tx` variable that you
+created with `db.Begin()`. The `Db` is not in a transaction, only the `Tx` is.
+If you make further calls to `db.Exec()` or similar, those will happen outside
+the scope of your transaction, on other connections.
+
+If you need to work with multiple statements that modify connection state, you
+need a `Tx` even if you don't want a transaction per se. For example:
+
+* Creating temporary tables, which are only visible to one connection.
+* Setting variables, such as MySQL's `SET @var := somevalue` syntax.
+* Changing connection options, such as character sets or timeouts.
+
+If you need to do any of these things, you need to bind your activity to a
+single connection, and the only way to do that in Go is to use a `Tx`.
+
 **Previous: [Retrieving Result Sets](retrieving.html)**
 **Next: [Handling Errors](errors.html)**

From 7b2ee04a3edb0a66c4d4bb86d5a83452191fe3c2 Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 16:46:46 -0500
Subject: [PATCH 12/47] Add leftnav for new Errors page

---
 _layouts/article.html | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/_layouts/article.html b/_layouts/article.html
index c2940a1..e65a5b9 100644
--- a/_layouts/article.html
+++ b/_layouts/article.html
@@ -21,6 +21,9 @@
   -
     title: Modifying Data and Using Transactions
     url: modifying.html
+  -
+    title: Handling Errors
+    url: errors.html
   -
     title: Working with NULLs
     url: nulls.html

From 4b385e734f01ed640010e802fbaaffa34ba70555 Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 16:55:35 -0500
Subject: [PATCH 13/47] Increase sidebar, shorten titles; fix #28

---
 _layouts/article.html | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/_layouts/article.html b/_layouts/article.html
index e65a5b9..d582273 100644
--- a/_layouts/article.html
+++ b/_layouts/article.html
@@ -7,19 +7,19 @@
   url: index.html
   articles:
   -
-    title: Overview of Go's database/sql Package
+    title: Overview
     url: overview.html
   -
-    title: Importing a Database Driver
+    title: Importing a Driver
     url: importing.html
   -
-    title: Accessing the Database
+    title: Accessing a DB
     url: accessing.html
   -
-    title: Retrieving Result Sets
+    title: Getting Results
     url: retrieving.html
   -
-    title: Modifying Data and Using Transactions
+    title: Updates and Transactions
     url: modifying.html
   -
     title: Handling Errors
@@ -28,16 +28,16 @@
     title: Working with NULLs
     url: nulls.html
   -
-    title: Working with Unknown Columns
+    title: Unknown Columns
     url: varcols.html
   -
-    title: The Connection Pool
+    title: Connection Pooling
     url: connection-pool.html
   -
-    title: Surprises, Antipatterns and Limitations
+    title: Surprises and Limitations
     url: surprises.html
   -
-    title: Related Reading and Resources
+    title: Resources
     url: references.html
 ---
 <!DOCTYPE html>
@@ -51,11 +51,11 @@
   <body onload="prettyPrint()">
     <div class="container">
       <div class="row">
-        <div class="span2">
+        <div class="span3">
           {% include leftnav.html %}
         </div>
 
-        <div class="span10">
+        <div class="span9">
           <div class="page-header">
             <h1>{{ page.title }}</h1>
             <a href="https://github.com/VividCortex/go-database-sql-tutorial/edit/gh-pages/{{ page.path }}" class="improve-page btn btn-info" target="_blank">Improve this page</a>

From 72d8e0c97fd864b394e5935d58cefc976d5e3642 Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 17:02:22 -0500
Subject: [PATCH 14/47] Warn about improper defer; fix #26

---
 .gitignore    |  3 +++
 retrieving.md | 39 ++++++++++++++++++++++-----------------
 2 files changed, 25 insertions(+), 17 deletions(-)
 create mode 100644 .gitignore

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..169bb6f
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+.Gemfile.lock
+Gemfile.lock
+_site/
diff --git a/retrieving.md b/retrieving.md
index f01edc9..a9514df 100644
--- a/retrieving.md
+++ b/retrieving.md
@@ -61,23 +61,28 @@ shown.
 
 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 some
-reason you exit that loop -- an early return, or so on -- then the
-`rows` doesn't get closed, and the connection remains open. (It is auto-closed
-if `rows.Next()` returns false due to an error, though). 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.
+* 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.
+* Second, 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 some reason you exit that loop -- an early return, or so on --
+  then the `rows` doesn't get closed, and the connection remains open. (It is
+  auto-closed if `rows.Next()` returns false due to an error, though). This is
+  an easy way to run out of resources.
+* `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
+  call `rows.Close()` if there isn't an error, in order to avoid a runtime panic.
+* You should **always `defer rows.Close()`**, even if you also call `rows.Close()`
+  explicitly at the end of the loop, which isn't a bad idea. 
+* Don't `defer` within a loop. A deferred statement doesn't get executed until
+  the function exits, so a long-running function shouldn't use it. If you do,
+  you will slowly accumulate memory. If you are repeatedly querying and
+  consuming result sets within a loop, you should explicitly call `rows.Close()`
+  when you're done with each result, and not use `defer`.
 
 How Scan() Works
 ================

From 505781b81d4bdcefc6307fe38998f2c7327dbeee Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 17:10:02 -0500
Subject: [PATCH 15/47] Document reconnect/retry; fix #25

---
 errors.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/errors.md b/errors.md
index 37d7eb9..de4b71e 100644
--- a/errors.md
+++ b/errors.md
@@ -129,5 +129,23 @@ if driverErr, ok := err.(*mysql.MySQLError); ok {
 }
 </pre>
 
+Handling Connection Errors
+==========================
+
+What if your connection to the database is dropped, killed, or has an error?
+
+You don't need to implement any logic to retry failed statements when this
+happens. As part of the [connection pooling](connection-pool.html) in
+`database/sql`, handling failed connections is built-in. If you execute a query
+or other statement and the underlying connection has a failure, Go will reopen a
+new connection (or just get another from the connection pool) and retry, up to
+10 times.
+
+There can be some unintended consequences, however. Some types of errors may be
+retried when other error conditions happen. This might also be driver-specific.
+One example that has occurred with the MySQL driver is that using `KILL` to
+cancel an undesired statement (such as a long-running query) results in the
+statement being retried up to 10 times.
+
 **Previous: [Modifying Data and Using Transactions](modifying.html)**
 **Next: [Working with NULLs](nulls.html)**

From 3bdc8afaa5d146ff5b347b81b151b3dd0e681114 Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Fri, 5 Dec 2014 21:15:47 -0500
Subject: [PATCH 16/47] Rearrange prep stmts; fix #22

---
 _layouts/article.html |   3 +
 errors.md             |   2 +-
 modifying.md          |   8 +--
 prepared.md           | 132 ++++++++++++++++++++++++++++++++++++++++++
 retrieving.md         |  32 +---------
 surprises.md          |  74 +++++++++--------------
 6 files changed, 167 insertions(+), 84 deletions(-)
 create mode 100644 prepared.md

diff --git a/_layouts/article.html b/_layouts/article.html
index d582273..e80f700 100644
--- a/_layouts/article.html
+++ b/_layouts/article.html
@@ -21,6 +21,9 @@
   -
     title: Updates and Transactions
     url: modifying.html
+  -
+    title: Prepared Statements
+    url: prepared.html
   -
     title: Handling Errors
     url: errors.html
diff --git a/errors.md b/errors.md
index de4b71e..6039f7d 100644
--- a/errors.md
+++ b/errors.md
@@ -147,5 +147,5 @@ One example that has occurred with the MySQL driver is that using `KILL` to
 cancel an undesired statement (such as a long-running query) results in the
 statement being retried up to 10 times.
 
-**Previous: [Modifying Data and Using Transactions](modifying.html)**
+**Previous: [Using Prepared Statements](prepared.html)**
 **Next: [Working with NULLs](nulls.html)**
diff --git a/modifying.md b/modifying.md
index 4cff52f..074188a 100644
--- a/modifying.md
+++ b/modifying.md
@@ -73,11 +73,7 @@ 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. To 
-use a prepared statement prepared outside the transaction, use `Tx.Stmt()`,
-which will create a new transaction-specific statement from the one prepared
-outside the transaction.
+that transaction. See [prepared statements](prepared.html) for more.
 
 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
@@ -104,4 +100,4 @@ If you need to do any of these things, you need to bind your activity to a
 single connection, and the only way to do that in Go is to use a `Tx`.
 
 **Previous: [Retrieving Result Sets](retrieving.html)**
-**Next: [Handling Errors](errors.html)**
+**Next: [Using Prepared Statements](prepared.html)**
diff --git a/prepared.md b/prepared.md
new file mode 100644
index 0000000..9b1a154
--- /dev/null
+++ b/prepared.md
@@ -0,0 +1,132 @@
+---
+layout: article
+title: Using Prepared Statements
+---
+
+Prepared statements have all the usual benefits in Go: security, efficiency,
+convenience. But the way they're implemented is a little different from what
+you might be used to, especially with regards to how they interact with some of
+the internals of `database/sql`.
+
+Prepared Statements And Connections
+===================================
+
+At the database level, a prepared statement is bound to a single database
+connection. The typical flow is that the client sends a SQL statement with
+placeholders to the server for preparation, the server responds with a statement
+ID, and then the client executes the statement by sending its ID and paraemters.
+
+In Go, however, connections are not exposed directly to the user of the
+`database/sql` package. You don't prepare a statement on a connection. You
+prepare it on a `DB` or a `Tx`. And `database/sql` has some convenience
+behaviors such as automatic retries. For these reasons, the underlying
+association between prepared statements and connections, which exists at the
+driver level, is hidden from your code.
+
+Here's how it works:
+
+1. When you prepare a statement, it's prepared on a connection in the pool.
+2. The `Stmt` object remembers which connection was used.
+3. When you execute the `Stmt`, it tries to use the connection. If it's not
+	available because it's closed or busy doing something else, it gets another
+	connection from the pool *and re-prepares the statement with the database on
+	another connection.*
+
+Because statements will be re-prepared as needed when their original connection
+is busy, it's possible for high-concurrency usage of the database, which may
+keep a lot of connections busy, to create a large number of prepared statements.
+This can result in apparent leaks of statements, statements being prepared and
+re-prepared more often than you think, and even running into server-side limits
+on the number of statements.
+
+Avoiding Prepared Statements
+============================
+
+Go creates prepared statements for you under the covers. A simple
+`db.Query(sql, param1, param2)`, for example, works by preparing the sql, then
+executing it with the parameters and finally closing the statement.
+
+Sometimes a prepared statement is not what you want, however. There might be
+several reasons for this:
+
+1. The database doesn't support prepared statements. When using the MySQL
+	driver, for example, you can connect to MemSQL and Sphinx, because they
+	support the MySQL wire protocol. But they don't support the "binary" protocol
+	that includes prepared statements, so they can fail in confusing ways.
+2. The statements aren't reused enough to make them worthwhile, and security
+	issues are handled in other ways, so performance overhead is undesired. An
+	example of this can be seen at the
+	[VividCortex blog](https://vividcortex.com/blog/2014/11/19/analyzing-prepared-statement-performance-with-vividcortex/).
+
+If you don't want to use a prepared statement, you need to use `fmt.Sprint()` or
+similar to assemble the SQL, and pass this as the only argument to `db.Query()`
+or `db.QueryRow()`. And your driver needs to support plaintext query execution,
+which is added in Go 1.1 via the `Execer` interface,
+[documented here](http://golang.org/pkg/database/sql/driver/#Execer).
+
+Prepared Statements in Transactions
+===================================
+
+Prepared statements that are created in a `Tx` are bound exclusively to
+it, so the earlier cautions about repreparing do not apply. When
+you operate on a `Tx` object, your actions map directly to the one and only one
+connection underlying it.
+
+This also means that prepared statements created inside a `Tx` can't be used
+separately from it. Likewise, prepared statements created on a `DB` can't be
+used within a transaction, because they will be bound to a different connection.
+To use a prepared statement prepared outside the transaction in a `Tx`, use
+`Tx.Stmt()`, which will create a new transaction-specific statement from the one
+prepared outside the transaction.
+
+Caution must be exercised when working with prepared statements in
+transactions. Consider the following example:
+
+<pre class="prettyprint lang-go">
+tx, err := db.Begin()
+if err != nil {
+	log.Fatal(err)
+}
+defer tx.Rollback()
+stmt, err := tx.Prepare("INSERT INTO foo VALUES (?)")
+if err != nil {
+	log.Fatal(err)
+}
+defer stmt.Close() // danger!
+for i := 0; i < 10; i++ {
+	_, err = stmt.Exec(i)
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+err = tx.Commit()
+if err != nil {
+	log.Fatal(err)
+}
+// stmt.Close() runs here!
+</pre>
+
+Closing a `*sql.Tx` releases the connection associated with it back into the
+pool, but the deferred call to Close on the prepared statement is executed
+**after** that has happened, which could lead to concurrent access to the
+underlying connection, rendering the connection state inconsistent.
+`database/sql` does not guard you against this particular behaviour.  Instead,
+you should make sure the statement is always closed before the transaction is
+committed or rolled back.
+
+This is a [known issue](https://code.google.com/p/go/issues/detail?id=4459) that
+will probably be fixed in Go 1.4 by [CR 131650043](https://codereview.appspot.com/131650043).
+
+Parameter Placeholder Syntax
+============================
+
+The syntax for placeholder parameters in prepared statements is
+database-specific. For example, comparing MySQL, PostgreSQL, and Oracle:
+
+	MySQL               PostgreSQL            Oracle
+	=====               ==========            ======
+	WHERE col = ?       WHERE col = $1        WHERE col = :col
+	VALUES(?, ?, ?)     VALUES($1, $2, $3)    VALUES(:val1, :val2, :val3)
+
+**Previous: [Modifying Data and Using Transactions](modifying.html)**
+**Next: [Handling Errors](errors.html)**
diff --git a/retrieving.md b/retrieving.md
index a9514df..85e14c2 100644
--- a/retrieving.md
+++ b/retrieving.md
@@ -141,36 +141,8 @@ if err = rows.Err(); err != nil {
 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.
-
-Naturally prepared statements and the management of prepared statements cost
-resources. You should take care to close statements when they are not used again.
-
-Avoiding Prepared Statements
-============================
-
-Go creates prepared statements for you under the covers. A simple
-`db.Query(sql, param1, param2)`, for example, works by preparing the sql, then
-executing it with the parameters and finally closing the statement.
-
-Sometimes a prepared statement is not what you want, however. There might be
-several reasons for this:
-
-1. The database doesn't support prepared statements. When using the MySQL
-	driver, for example, you can connect to MemSQL and Sphinx, because they
-	support the MySQL wire protocol. But they don't support the "binary" protocol
-	that includes prepared statements, so they can fail in confusing ways.
-2. The statements aren't reused enough to make them worthwhile, and security
-	issues are handled in other ways, so performance overhead is undesired. An
-	example of this can be seen at the
-	[VividCortex blog](https://vividcortex.com/blog/2014/11/19/analyzing-prepared-statement-performance-with-vividcortex/).
-
-If you don't want to use a prepared statement, you need to use `fmt.Sprint()` or
-similar to assemble the SQL, and pass this as the only argument to `db.Query()`
-or `db.QueryRow()`. And your driver needs to support plaintext query execution,
-which is added in Go 1.1 via the `Execer` interface,
-[documented here](http://golang.org/pkg/database/sql/driver/#Execer).
+drivers can avoid this in specific cases,
+but not all drivers do. See [prepared statements](prepared.html) for more.
 
 Single-Row Queries
 ==================
diff --git a/surprises.md b/surprises.md
index e332302..57be48e 100644
--- a/surprises.md
+++ b/surprises.md
@@ -17,7 +17,7 @@ resources or preventing them from being reused effectively:
 * Opening and closing databases can cause exhaustion of resources.
 * Failing to read all rows or use `rows.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.
+* Failing to be aware of how [prepared statements](prepared.html) work can lead to a lot of extra database activity.
 
 Large uint64 Values
 ===================
@@ -59,14 +59,8 @@ Database-Specific Syntax
 ========================
 
 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:
-
-	MySQL               PostgreSQL            Oracle
-	=====               ==========            ======
-	WHERE col = ?       WHERE col = $1        WHERE col = :col
-	VALUES(?, ?, ?)     VALUES($1, $2, $3)    VALUES(:val1, :val2, :val3)
+specific databases and drivers can differ in behavior and/or syntax, such as
+[prepared statement placeholders](prepared.html).
 
 Multiple Result Sets
 ====================
@@ -113,52 +107,38 @@ returning an error, executing only the first statement, or executing both.
 Similarly, there is no way to batch statements in a transaction. Each statement
 in a transaction must be executed serially, and the resources in the results,
 such as a Row or Rows, must be scanned or closed so the underlying connection is free
-for the next statement to use.  Since transactions are connection state and bind
-to a single database connection, you may wind up with a corrupted connection if
-you attempt to perform another statement before the first has released that resource
-and cleaned up after itself.  This also means that each statement in a transaction
-results in a separate set of network round-trips to the database.
+for the next statement to use. This differs from the usual behavior when you're
+not working with a transaction. In that scenario, it is perfectly possible to
+execute a query, loop over the rows, and within the loop make a query to the
+database (which will happen on a new connection):
 
-Prepared Statements in Transactions
-===================================
+<pre class="prettyprint lang-go">
+rows, err := db.Query("select * from tbl1") // Uses connection 1
+for rows.Next() {
+	err = rows.Scan(&myvariable)
+	// The following line will NOT use connection 1, which is already in-use
+   db.Query("select * from tbl2 where id = ?", myvariable)
+}
+</pre>
 
-Caution must be exercised when working with prepared statements in
-transactions. Consider the following example:
+But transactions are bound to
+just one connection, so this isn't possible with a transaction:
 
 <pre class="prettyprint lang-go">
 tx, err := db.Begin()
-if err != nil {
-	log.Fatal(err)
+rows, err := tx.Query("select * from tbl1") // Uses tx's connection
+for rows.Next() {
+	err = rows.Scan(&myvariable)
+	// ERROR! tx's connection is already busy!
+   tx.Query("select * from tbl2 where id = ?", myvariable)
 }
-defer tx.Rollback()
-stmt, err := tx.Prepare("INSERT INTO foo VALUES (?)")
-if err != nil {
-	log.Fatal(err)
-}
-defer stmt.Close() // danger!
-for i := 0; i < 10; i++ {
-	_, err = stmt.Exec(i)
-	if err != nil {
-		log.Fatal(err)
-	}
-}
-err = tx.Commit()
-if err != nil {
-	log.Fatal(err)
-}
-// stmt.Close() runs here!
 </pre>
 
-Closing a `*sql.Tx` releases the connection associated with it back into the
-pool, but the deferred call to Close on the prepared statement is executed
-**after** that has happened, which could lead to concurrent access to the
-underlying connection, rendering the connection state inconsistent.
-`database/sql` does not guard you against this particular behaviour.  Instead,
-you should make sure the statement is always closed before the transaction is
-committed or rolled back.
-
-This is a [known issue](https://code.google.com/p/go/issues/detail?id=4459) that
-will probably be fixed in Go 1.4 by [CR 131650043](https://codereview.appspot.com/131650043).
+Go doesn't stop you from trying, though. For that reason, you may wind up with a
+corrupted connection if you attempt to perform another statement before the
+first has released its resources and cleaned up after itself.  This also means
+that each statement in a transaction results in a separate set of network
+round-trips to the database.
 
 **Previous: [The Connection Pool](connection-pool.html)**
 **Next: [Related Reading and Resources](references.html)**

From 0c88bfa826c53650ade17db6df0b7579feaf25bf Mon Sep 17 00:00:00 2001
From: Baron Schwartz <xaprb@users.noreply.github.com>
Date: Sat, 6 Dec 2014 20:22:19 -0500
Subject: [PATCH 17/47] Addressing @arnehormann's comments in #59

---
 prepared.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/prepared.md b/prepared.md
index 9b1a154..51ca686 100644
--- a/prepared.md
+++ b/prepared.md
@@ -61,7 +61,7 @@ several reasons for this:
 If you don't want to use a prepared statement, you need to use `fmt.Sprint()` or
 similar to assemble the SQL, and pass this as the only argument to `db.Query()`
 or `db.QueryRow()`. And your driver needs to support plaintext query execution,
-which is added in Go 1.1 via the `Execer` interface,
+which is added in Go 1.1 via the `Execer` and `Queryer` interfaces,
 [documented here](http://golang.org/pkg/database/sql/driver/#Execer).
 
 Prepared Statements in Transactions
@@ -75,9 +75,13 @@ connection underlying it.
 This also means that prepared statements created inside a `Tx` can't be used
 separately from it. Likewise, prepared statements created on a `DB` can't be
 used within a transaction, because they will be bound to a different connection.
-To use a prepared statement prepared outside the transaction in a `Tx`, use
+
+To use a prepared statement prepared outside the transaction in a `Tx`, you can use
 `Tx.Stmt()`, which will create a new transaction-specific statement from the one
-prepared outside the transaction.
+prepared outside the transaction. It does this by taking an existing prepared statement,
+setting the connection to that of the transaction and repreparing all statements every
+time they are executed. This behavior and its implementation are undesirable and there's
+even a TODO in the `database/sql` source code to improve it; we advise against using this.
 
 Caution must be exercised when working with prepared statements in
 transactions. Consider the following example:

From 9a0750e2cf0171e07fe9aab64e65cb33ee64c070 Mon Sep 17 00:00:00 2001
From: Benny Ng <benny.tpng@gmail.com>
Date: Tue, 9 Dec 2014 17:50:46 +0800
Subject: [PATCH 18/47] fix comparison to sql.ErrNoRows

---
 errors.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/errors.md b/errors.md
index 6039f7d..7bccac3 100644
--- a/errors.md
+++ b/errors.md
@@ -59,7 +59,7 @@ returned from that. The above code is better written like this instead:
 var name string
 err = db.QueryRow("select name from users where id = ?", 1).Scan(&amp;name)
 if err != nil {
-	if err != sql.ErrNoRows {
+	if err == sql.ErrNoRows {
 		// there were no rows, but otherwise no error occurred
 	} else {
 		log.Fatal(err)

From 534c65bc20575f1e447d03ffd1e7d5af22821dda Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Tue, 16 Dec 2014 09:09:46 -0500
Subject: [PATCH 19/47] Separate Close and Err docs for #62

---
 errors.md | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/errors.md b/errors.md
index 7bccac3..2986f07 100644
--- a/errors.md
+++ b/errors.md
@@ -16,16 +16,43 @@ Consider the following code:
 
 <pre class="prettyprint lang-go">
 for rows.Next() {
-   // ...
+	// ...
 }
 if err = rows.Err(); err != nil {
-   // handle the error here
+	// handle the error here
+}
+</pre>
+
+The error from `rows.Err()` could be the result of a variety of errors in the
+`rows.Next()` loop. The most important thing is to be aware that this `for` loop
+might exit for some reason other than finishing the loop normally, so you always
+need to check whether the loop terminated normally or not. An abnormal
+termination automatically calls `rows.Close()`, although it's harmless to call it
+multiple times.
+
+Errors From Closing Resultsets
+==============================
+
+You should always explicitly close a `sql.Rows` if you exit the loop
+prematurely, as previously mentioned. It's auto-closed if the loop exits
+normally or through an error, but you might mistakenly do this:
+
+<pre class="prettyprint lang-go">
+for rows.Next() {
+	// ...
+	break; // whoops, rows is not closed! memory leak...
+}
+// do the usual "if err = rows.Err()" [omitted here]...
+// it's always safe to [re?]close here:
+if err = rows.Close(); err != nil {
+	// but what should we do if there's an error?
+	log.Println(err)
 }
 </pre>
 
 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.
+`rows.Close()` returns 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.
 

From 5797134ad707ba0ae09c23abf3490b3a8dd97e25 Mon Sep 17 00:00:00 2001
From: Baron Schwartz <baron@xaprb.com>
Date: Tue, 16 Dec 2014 13:06:06 -0500
Subject: [PATCH 20/47] Fix some small tweaks Arne suggested

---
 errors.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/errors.md b/errors.md
index 2986f07..a78d30d 100644
--- a/errors.md
+++ b/errors.md
@@ -24,7 +24,7 @@ if err = rows.Err(); err != nil {
 </pre>
 
 The error from `rows.Err()` could be the result of a variety of errors in the
-`rows.Next()` loop. The most important thing is to be aware that this `for` loop
+`rows.Next()` loop. The loop
 might exit for some reason other than finishing the loop normally, so you always
 need to check whether the loop terminated normally or not. An abnormal
 termination automatically calls `rows.Close()`, although it's harmless to call it
@@ -52,8 +52,8 @@ if err = rows.Close(); err != nil {
 
 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()` returns 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,
+`rows.Close()` returns an error, it's unclear what you should do.
+Logging the error message or panicing might be the only sensible thing,
 and if that's not sensible, then perhaps you should just ignore the error.
 
 Errors From QueryRow()

From ce1d9dabfd6e592002c2fe52b5fb0c16f2f0ca7b Mon Sep 17 00:00:00 2001
From: jeteon <jeteon@users.noreply.github.com>
Date: Fri, 2 Jan 2015 14:01:55 +0200
Subject: [PATCH 21/47] Spelling fix of paraemters

---
 prepared.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/prepared.md b/prepared.md
index 51ca686..957e73d 100644
--- a/prepared.md
+++ b/prepared.md
@@ -14,7 +14,7 @@ Prepared Statements And Connections
 At the database level, a prepared statement is bound to a single database
 connection. The typical flow is that the client sends a SQL statement with
 placeholders to the server for preparation, the server responds with a statement
-ID, and then the client executes the statement by sending its ID and paraemters.
+ID, and then the client executes the statement by sending its ID and parameters.
 
 In Go, however, connections are not exposed directly to the user of the
 `database/sql` package. You don't prepare a statement on a connection. You

From c9c6f6af5c3febeb654ca77b7a63ec0cdf61b776 Mon Sep 17 00:00:00 2001
From: perceptec <perceptec@gmail.com>
Date: Thu, 26 Feb 2015 20:14:20 -0500
Subject: [PATCH 22/47] Add warning comments to erroneous examples

It isn't imperative, but the failing code examples might be improved with comments for the attention-challenged.
---
 surprises.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/surprises.md b/surprises.md
index 57be48e..2bd2de0 100644
--- a/surprises.md
+++ b/surprises.md
@@ -26,7 +26,7 @@ Here's a surprising error. You can't pass big unsigned integers as parameters to
 statements if their high bit is set:
 
 <pre class="prettyprint lang-go">
-_, err := db.Exec("INSERT INTO users(id) VALUES", math.MaxUint64)
+_, err := db.Exec("INSERT INTO users(id) VALUES", math.MaxUint64) // Error
 </pre>
 
 This will throw an error. Be careful if you use `uint64` values, as they may
@@ -81,7 +81,7 @@ be done at present. It might seem that you'd be able to call a simple
 procedure that returns a single result set, by executing something like this:
 
 <pre class="prettyprint lang-go">
-err := db.QueryRow("CALL mydb.myprocedure").Scan(&amp;result)
+err := db.QueryRow("CALL mydb.myprocedure").Scan(&amp;result) // Error
 </pre>
 
 In fact, this won't work. You'll get the following error: _Error
@@ -98,7 +98,7 @@ The `database/sql` doesn't explicitly have multiple statement support, which mea
 that the behavior of this is backend dependent:
 
 <pre class="prettyprint lang-go">
-_, err := db.Exec("DELETE FROM tbl1; DELETE FROM tbl2")
+_, err := db.Exec("DELETE FROM tbl1; DELETE FROM tbl2") // Error/unpredictable result
 </pre>
 
 The server is allowed to interpret this however it wants, which can include

From 54f979e90d9cdd11fa01eb0026c47257bb59d061 Mon Sep 17 00:00:00 2001
From: s7v7nislands <s7v7nislands@gmail.com>
Date: Mon, 23 Mar 2015 17:43:21 +0800
Subject: [PATCH 23/47] fix url

the golang issue is moved to github
---
 prepared.md  | 2 +-
 surprises.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/prepared.md b/prepared.md
index 957e73d..f247c7e 100644
--- a/prepared.md
+++ b/prepared.md
@@ -118,7 +118,7 @@ underlying connection, rendering the connection state inconsistent.
 you should make sure the statement is always closed before the transaction is
 committed or rolled back.
 
-This is a [known issue](https://code.google.com/p/go/issues/detail?id=4459) that
+This is a [known issue](https://github.com/golang/go/issues/4459) that
 will probably be fixed in Go 1.4 by [CR 131650043](https://codereview.appspot.com/131650043).
 
 Parameter Placeholder Syntax
diff --git a/surprises.md b/surprises.md
index 2bd2de0..8f51f91 100644
--- a/surprises.md
+++ b/surprises.md
@@ -67,7 +67,7 @@ Multiple Result Sets
 
 The Go driver doesn't support multiple result sets from a single query in any
 way, and there doesn't seem to be any plan to do that, although there is [a
-feature request](https://code.google.com/p/go/issues/detail?id=5171) for
+feature request](https://github.com/golang/go/issues/5171) for
 supporting bulk operations such as bulk copy.
 
 This means, among other things, that a stored procedure that returns multiple

From a2c4d3589a182befc5d4bd4486a201a823ca1d13 Mon Sep 17 00:00:00 2001
From: Maciek Sakrejda <m.sakrejda@gmail.com>
Date: Thu, 3 Sep 2015 14:55:05 -0700
Subject: [PATCH 24/47] Correct name of Postgres driver in example

This page lists the Postgres driver as `libpq`, which is incorrect. The driver is just called `pq`. `libpq` is the Postgres C client library that one can link against to build a driver, but `pq` does not use it--it is a native Go implementation.
---
 errors.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/errors.md b/errors.md
index a78d30d..aae8d84 100644
--- a/errors.md
+++ b/errors.md
@@ -142,7 +142,7 @@ driver specific.
 
 This code is still ugly. Comparing to 1045, a magic number, is a code smell.
 Some drivers (though not the MySQL one, for reasons that are off-topic here)
-provide a list of error identifiers. The `libpq` driver does, for example, in
+provide a list of error identifiers. The Postgres `pq` driver does, for example, in
 [error.go](https://github.com/lib/pq/blob/master/error.go). And there's an
 external package of [MySQL error numbers maintained by
 VividCortex](https://github.com/VividCortex/mysqlerr). Using such a list, the

From 29e71f2dab02beee956ac805128f42778be66738 Mon Sep 17 00:00:00 2001
From: Julien Schmidt <julienschmidt@users.noreply.github.com>
Date: Fri, 4 Sep 2015 00:25:18 +0200
Subject: [PATCH 25/47] CR 131650043 was merged in Go 1.4

---
 prepared.md | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/prepared.md b/prepared.md
index f247c7e..e382940 100644
--- a/prepared.md
+++ b/prepared.md
@@ -110,16 +110,13 @@ if err != nil {
 // stmt.Close() runs here!
 </pre>
 
-Closing a `*sql.Tx` releases the connection associated with it back into the
-pool, but the deferred call to Close on the prepared statement is executed
+
+Before Go 1.4 closing a `*sql.Tx` released the connection associated with it back into the
+pool, but the deferred call to Close on the prepared statement was executed
 **after** that has happened, which could lead to concurrent access to the
 underlying connection, rendering the connection state inconsistent.
-`database/sql` does not guard you against this particular behaviour.  Instead,
-you should make sure the statement is always closed before the transaction is
-committed or rolled back.
-
-This is a [known issue](https://github.com/golang/go/issues/4459) that
-will probably be fixed in Go 1.4 by [CR 131650043](https://codereview.appspot.com/131650043).
+If you use Go 1.4 or older, you should make sure the statement is always closed before the transaction is
+committed or rolled back. [This issue](https://github.com/golang/go/issues/4459) was fixed in Go 1.4 by [CR 131650043](https://codereview.appspot.com/131650043).
 
 Parameter Placeholder Syntax
 ============================

From 28a4c66bae8d6add3948ba56bc3315171b37df8f Mon Sep 17 00:00:00 2001
From: AMK <amkguo@gmail.com>
Date: Tue, 6 Oct 2015 11:52:40 -0700
Subject: [PATCH 26/47] Provide the driver names for SQLite and PostgreSQL

To be in consistent with http://go-database-sql.org/retrieving.html which shows the placeholders used by MySQL, SQLite and PostgreSQL.
---
 accessing.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/accessing.md b/accessing.md
index 14bfe87..ab046ab 100644
--- a/accessing.md
+++ b/accessing.md
@@ -21,7 +21,7 @@ func main() {
 
 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.
+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. It's `mysql` for [MySQL Server](github.com/go-sql-driver/mysql). Or `sqlite3` if you use [SQLite database engine](https://github.com/mattn/go-sqlite3), `postgres` for [PostgreSQL server](https://github.com/lib/pq).
 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.  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.

From 8169016511571ac52546d66adb002d1c6cb35657 Mon Sep 17 00:00:00 2001
From: AMK <amkguo@gmail.com>
Date: Thu, 8 Oct 2015 10:18:38 -0700
Subject: [PATCH 27/47] Update the link and wording

---
 accessing.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/accessing.md b/accessing.md
index ab046ab..45ee2c9 100644
--- a/accessing.md
+++ b/accessing.md
@@ -21,7 +21,7 @@ func main() {
 
 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. It's `mysql` for [MySQL Server](github.com/go-sql-driver/mysql). Or `sqlite3` if you use [SQLite database engine](https://github.com/mattn/go-sqlite3), `postgres` for [PostgreSQL server](https://github.com/lib/pq).
+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. It's `mysql` for MySQL database driver \[[github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)\]. Or `sqlite3` if you use SQLite database driver \[[github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)\], `postgres` for PostgreSQL database driver \[[github.com/lib/pq](https://github.com/lib/pq)\].
 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.  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.

From 58e3b2824455c6841077e6f8ea0ce6bf37e804a0 Mon Sep 17 00:00:00 2001
From: Preetam Jinka <pj@preet.am>
Date: Fri, 9 Oct 2015 16:33:48 -0400
Subject: [PATCH 28/47] Fix wording in accessing.md

---
 accessing.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/accessing.md b/accessing.md
index 45ee2c9..1ce765e 100644
--- a/accessing.md
+++ b/accessing.md
@@ -21,7 +21,7 @@ func main() {
 
 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. It's `mysql` for MySQL database driver \[[github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)\]. Or `sqlite3` if you use SQLite database driver \[[github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)\], `postgres` for PostgreSQL database driver \[[github.com/lib/pq](https://github.com/lib/pq)\].
+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. For example, it's `mysql` for [github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql). Some drivers do not follow the convention and use the database name, e.g. `sqlite3` for [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) and `postgres` for [github.com/lib/pq](https://github.com/lib/pq).
 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.  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.

From f86dfff35bd5a9d4ce2d7c4cdff49f2e509ceea2 Mon Sep 17 00:00:00 2001
From: Ches Martin <ches@whiskeyandgrits.net>
Date: Fri, 13 Nov 2015 21:18:39 +0700
Subject: [PATCH 29/47] Fix mixed spaces and tabs in Surprises code samples

---
 surprises.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/surprises.md b/surprises.md
index 8f51f91..359cbe4 100644
--- a/surprises.md
+++ b/surprises.md
@@ -117,7 +117,7 @@ rows, err := db.Query("select * from tbl1") // Uses connection 1
 for rows.Next() {
 	err = rows.Scan(&myvariable)
 	// The following line will NOT use connection 1, which is already in-use
-   db.Query("select * from tbl2 where id = ?", myvariable)
+	db.Query("select * from tbl2 where id = ?", myvariable)
 }
 </pre>
 
@@ -130,7 +130,7 @@ rows, err := tx.Query("select * from tbl1") // Uses tx's connection
 for rows.Next() {
 	err = rows.Scan(&myvariable)
 	// ERROR! tx's connection is already busy!
-   tx.Query("select * from tbl2 where id = ?", myvariable)
+	tx.Query("select * from tbl2 where id = ?", myvariable)
 }
 </pre>
 

From 33d00c71814b305c912cfe9fdf35b05964536cfc Mon Sep 17 00:00:00 2001
From: Mark van der Velden <markvdv@gmail.com>
Date: Mon, 23 Nov 2015 12:54:33 +0100
Subject: [PATCH 30/47] Added an alternative approach by suggesting COALESCE()

---
 nulls.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/nulls.md b/nulls.md
index baba7d9..274b450 100644
--- a/nulls.md
+++ b/nulls.md
@@ -37,5 +37,22 @@ you need more convincing:
 If you need to define your own types to handle NULLs, you can copy the design of
 `sql.NullString` to achieve that.
 
+If you can't avoid having NULL values in your database, there is another work around that most database systems support, namely `COALESCE()`. Something like the following might be something that you can use, without introducing a myriad of `sql.Null*` types.
+<pre class="prettyprint lang-go">
+rows, err := db.Query(`
+	SELECT
+		name,
+		COALESCE(other_field, '') as other_field
+	WHERE id = ?
+`, 42)
+
+for rows.Next() {
+	err := rows.Scan(&name, &otherField)
+	// ..
+	// If `other_field` was NULL, `otherField` is now an empty string. This works with other data types as well.
+}
+</pre>
+
+
 **Previous: [Handling Errors](errors.html)**
 **Next: [Working with Unknown Columns](varcols.html)**

From 66c7eea0568d7386a07b4be18e817f9d2c422757 Mon Sep 17 00:00:00 2001
From: Justin <kurtz.justin@gmail.com>
Date: Wed, 16 Mar 2016 11:43:54 -0600
Subject: [PATCH 31/47] Fix double negative

---
 errors.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/errors.md b/errors.md
index aae8d84..1c07326 100644
--- a/errors.md
+++ b/errors.md
@@ -102,7 +102,7 @@ to use this special-case in order to let the caller distinguish whether
 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
+You should only run into this error when you're using `QueryRow()`. If you
 encounter this error elsewhere, you're doing something wrong.
 
 Identifying Specific Database Errors

From b0f1026c481ad7e7ea230ab086ad9febbbbeb8af Mon Sep 17 00:00:00 2001
From: Preetam Jinka <preetam@vividcortex.com>
Date: Wed, 16 Mar 2016 14:44:13 -0400
Subject: [PATCH 32/47] Add CC license; #78

---
 LICENSE | 427 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 427 insertions(+)
 create mode 100644 LICENSE

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..2e72ca1
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,427 @@
+Attribution-ShareAlike 4.0 International
+
+=======================================================================
+
+Creative Commons Corporation ("Creative Commons") is not a law firm and
+does not provide legal services or legal advice. Distribution of
+Creative Commons public licenses does not create a lawyer-client or
+other relationship. Creative Commons makes its licenses and related
+information available on an "as-is" basis. Creative Commons gives no
+warranties regarding its licenses, any material licensed under their
+terms and conditions, or any related information. Creative Commons
+disclaims all liability for damages resulting from their use to the
+fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and
+conditions that creators and other rights holders may use to share
+original works of authorship and other material subject to copyright
+and certain other rights specified in the public license below. The
+following considerations are for informational purposes only, are not
+exhaustive, and do not form part of our licenses.
+
+     Considerations for licensors: Our public licenses are
+     intended for use by those authorized to give the public
+     permission to use material in ways otherwise restricted by
+     copyright and certain other rights. Our licenses are
+     irrevocable. Licensors should read and understand the terms
+     and conditions of the license they choose before applying it.
+     Licensors should also secure all rights necessary before
+     applying our licenses so that the public can reuse the
+     material as expected. Licensors should clearly mark any
+     material not subject to the license. This includes other CC-
+     licensed material, or material used under an exception or
+     limitation to copyright. More considerations for licensors:
+	wiki.creativecommons.org/Considerations_for_licensors
+
+     Considerations for the public: By using one of our public
+     licenses, a licensor grants the public permission to use the
+     licensed material under specified terms and conditions. If
+     the licensor's permission is not necessary for any reason--for
+     example, because of any applicable exception or limitation to
+     copyright--then that use is not regulated by the license. Our
+     licenses grant only permissions under copyright and certain
+     other rights that a licensor has authority to grant. Use of
+     the licensed material may still be restricted for other
+     reasons, including because others have copyright or other
+     rights in the material. A licensor may make special requests,
+     such as asking that all changes be marked or described.
+     Although not required by our licenses, you are encouraged to
+     respect those requests where reasonable. More_considerations
+     for the public: 
+	wiki.creativecommons.org/Considerations_for_licensees
+
+=======================================================================
+
+Creative Commons Attribution-ShareAlike 4.0 International Public
+License
+
+By exercising the Licensed Rights (defined below), You accept and agree
+to be bound by the terms and conditions of this Creative Commons
+Attribution-ShareAlike 4.0 International Public License ("Public
+License"). To the extent this Public License may be interpreted as a
+contract, You are granted the Licensed Rights in consideration of Your
+acceptance of these terms and conditions, and the Licensor grants You
+such rights in consideration of benefits the Licensor receives from
+making the Licensed Material available under these terms and
+conditions.
+
+
+Section 1 -- Definitions.
+
+  a. Adapted Material means material subject to Copyright and Similar
+     Rights that is derived from or based upon the Licensed Material
+     and in which the Licensed Material is translated, altered,
+     arranged, transformed, or otherwise modified in a manner requiring
+     permission under the Copyright and Similar Rights held by the
+     Licensor. For purposes of this Public License, where the Licensed
+     Material is a musical work, performance, or sound recording,
+     Adapted Material is always produced where the Licensed Material is
+     synched in timed relation with a moving image.
+
+  b. Adapter's License means the license You apply to Your Copyright
+     and Similar Rights in Your contributions to Adapted Material in
+     accordance with the terms and conditions of this Public License.
+
+  c. BY-SA Compatible License means a license listed at
+     creativecommons.org/compatiblelicenses, approved by Creative
+     Commons as essentially the equivalent of this Public License.
+
+  d. Copyright and Similar Rights means copyright and/or similar rights
+     closely related to copyright including, without limitation,
+     performance, broadcast, sound recording, and Sui Generis Database
+     Rights, without regard to how the rights are labeled or
+     categorized. For purposes of this Public License, the rights
+     specified in Section 2(b)(1)-(2) are not Copyright and Similar
+     Rights.
+
+  e. Effective Technological Measures means those measures that, in the
+     absence of proper authority, may not be circumvented under laws
+     fulfilling obligations under Article 11 of the WIPO Copyright
+     Treaty adopted on December 20, 1996, and/or similar international
+     agreements.
+
+  f. Exceptions and Limitations means fair use, fair dealing, and/or
+     any other exception or limitation to Copyright and Similar Rights
+     that applies to Your use of the Licensed Material.
+
+  g. License Elements means the license attributes listed in the name
+     of a Creative Commons Public License. The License Elements of this
+     Public License are Attribution and ShareAlike.
+
+  h. Licensed Material means the artistic or literary work, database,
+     or other material to which the Licensor applied this Public
+     License.
+
+  i. Licensed Rights means the rights granted to You subject to the
+     terms and conditions of this Public License, which are limited to
+     all Copyright and Similar Rights that apply to Your use of the
+     Licensed Material and that the Licensor has authority to license.
+
+  j. Licensor means the individual(s) or entity(ies) granting rights
+     under this Public License.
+
+  k. Share means to provide material to the public by any means or
+     process that requires permission under the Licensed Rights, such
+     as reproduction, public display, public performance, distribution,
+     dissemination, communication, or importation, and to make material
+     available to the public including in ways that members of the
+     public may access the material from a place and at a time
+     individually chosen by them.
+
+  l. Sui Generis Database Rights means rights other than copyright
+     resulting from Directive 96/9/EC of the European Parliament and of
+     the Council of 11 March 1996 on the legal protection of databases,
+     as amended and/or succeeded, as well as other essentially
+     equivalent rights anywhere in the world.
+
+  m. You means the individual or entity exercising the Licensed Rights
+     under this Public License. Your has a corresponding meaning.
+
+
+Section 2 -- Scope.
+
+  a. License grant.
+
+       1. Subject to the terms and conditions of this Public License,
+          the Licensor hereby grants You a worldwide, royalty-free,
+          non-sublicensable, non-exclusive, irrevocable license to
+          exercise the Licensed Rights in the Licensed Material to:
+
+            a. reproduce and Share the Licensed Material, in whole or
+               in part; and
+
+            b. produce, reproduce, and Share Adapted Material.
+
+       2. Exceptions and Limitations. For the avoidance of doubt, where
+          Exceptions and Limitations apply to Your use, this Public
+          License does not apply, and You do not need to comply with
+          its terms and conditions.
+
+       3. Term. The term of this Public License is specified in Section
+          6(a).
+
+       4. Media and formats; technical modifications allowed. The
+          Licensor authorizes You to exercise the Licensed Rights in
+          all media and formats whether now known or hereafter created,
+          and to make technical modifications necessary to do so. The
+          Licensor waives and/or agrees not to assert any right or
+          authority to forbid You from making technical modifications
+          necessary to exercise the Licensed Rights, including
+          technical modifications necessary to circumvent Effective
+          Technological Measures. For purposes of this Public License,
+          simply making modifications authorized by this Section 2(a)
+          (4) never produces Adapted Material.
+
+       5. Downstream recipients.
+
+            a. Offer from the Licensor -- Licensed Material. Every
+               recipient of the Licensed Material automatically
+               receives an offer from the Licensor to exercise the
+               Licensed Rights under the terms and conditions of this
+               Public License.
+
+            b. Additional offer from the Licensor -- Adapted Material.
+               Every recipient of Adapted Material from You
+               automatically receives an offer from the Licensor to
+               exercise the Licensed Rights in the Adapted Material
+               under the conditions of the Adapter's License You apply.
+
+            c. No downstream restrictions. You may not offer or impose
+               any additional or different terms or conditions on, or
+               apply any Effective Technological Measures to, the
+               Licensed Material if doing so restricts exercise of the
+               Licensed Rights by any recipient of the Licensed
+               Material.
+
+       6. No endorsement. Nothing in this Public License constitutes or
+          may be construed as permission to assert or imply that You
+          are, or that Your use of the Licensed Material is, connected
+          with, or sponsored, endorsed, or granted official status by,
+          the Licensor or others designated to receive attribution as
+          provided in Section 3(a)(1)(A)(i).
+
+  b. Other rights.
+
+       1. Moral rights, such as the right of integrity, are not
+          licensed under this Public License, nor are publicity,
+          privacy, and/or other similar personality rights; however, to
+          the extent possible, the Licensor waives and/or agrees not to
+          assert any such rights held by the Licensor to the limited
+          extent necessary to allow You to exercise the Licensed
+          Rights, but not otherwise.
+
+       2. Patent and trademark rights are not licensed under this
+          Public License.
+
+       3. To the extent possible, the Licensor waives any right to
+          collect royalties from You for the exercise of the Licensed
+          Rights, whether directly or through a collecting society
+          under any voluntary or waivable statutory or compulsory
+          licensing scheme. In all other cases the Licensor expressly
+          reserves any right to collect such royalties.
+
+
+Section 3 -- License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the
+following conditions.
+
+  a. Attribution.
+
+       1. If You Share the Licensed Material (including in modified
+          form), You must:
+
+            a. retain the following if it is supplied by the Licensor
+               with the Licensed Material:
+
+                 i. identification of the creator(s) of the Licensed
+                    Material and any others designated to receive
+                    attribution, in any reasonable manner requested by
+                    the Licensor (including by pseudonym if
+                    designated);
+
+                ii. a copyright notice;
+
+               iii. a notice that refers to this Public License;
+
+                iv. a notice that refers to the disclaimer of
+                    warranties;
+
+                 v. a URI or hyperlink to the Licensed Material to the
+                    extent reasonably practicable;
+
+            b. indicate if You modified the Licensed Material and
+               retain an indication of any previous modifications; and
+
+            c. indicate the Licensed Material is licensed under this
+               Public License, and include the text of, or the URI or
+               hyperlink to, this Public License.
+
+       2. You may satisfy the conditions in Section 3(a)(1) in any
+          reasonable manner based on the medium, means, and context in
+          which You Share the Licensed Material. For example, it may be
+          reasonable to satisfy the conditions by providing a URI or
+          hyperlink to a resource that includes the required
+          information.
+
+       3. If requested by the Licensor, You must remove any of the
+          information required by Section 3(a)(1)(A) to the extent
+          reasonably practicable.
+
+  b. ShareAlike.
+
+     In addition to the conditions in Section 3(a), if You Share
+     Adapted Material You produce, the following conditions also apply.
+
+       1. The Adapter's License You apply must be a Creative Commons
+          license with the same License Elements, this version or
+          later, or a BY-SA Compatible License.
+
+       2. You must include the text of, or the URI or hyperlink to, the
+          Adapter's License You apply. You may satisfy this condition
+          in any reasonable manner based on the medium, means, and
+          context in which You Share Adapted Material.
+
+       3. You may not offer or impose any additional or different terms
+          or conditions on, or apply any Effective Technological
+          Measures to, Adapted Material that restrict exercise of the
+          rights granted under the Adapter's License You apply.
+
+
+Section 4 -- Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that
+apply to Your use of the Licensed Material:
+
+  a. for the avoidance of doubt, Section 2(a)(1) grants You the right
+     to extract, reuse, reproduce, and Share all or a substantial
+     portion of the contents of the database;
+
+  b. if You include all or a substantial portion of the database
+     contents in a database in which You have Sui Generis Database
+     Rights, then the database in which You have Sui Generis Database
+     Rights (but not its individual contents) is Adapted Material,
+
+     including for purposes of Section 3(b); and
+  c. You must comply with the conditions in Section 3(a) if You Share
+     all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not
+replace Your obligations under this Public License where the Licensed
+Rights include other Copyright and Similar Rights.
+
+
+Section 5 -- Disclaimer of Warranties and Limitation of Liability.
+
+  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
+     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
+     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
+     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
+     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
+     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
+     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
+     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
+     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
+
+  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
+     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
+     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
+     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
+     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
+     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
+     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
+     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
+
+  c. The disclaimer of warranties and limitation of liability provided
+     above shall be interpreted in a manner that, to the extent
+     possible, most closely approximates an absolute disclaimer and
+     waiver of all liability.
+
+
+Section 6 -- Term and Termination.
+
+  a. This Public License applies for the term of the Copyright and
+     Similar Rights licensed here. However, if You fail to comply with
+     this Public License, then Your rights under this Public License
+     terminate automatically.
+
+  b. Where Your right to use the Licensed Material has terminated under
+     Section 6(a), it reinstates:
+
+       1. automatically as of the date the violation is cured, provided
+          it is cured within 30 days of Your discovery of the
+          violation; or
+
+       2. upon express reinstatement by the Licensor.
+
+     For the avoidance of doubt, this Section 6(b) does not affect any
+     right the Licensor may have to seek remedies for Your violations
+     of this Public License.
+
+  c. For the avoidance of doubt, the Licensor may also offer the
+     Licensed Material under separate terms or conditions or stop
+     distributing the Licensed Material at any time; however, doing so
+     will not terminate this Public License.
+
+  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
+     License.
+
+
+Section 7 -- Other Terms and Conditions.
+
+  a. The Licensor shall not be bound by any additional or different
+     terms or conditions communicated by You unless expressly agreed.
+
+  b. Any arrangements, understandings, or agreements regarding the
+     Licensed Material not stated herein are separate from and
+     independent of the terms and conditions of this Public License.
+
+
+Section 8 -- Interpretation.
+
+  a. For the avoidance of doubt, this Public License does not, and
+     shall not be interpreted to, reduce, limit, restrict, or impose
+     conditions on any use of the Licensed Material that could lawfully
+     be made without permission under this Public License.
+
+  b. To the extent possible, if any provision of this Public License is
+     deemed unenforceable, it shall be automatically reformed to the
+     minimum extent necessary to make it enforceable. If the provision
+     cannot be reformed, it shall be severed from this Public License
+     without affecting the enforceability of the remaining terms and
+     conditions.
+
+  c. No term or condition of this Public License will be waived and no
+     failure to comply consented to unless expressly agreed to by the
+     Licensor.
+
+  d. Nothing in this Public License constitutes or may be interpreted
+     as a limitation upon, or waiver of, any privileges and immunities
+     that apply to the Licensor or You, including from the legal
+     processes of any jurisdiction or authority.
+
+
+=======================================================================
+
+Creative Commons is not a party to its public
+licenses. Notwithstanding, Creative Commons may elect to apply one of
+its public licenses to material it publishes and in those instances
+will be considered the “Licensor.” The text of the Creative Commons
+public licenses is dedicated to the public domain under the CC0 Public
+Domain Dedication. Except for the limited purpose of indicating that
+material is shared under a Creative Commons public license or as
+otherwise permitted by the Creative Commons policies published at
+creativecommons.org/policies, Creative Commons does not authorize the
+use of the trademark "Creative Commons" or any other trademark or logo
+of Creative Commons without its prior written consent including,
+without limitation, in connection with any unauthorized modifications
+to any of its public licenses or any other arrangements,
+understandings, or agreements concerning use of licensed material. For
+the avoidance of doubt, this paragraph does not form part of the
+public licenses.
+
+Creative Commons may be contacted at creativecommons.org.

From e71232b130d4fdd1d9a43ea909e87a76972ab205 Mon Sep 17 00:00:00 2001
From: Preetam Jinka <preetam@vividcortex.com>
Date: Wed, 16 Mar 2016 14:52:21 -0400
Subject: [PATCH 33/47] add license badge

---
 _includes/leftnav.html | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/_includes/leftnav.html b/_includes/leftnav.html
index 5ca5d57..df91360 100644
--- a/_includes/leftnav.html
+++ b/_includes/leftnav.html
@@ -19,4 +19,8 @@
   {% endfor %}
 {% endfor %}
   </ul>
+  <hr />
+  <div class="license">
+    <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/80x15.png" /></a>
+  </div>
 </div>

From 2806884f34be85e0e839a483c1097245be790124 Mon Sep 17 00:00:00 2001
From: Ilja Heitlager <iheitlager@schubergphilis.com>
Date: Wed, 3 Aug 2016 09:04:56 +0200
Subject: [PATCH 34/47] Update references.md

---
 references.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/references.md b/references.md
index ae4de6e..b61fcf6 100644
--- a/references.md
+++ b/references.md
@@ -9,6 +9,7 @@ Here are some external sources of information we've found to be helpful.
 * [http://jmoiron.net/blog/gos-database-sql/](http://jmoiron.net/blog/gos-database-sql/)
 * [http://jmoiron.net/blog/built-in-interfaces/](http://jmoiron.net/blog/built-in-interfaces/)
 * The VividCortex blog, e.g. [transparent encryption](https://vividcortex.com/blog/2014/11/11/encrypting-data-in-mysql-with-go/)
+* Overview of SQL Drivers from [golang github](https://github.com/golang/go/wiki/SQLDrivers)
 
 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

From c90d644aa2268e5a94136111c0e78e627c50fe56 Mon Sep 17 00:00:00 2001
From: Sartaj Singh <srtaj.sngh@gmail.com>
Date: Mon, 22 May 2017 20:24:44 +0530
Subject: [PATCH 35/47] Add SetConnMaxLifetime details to connection pool

---
 connection-pool.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/connection-pool.md b/connection-pool.md
index ae1dc6f..097945f 100644
--- a/connection-pool.md
+++ b/connection-pool.md
@@ -14,6 +14,7 @@ useful to know:
 * In Go 1.2.1 or newer, you can use `db.SetMaxOpenConns(N)` to limit the number of *total* open connections to the database. Unfortunately, a [deadlock bug](https://groups.google.com/d/msg/golang-dev/jOTqHxI09ns/x79ajll-ab4J) ([fix](https://code.google.com/p/go/source/detail?r=8a7ac002f840)) prevents `db.SetMaxOpenConns(N)` from safely being used in 1.2.
 * Connections are recycled rather fast. Setting a high number of idle connections with `db.SetMaxIdleConns(N)` can reduce this churn, and help keep connections around for reuse.
 * Keeping a connection idle for a long time can cause problems (like in [this issue](https://github.com/go-sql-driver/mysql/issues/257) with MySQL on Microsoft Azure). Try `db.SetMaxIdleConns(0)` if you get connection timeouts because a connection is idle for too long.
+* You can also specify the maximum amount of time a connection may be reused by setting `db.SetConnMaxLifetime(duration)` since reusing long lived connections may cause network issues. This closes the unused connections lazily i.e. closing expired connection may be deferred.
 
 **Previous: [Working with Unknown Columns](varcols.html)**
 **Next: [Surprises, Antipatterns and Limitations](surprises.html)**

From ceadad3644eb23bb437029f8873027f0d084a3d6 Mon Sep 17 00:00:00 2001
From: kenny <kenny.ortmann@gmail.com>
Date: Thu, 15 Feb 2018 13:20:58 -0600
Subject: [PATCH 36/47] Update nulls.md

Rename value used for selecting column to `otherField` to reflect comment below
---
 nulls.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nulls.md b/nulls.md
index 274b450..389315c 100644
--- a/nulls.md
+++ b/nulls.md
@@ -42,7 +42,7 @@ If you can't avoid having NULL values in your database, there is another work ar
 rows, err := db.Query(`
 	SELECT
 		name,
-		COALESCE(other_field, '') as other_field
+		COALESCE(other_field, '') as otherField
 	WHERE id = ?
 `, 42)
 

From 6b46e2e38dcdf47b7f1cb61ed3625e84ab2c5577 Mon Sep 17 00:00:00 2001
From: alex <alex.liutao@outlook.com>
Date: Tue, 8 May 2018 15:04:43 +0800
Subject: [PATCH 37/47] Possible missing stmt.Close

Are you missing `derfer stmt.Close` on here or you just did it on purpose?
Please explain to us why you don't need to stmt.Close() in this scenario
---
 retrieving.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/retrieving.md b/retrieving.md
index 85e14c2..33cee55 100644
--- a/retrieving.md
+++ b/retrieving.md
@@ -167,6 +167,7 @@ stmt, err := db.Prepare("select name from users where id = ?")
 if err != nil {
 	log.Fatal(err)
 }
+defer stmt.Close()
 var name string
 err = stmt.QueryRow(1).Scan(&amp;name)
 if err != nil {

From 167139ec1528e5c86956329ab427cc015f693963 Mon Sep 17 00:00:00 2001
From: Dimitri Balios <Jimmy99@users.noreply.github.com>
Date: Sat, 6 Oct 2018 15:28:10 +0200
Subject: [PATCH 38/47] Update importing.md

---
 importing.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/importing.md b/importing.md
index 9b6608a..ef1ab3a 100644
--- a/importing.md
+++ b/importing.md
@@ -30,7 +30,7 @@ import (
 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.
+but in general nothing else happens with the exception that the init function is run.
 
 Now you're ready to access a database.
 

From d36f9a6ce2d9c498f5c972f23b0a711f54668a60 Mon Sep 17 00:00:00 2001
From: Baron Schwartz <xaprb@users.noreply.github.com>
Date: Mon, 29 Oct 2018 15:33:53 -0400
Subject: [PATCH 39/47] fix deprecated pygments

---
 _config.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_config.yml b/_config.yml
index 953722e..9e1bfd3 100644
--- a/_config.yml
+++ b/_config.yml
@@ -2,6 +2,6 @@ title:            Go database/sql tutorial
 description:      Use database/sql effectively!
 safe: true
 lsi: false
-pygments: true
+highlighter: rouge
 timezone: UTC
 markdown: kramdown

From cb7dc9b43218891d5f7b9ee0edd02edece71cb40 Mon Sep 17 00:00:00 2001
From: "Afriza N. Arief" <68133+afriza@users.noreply.github.com>
Date: Fri, 18 Jan 2019 15:46:39 +0700
Subject: [PATCH 40/47] fix typo in overview.md

change `db.SQL` to `sql.DB`
---
 overview.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/overview.md b/overview.md
index 92d344a..1a3287a 100644
--- a/overview.md
+++ b/overview.md
@@ -21,7 +21,7 @@ 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
+to release connections back to the pool, you can cause `sql.DB` 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.

From 8d17aaeb98d9a466f19b649de8ff2d1b277e5cb5 Mon Sep 17 00:00:00 2001
From: cglotr <amir.ariffin.920404@gmail.com>
Date: Tue, 29 Jan 2019 14:40:03 +0800
Subject: [PATCH 41/47] fix navigation not showing

---
 _data/nav.yml          | 37 +++++++++++++++++++++++++++++++++++++
 _includes/leftnav.html | 24 ++++++------------------
 2 files changed, 43 insertions(+), 18 deletions(-)
 create mode 100644 _data/nav.yml

diff --git a/_data/nav.yml b/_data/nav.yml
new file mode 100644
index 0000000..1d2d2a1
--- /dev/null
+++ b/_data/nav.yml
@@ -0,0 +1,37 @@
+docs:
+
+  - title: Go database/sql tutorial
+    url: index.html
+
+  - title: Overview
+    url: overview.html
+
+  - title: Accessing the Database
+    url: accessing.html
+
+  - title: Retrieving Result Sets
+    url: retrieving.html
+
+  - title: Modifying Data and Using Transactions
+    url: modifying.html
+
+  - title: Using Prepared Statements
+    url: prepared.html
+
+  - title: Handling Errors
+    url: errors.html
+
+  - title: Working with NULLs
+    url: nulls.html
+
+  - title: Working with Unknown Columns
+    url: varcols.html
+
+  - title: The Connection Pool
+    url: connection-pool.html
+
+  - title: Surprises, Antipatterns and Limitations
+    url: surprises.html
+
+  - title: Related Reading and Resources
+    url: references.html
diff --git a/_includes/leftnav.html b/_includes/leftnav.html
index df91360..832c653 100644
--- a/_includes/leftnav.html
+++ b/_includes/leftnav.html
@@ -1,23 +1,11 @@
 <div class="leftnav">
   <ul class="nav nav-list">
-{% for group in page.nav %}
-  {% capture group_url %}/{{ page.name }}/{{ group.url }}{% endcapture %}
-  <li class="nav-header{% if page.url == node_url %} active{% endif %}">
-    {% if page.url %}
-      <a href="{{group.url}}">{{group.name}}</a>
-    {% else %}
-      {{group.name}}
-    {% endif %}
-  </li>
-  {% for node in group.articles %}
-    {% capture node_url %}/{{ page.name }}/{{ node.url }}{% endcapture %}
-    {% if page.url == node_url %}
-      <li class="active"><a href="{{node.url}}">{{node.title}}</a></li>
-    {% else %}
-      <li><a href="{{node.url}}">{{node.title}}</a></li>
-    {% endif %}
-  {% endfor %}
-{% endfor %}
+    {% for doc in site.data.nav.docs %}
+      {% assign curr_url = page.url | remove_first: "/" %}
+      <li class="{% if doc.url == 'index.html' %}nav-header{% endif %} {% if curr_url == doc.url %}active{% endif %}">
+        <a href="{{ doc.url }}">{{ doc.title }}</a>
+      </li>
+    {% endfor %}
   </ul>
   <hr />
   <div class="license">

From 910626ff2bcd0b772f03948a243b0c812daf35ba Mon Sep 17 00:00:00 2001
From: cglotr <amir.ariffin.920404@gmail.com>
Date: Thu, 31 Jan 2019 12:36:11 +0800
Subject: [PATCH 42/47] add missing importing nav

---
 _data/nav.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/_data/nav.yml b/_data/nav.yml
index 1d2d2a1..dfab5a9 100644
--- a/_data/nav.yml
+++ b/_data/nav.yml
@@ -6,6 +6,9 @@ docs:
   - title: Overview
     url: overview.html
 
+  - title: Importing a Database Driver
+    url: importing.html
+
   - title: Accessing the Database
     url: accessing.html
 

From 86f6735f4f287c776e12b8ba1eb2bb1596587ad0 Mon Sep 17 00:00:00 2001
From: Eli Bendersky <eliben@users.noreply.github.com>
Date: Wed, 6 Mar 2019 06:26:05 -0800
Subject: [PATCH 43/47] Fix grammar typo

---
 overview.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/overview.md b/overview.md
index 1a3287a..337973b 100644
--- a/overview.md
+++ b/overview.md
@@ -12,7 +12,7 @@ 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.
 
-The `sql.DB` performs some important tasks for you behind the scenes:
+`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, which may be a variety of things as mentioned.

From 9d2e80505f0f4ef12e7c35fab637f9aecd87bf2f Mon Sep 17 00:00:00 2001
From: Eli Bendersky <eliben@users.noreply.github.com>
Date: Wed, 6 Mar 2019 06:39:53 -0800
Subject: [PATCH 44/47] Grammar fix

---
 modifying.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modifying.md b/modifying.md
index 074188a..f649022 100644
--- a/modifying.md
+++ b/modifying.md
@@ -12,7 +12,7 @@ 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
+`UPDATE`, `DELETE`, or another statement that doesn't return rows. The following
 example shows how to insert a row and inspect metadata about the operation:
 
 <pre class="prettyprint lang-go">

From 07f6fad65812bc6db25e748c834da8d634b052e8 Mon Sep 17 00:00:00 2001
From: Eli Bendersky <eliben@users.noreply.github.com>
Date: Thu, 7 Mar 2019 07:03:00 -0800
Subject: [PATCH 45/47] Fix reference to 'db' var

In the rest of the example `db` is used, not `Db`. Moreover, I think that a simple example here could help clarify the terminology, because it gets a bit murky between `db` (object of type `DB`) and `tx` (object of type `Tx`). Something like:

```
// Create an object of type Tx
tx, err := db.Begin()
...
```
---
 modifying.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/modifying.md b/modifying.md
index f649022..487aac3 100644
--- a/modifying.md
+++ b/modifying.md
@@ -84,8 +84,8 @@ code. Bad things might result:
 * 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.
 
 While you are working inside a transaction you should be careful not to make
-calls to the `Db` variable. Make all of your calls to the `Tx` variable that you
-created with `db.Begin()`. The `Db` is not in a transaction, only the `Tx` is.
+calls to the `db` variable. Make all of your calls to the `Tx` variable that you
+created with `db.Begin()`. `db` is not in a transaction, only the `Tx` object is.
 If you make further calls to `db.Exec()` or similar, those will happen outside
 the scope of your transaction, on other connections.
 

From 75b25123d375bc1a86a6b83f4070f0e28c215c38 Mon Sep 17 00:00:00 2001
From: "whitesource-for-github.amrom.workers.dev[bot]"
 <50673670+whitesource-for-github.amrom.workers.dev[bot]@users.noreply.github.com>
Date: Wed, 24 Jun 2020 14:11:58 +0000
Subject: [PATCH 46/47] Add .whitesource configuration file

---
 .whitesource | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 .whitesource

diff --git a/.whitesource b/.whitesource
new file mode 100644
index 0000000..60fc783
--- /dev/null
+++ b/.whitesource
@@ -0,0 +1,13 @@
+{
+  "scanSettings": {
+    "configMode": "AUTO",
+    "configExternalURL": "",
+    "projectToken" : ""
+  },
+  "checkRunSettings": {
+    "vulnerableCheckRunConclusionLevel": "failure"
+  },
+  "issueSettings": {
+    "minSeverityLevel": "LOW"
+  }
+}
\ No newline at end of file

From ae7ad3a8886f5ff92f269fe35debe3021005d336 Mon Sep 17 00:00:00 2001
From: "whitesource-for-github.amrom.workers.dev[bot]"
 <50673670+whitesource-for-github.amrom.workers.dev[bot]@users.noreply.github.com>
Date: Tue, 15 Dec 2020 15:54:46 +0000
Subject: [PATCH 47/47] Migrate .whitesource configuration file to inheritance
 mode

---
 .whitesource | 12 +-----------
 1 file changed, 1 insertion(+), 11 deletions(-)

diff --git a/.whitesource b/.whitesource
index 60fc783..d7eebc0 100644
--- a/.whitesource
+++ b/.whitesource
@@ -1,13 +1,3 @@
 {
-  "scanSettings": {
-    "configMode": "AUTO",
-    "configExternalURL": "",
-    "projectToken" : ""
-  },
-  "checkRunSettings": {
-    "vulnerableCheckRunConclusionLevel": "failure"
-  },
-  "issueSettings": {
-    "minSeverityLevel": "LOW"
-  }
+  "settingsInheritedFrom": "VividCortex/whitesource-config@master"
 }
\ No newline at end of file