From: Brad Fitzpatrick <bradfitz@golang.org>
Date: Wed, 7 Mar 2012 01:44:47 +0000 (-0800)
Subject: database/sql: add docs about connection state, pooling
X-Git-Tag: weekly.2012-03-13~172
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=502e29f485c2a3ed5691601a689911199fd5aef0;p=gostls13.git

database/sql: add docs about connection state, pooling

Fixes #3223

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5755063
---

diff --git a/src/pkg/database/sql/sql.go b/src/pkg/database/sql/sql.go
index f50daa11a1..2fdf57b6c8 100644
--- a/src/pkg/database/sql/sql.go
+++ b/src/pkg/database/sql/sql.go
@@ -175,6 +175,16 @@ var ErrNoRows = errors.New("sql: no rows in result set")
 
 // DB is a database handle. It's safe for concurrent use by multiple
 // goroutines.
+//
+// If the underlying database driver has the concept of a connection
+// and per-connection session state, the sql package manages creating
+// and freeing connections automatically, including maintaining a free
+// pool of idle connections. If observing session state is required,
+// either do not share a *DB between multiple concurrent goroutines or
+// create and observe all state only within a transaction. Once
+// DB.Open is called, the returned Tx is bound to a single isolated
+// connection. Once Tx.Commit or Tx.Rollback is called, that
+// connection is returned to DB's idle connection pool.
 type DB struct {
 	driver driver.Driver
 	dsn    string