1 // Copyright 2011 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
5 // Package sql provides a generic interface around SQL (or SQL-like)
8 // The sql package must be used in conjunction with a database driver.
9 // See https://golang.org/s/sqldrivers for a list of drivers.
11 // Drivers that do not support context cancellation will not return until
12 // after the query is completed.
14 // For usage examples, see the wiki page at
15 // https://golang.org/s/sqlwiki.
34 driversMu sync
.RWMutex
35 drivers
= make(map[string]driver
.Driver
)
38 // nowFunc returns the current time; it's overridden in tests.
39 var nowFunc
= time
.Now
41 // Register makes a database driver available by the provided name.
42 // If Register is called twice with the same name or if driver is nil,
44 func Register(name
string, driver driver
.Driver
) {
46 defer driversMu
.Unlock()
48 panic("sql: Register driver is nil")
50 if _
, dup
:= drivers
[name
]; dup
{
51 panic("sql: Register called twice for driver " + name
)
53 drivers
[name
] = driver
56 func unregisterAllDrivers() {
58 defer driversMu
.Unlock()
60 drivers
= make(map[string]driver
.Driver
)
63 // Drivers returns a sorted list of the names of the registered drivers.
64 func Drivers() []string {
66 defer driversMu
.RUnlock()
67 list
:= make([]string, 0, len(drivers
))
68 for name
:= range drivers
{
69 list
= append(list
, name
)
75 // A NamedArg is a named argument. NamedArg values may be used as
76 // arguments to Query or Exec and bind to the corresponding named
77 // parameter in the SQL statement.
79 // For a more concise way to create NamedArg values, see
80 // the Named function.
81 type NamedArg
struct {
82 _Named_Fields_Required
struct{}
84 // Name is the name of the parameter placeholder.
86 // If empty, the ordinal position in the argument list will be
89 // Name must omit any symbol prefix.
92 // Value is the value of the parameter.
93 // It may be assigned the same value types as the query
98 // Named provides a more concise way to create NamedArg values.
102 // db.ExecContext(ctx, `
103 // delete from Invoice
105 // TimeCreated < @end
106 // and TimeCreated >= @start;`,
107 // sql.Named("start", startTime),
108 // sql.Named("end", endTime),
110 func Named(name
string, value any
) NamedArg
{
111 // This method exists because the go1compat promise
112 // doesn't guarantee that structs don't grow more fields,
113 // so unkeyed struct literals are a vet error. Thus, we don't
114 // want to allow sql.NamedArg{name, value}.
115 return NamedArg
{Name
: name
, Value
: value
}
118 // IsolationLevel is the transaction isolation level used in TxOptions.
119 type IsolationLevel
int
121 // Various isolation levels that drivers may support in BeginTx.
122 // If a driver does not support a given isolation level an error may be returned.
124 // See https://en.wikipedia.org/wiki/Isolation_(database_systems)#Isolation_levels.
126 LevelDefault IsolationLevel
= iota
136 // String returns the name of the transaction isolation level.
137 func (i IsolationLevel
) String() string {
141 case LevelReadUncommitted
:
142 return "Read Uncommitted"
143 case LevelReadCommitted
:
144 return "Read Committed"
145 case LevelWriteCommitted
:
146 return "Write Committed"
147 case LevelRepeatableRead
:
148 return "Repeatable Read"
151 case LevelSerializable
:
152 return "Serializable"
153 case LevelLinearizable
:
154 return "Linearizable"
156 return "IsolationLevel(" + strconv
.Itoa(int(i
)) + ")"
160 var _ fmt
.Stringer
= LevelDefault
162 // TxOptions holds the transaction options to be used in DB.BeginTx.
163 type TxOptions
struct {
164 // Isolation is the transaction isolation level.
165 // If zero, the driver or database's default level is used.
166 Isolation IsolationLevel
170 // RawBytes is a byte slice that holds a reference to memory owned by
171 // the database itself. After a Scan into a RawBytes, the slice is only
172 // valid until the next call to Next, Scan, or Close.
175 // NullString represents a string that may be null.
176 // NullString implements the Scanner interface so
177 // it can be used as a scan destination:
180 // err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s)
188 type NullString
struct {
190 Valid
bool // Valid is true if String is not NULL
193 // Scan implements the Scanner interface.
194 func (ns
*NullString
) Scan(value any
) error
{
196 ns
.String
, ns
.Valid
= "", false
200 return convertAssign(&ns
.String
, value
)
203 // Value implements the driver Valuer interface.
204 func (ns NullString
) Value() (driver
.Value
, error
) {
208 return ns
.String
, nil
211 // NullInt64 represents an int64 that may be null.
212 // NullInt64 implements the Scanner interface so
213 // it can be used as a scan destination, similar to NullString.
214 type NullInt64
struct {
216 Valid
bool // Valid is true if Int64 is not NULL
219 // Scan implements the Scanner interface.
220 func (n
*NullInt64
) Scan(value any
) error
{
222 n
.Int64
, n
.Valid
= 0, false
226 return convertAssign(&n
.Int64
, value
)
229 // Value implements the driver Valuer interface.
230 func (n NullInt64
) Value() (driver
.Value
, error
) {
237 // NullInt32 represents an int32 that may be null.
238 // NullInt32 implements the Scanner interface so
239 // it can be used as a scan destination, similar to NullString.
240 type NullInt32
struct {
242 Valid
bool // Valid is true if Int32 is not NULL
245 // Scan implements the Scanner interface.
246 func (n
*NullInt32
) Scan(value any
) error
{
248 n
.Int32
, n
.Valid
= 0, false
252 return convertAssign(&n
.Int32
, value
)
255 // Value implements the driver Valuer interface.
256 func (n NullInt32
) Value() (driver
.Value
, error
) {
260 return int64(n
.Int32
), nil
263 // NullInt16 represents an int16 that may be null.
264 // NullInt16 implements the Scanner interface so
265 // it can be used as a scan destination, similar to NullString.
266 type NullInt16
struct {
268 Valid
bool // Valid is true if Int16 is not NULL
271 // Scan implements the Scanner interface.
272 func (n
*NullInt16
) Scan(value any
) error
{
274 n
.Int16
, n
.Valid
= 0, false
277 err
:= convertAssign(&n
.Int16
, value
)
282 // Value implements the driver Valuer interface.
283 func (n NullInt16
) Value() (driver
.Value
, error
) {
287 return int64(n
.Int16
), nil
290 // NullByte represents a byte that may be null.
291 // NullByte implements the Scanner interface so
292 // it can be used as a scan destination, similar to NullString.
293 type NullByte
struct {
295 Valid
bool // Valid is true if Byte is not NULL
298 // Scan implements the Scanner interface.
299 func (n
*NullByte
) Scan(value any
) error
{
301 n
.Byte
, n
.Valid
= 0, false
304 err
:= convertAssign(&n
.Byte
, value
)
309 // Value implements the driver Valuer interface.
310 func (n NullByte
) Value() (driver
.Value
, error
) {
314 return int64(n
.Byte
), nil
317 // NullFloat64 represents a float64 that may be null.
318 // NullFloat64 implements the Scanner interface so
319 // it can be used as a scan destination, similar to NullString.
320 type NullFloat64
struct {
322 Valid
bool // Valid is true if Float64 is not NULL
325 // Scan implements the Scanner interface.
326 func (n
*NullFloat64
) Scan(value any
) error
{
328 n
.Float64
, n
.Valid
= 0, false
332 return convertAssign(&n
.Float64
, value
)
335 // Value implements the driver Valuer interface.
336 func (n NullFloat64
) Value() (driver
.Value
, error
) {
340 return n
.Float64
, nil
343 // NullBool represents a bool that may be null.
344 // NullBool implements the Scanner interface so
345 // it can be used as a scan destination, similar to NullString.
346 type NullBool
struct {
348 Valid
bool // Valid is true if Bool is not NULL
351 // Scan implements the Scanner interface.
352 func (n
*NullBool
) Scan(value any
) error
{
354 n
.Bool
, n
.Valid
= false, false
358 return convertAssign(&n
.Bool
, value
)
361 // Value implements the driver Valuer interface.
362 func (n NullBool
) Value() (driver
.Value
, error
) {
369 // NullTime represents a time.Time that may be null.
370 // NullTime implements the Scanner interface so
371 // it can be used as a scan destination, similar to NullString.
372 type NullTime
struct {
374 Valid
bool // Valid is true if Time is not NULL
377 // Scan implements the Scanner interface.
378 func (n
*NullTime
) Scan(value any
) error
{
380 n
.Time
, n
.Valid
= time
.Time
{}, false
384 return convertAssign(&n
.Time
, value
)
387 // Value implements the driver Valuer interface.
388 func (n NullTime
) Value() (driver
.Value
, error
) {
395 // Scanner is an interface used by Scan.
396 type Scanner
interface {
397 // Scan assigns a value from a database driver.
399 // The src value will be of one of the following types:
407 // nil - for NULL values
409 // An error should be returned if the value cannot be stored
410 // without loss of information.
412 // Reference types such as []byte are only valid until the next call to Scan
413 // and should not be retained. Their underlying memory is owned by the driver.
414 // If retention is necessary, copy their values before the next call to Scan.
418 // Out may be used to retrieve OUTPUT value parameters from stored procedures.
420 // Not all drivers and databases support OUTPUT value parameters.
425 // _, err := db.ExecContext(ctx, "ProcName", sql.Named("Arg1", sql.Out{Dest: &outArg}))
427 _Named_Fields_Required
struct{}
429 // Dest is a pointer to the value that will be set to the result of the
430 // stored procedure's OUTPUT parameter.
433 // In is whether the parameter is an INOUT parameter. If so, the input value to the stored
434 // procedure is the dereferenced value of Dest's pointer, which is then replaced with
439 // ErrNoRows is returned by Scan when QueryRow doesn't return a
440 // row. In such a case, QueryRow returns a placeholder *Row value that
441 // defers this error until a Scan.
442 var ErrNoRows
= errors
.New("sql: no rows in result set")
444 // DB is a database handle representing a pool of zero or more
445 // underlying connections. It's safe for concurrent use by multiple
448 // The sql package creates and frees connections automatically; it
449 // also maintains a free pool of idle connections. If the database has
450 // a concept of per-connection state, such state can be reliably observed
451 // within a transaction (Tx) or connection (Conn). Once DB.Begin is called, the
452 // returned Tx is bound to a single connection. Once Commit or
453 // Rollback is called on the transaction, that transaction's
454 // connection is returned to DB's idle connection pool. The pool size
455 // can be controlled with SetMaxIdleConns.
457 // Atomic access only. At top of struct to prevent mis-alignment
458 // on 32-bit platforms. Of type time.Duration.
459 waitDuration
int64 // Total time waited for new connections.
461 connector driver
.Connector
462 // numClosed is an atomic counter which represents a total number of
463 // closed connections. Stmt.openStmt checks it before cleaning closed
464 // connections in Stmt.css.
467 mu sync
.Mutex
// protects following fields
468 freeConn
[]*driverConn
// free connections ordered by returnedAt oldest to newest
469 connRequests
map[uint64]chan connRequest
470 nextRequest
uint64 // Next key to use in connRequests.
471 numOpen
int // number of opened and pending open connections
472 // Used to signal the need for new connections
473 // a goroutine running connectionOpener() reads on this chan and
474 // maybeOpenNewConnections sends on the chan (one send per needed connection)
475 // It is closed during db.Close(). The close tells the connectionOpener
476 // goroutine to exit.
477 openerCh
chan struct{}
479 dep
map[finalCloser
]depSet
480 lastPut
map[*driverConn
]string // stacktrace of last conn's put; debug only
481 maxIdleCount
int // zero means defaultMaxIdleConns; negative means 0
482 maxOpen
int // <= 0 means unlimited
483 maxLifetime time
.Duration
// maximum amount of time a connection may be reused
484 maxIdleTime time
.Duration
// maximum amount of time a connection may be idle before being closed
485 cleanerCh
chan struct{}
486 waitCount
int64 // Total number of connections waited for.
487 maxIdleClosed
int64 // Total number of connections closed due to idle count.
488 maxIdleTimeClosed
int64 // Total number of connections closed due to idle time.
489 maxLifetimeClosed
int64 // Total number of connections closed due to max connection lifetime limit.
491 stop
func() // stop cancels the connection opener.
494 // connReuseStrategy determines how (*DB).conn returns database connections.
495 type connReuseStrategy
uint8
498 // alwaysNewConn forces a new connection to the database.
499 alwaysNewConn connReuseStrategy
= iota
500 // cachedOrNewConn returns a cached connection, if available, else waits
501 // for one to become available (if MaxOpenConns has been reached) or
502 // creates a new database connection.
506 // driverConn wraps a driver.Conn with a mutex, to
507 // be held during all calls into the Conn. (including any calls onto
508 // interfaces returned via that Conn, such as calls on Tx, Stmt,
510 type driverConn
struct {
514 sync
.Mutex
// guards following
516 needReset
bool // The connection session should be reset before use if true.
518 finalClosed
bool // ci.Close has been called
519 openStmt
map[*driverStmt
]bool
523 returnedAt time
.Time
// Time the connection was created or returned.
524 onPut
[]func() // code (with db.mu held) run when conn is next returned
525 dbmuClosed
bool // same as closed, but guarded by db.mu, for removeClosedStmtLocked
528 func (dc
*driverConn
) releaseConn(err error
) {
529 dc
.db
.putConn(dc
, err
, true)
532 func (dc
*driverConn
) removeOpenStmt(ds
*driverStmt
) {
535 delete(dc
.openStmt
, ds
)
538 func (dc
*driverConn
) expired(timeout time
.Duration
) bool {
542 return dc
.createdAt
.Add(timeout
).Before(nowFunc())
545 // resetSession checks if the driver connection needs the
546 // session to be reset and if required, resets it.
547 func (dc
*driverConn
) resetSession(ctx context
.Context
) error
{
554 if cr
, ok
:= dc
.ci
.(driver
.SessionResetter
); ok
{
555 return cr
.ResetSession(ctx
)
560 // validateConnection checks if the connection is valid and can
561 // still be used. It also marks the session for reset if required.
562 func (dc
*driverConn
) validateConnection(needsReset
bool) bool {
569 if cv
, ok
:= dc
.ci
.(driver
.Validator
); ok
{
575 // prepareLocked prepares the query on dc. When cg == nil the dc must keep track of
576 // the prepared statements in a pool.
577 func (dc
*driverConn
) prepareLocked(ctx context
.Context
, cg stmtConnGrabber
, query
string) (*driverStmt
, error
) {
578 si
, err
:= ctxDriverPrepare(ctx
, dc
.ci
, query
)
582 ds
:= &driverStmt
{Locker
: dc
, si
: si
}
584 // No need to manage open statements if there is a single connection grabber.
589 // Track each driverConn's open statements, so we can close them
590 // before closing the conn.
592 // Wrap all driver.Stmt is *driverStmt to ensure they are only closed once.
593 if dc
.openStmt
== nil {
594 dc
.openStmt
= make(map[*driverStmt
]bool)
596 dc
.openStmt
[ds
] = true
600 // the dc.db's Mutex is held.
601 func (dc
*driverConn
) closeDBLocked() func() error
{
605 return func() error
{ return errors
.New("sql: duplicate driverConn close") }
608 return dc
.db
.removeDepLocked(dc
, dc
)
611 func (dc
*driverConn
) Close() error
{
615 return errors
.New("sql: duplicate driverConn close")
618 dc
.Unlock() // not defer; removeDep finalClose calls may need to lock
620 // And now updates that require holding dc.mu.Lock.
623 fn
:= dc
.db
.removeDepLocked(dc
, dc
)
628 func (dc
*driverConn
) finalClose() error
{
631 // Each *driverStmt has a lock to the dc. Copy the list out of the dc
632 // before calling close on each stmt.
633 var openStmt
[]*driverStmt
634 withLock(dc
, func() {
635 openStmt
= make([]*driverStmt
, 0, len(dc
.openStmt
))
636 for ds
:= range dc
.openStmt
{
637 openStmt
= append(openStmt
, ds
)
641 for _
, ds
:= range openStmt
{
644 withLock(dc
, func() {
645 dc
.finalClosed
= true
652 dc
.db
.maybeOpenNewConnections()
655 atomic
.AddUint64(&dc
.db
.numClosed
, 1)
659 // driverStmt associates a driver.Stmt with the
660 // *driverConn from which it came, so the driverConn's lock can be
661 // held during calls.
662 type driverStmt
struct {
663 sync
.Locker
// the *driverConn
666 closeErr error
// return value of previous Close call
669 // Close ensures driver.Stmt is only closed once and always returns the same
671 func (ds
*driverStmt
) Close() error
{
678 ds
.closeErr
= ds
.si
.Close()
682 // depSet is a finalCloser's outstanding dependencies
683 type depSet
map[any
]bool // set of true bools
685 // The finalCloser interface is used by (*DB).addDep and related
686 // dependency reference counting.
687 type finalCloser
interface {
688 // finalClose is called when the reference count of an object
689 // goes to zero. (*DB).mu is not held while calling it.
693 // addDep notes that x now depends on dep, and x's finalClose won't be
694 // called until all of x's dependencies are removed with removeDep.
695 func (db
*DB
) addDep(x finalCloser
, dep any
) {
698 db
.addDepLocked(x
, dep
)
701 func (db
*DB
) addDepLocked(x finalCloser
, dep any
) {
703 db
.dep
= make(map[finalCloser
]depSet
)
713 // removeDep notes that x no longer depends on dep.
714 // If x still has dependencies, nil is returned.
715 // If x no longer has any dependencies, its finalClose method will be
716 // called and its error value will be returned.
717 func (db
*DB
) removeDep(x finalCloser
, dep any
) error
{
719 fn
:= db
.removeDepLocked(x
, dep
)
724 func (db
*DB
) removeDepLocked(x finalCloser
, dep any
) func() error
{
726 xdep
, ok
:= db
.dep
[x
]
728 panic(fmt
.Sprintf("unpaired removeDep: no deps for %T", x
))
736 // Nothing removed. Shouldn't happen.
737 panic(fmt
.Sprintf("unpaired removeDep: no %T dep on %T", dep
, x
))
739 // No more dependencies.
743 // Dependencies remain.
744 return func() error
{ return nil }
748 // This is the size of the connectionOpener request chan (DB.openerCh).
749 // This value should be larger than the maximum typical value
750 // used for db.maxOpen. If maxOpen is significantly larger than
751 // connectionRequestQueueSize then it is possible for ALL calls into the *DB
752 // to block until the connectionOpener can satisfy the backlog of requests.
753 var connectionRequestQueueSize
= 1000000
755 type dsnConnector
struct {
760 func (t dsnConnector
) Connect(_ context
.Context
) (driver
.Conn
, error
) {
761 return t
.driver
.Open(t
.dsn
)
764 func (t dsnConnector
) Driver() driver
.Driver
{
768 // OpenDB opens a database using a Connector, allowing drivers to
769 // bypass a string based data source name.
771 // Most users will open a database via a driver-specific connection
772 // helper function that returns a *DB. No database drivers are included
773 // in the Go standard library. See https://golang.org/s/sqldrivers for
774 // a list of third-party drivers.
776 // OpenDB may just validate its arguments without creating a connection
777 // to the database. To verify that the data source name is valid, call
780 // The returned DB is safe for concurrent use by multiple goroutines
781 // and maintains its own pool of idle connections. Thus, the OpenDB
782 // function should be called just once. It is rarely necessary to
784 func OpenDB(c driver
.Connector
) *DB
{
785 ctx
, cancel
:= context
.WithCancel(context
.Background())
788 openerCh
: make(chan struct{}, connectionRequestQueueSize
),
789 lastPut
: make(map[*driverConn
]string),
790 connRequests
: make(map[uint64]chan connRequest
),
794 go db
.connectionOpener(ctx
)
799 // Open opens a database specified by its database driver name and a
800 // driver-specific data source name, usually consisting of at least a
801 // database name and connection information.
803 // Most users will open a database via a driver-specific connection
804 // helper function that returns a *DB. No database drivers are included
805 // in the Go standard library. See https://golang.org/s/sqldrivers for
806 // a list of third-party drivers.
808 // Open may just validate its arguments without creating a connection
809 // to the database. To verify that the data source name is valid, call
812 // The returned DB is safe for concurrent use by multiple goroutines
813 // and maintains its own pool of idle connections. Thus, the Open
814 // function should be called just once. It is rarely necessary to
816 func Open(driverName
, dataSourceName
string) (*DB
, error
) {
818 driveri
, ok
:= drivers
[driverName
]
821 return nil, fmt
.Errorf("sql: unknown driver %q (forgotten import?)", driverName
)
824 if driverCtx
, ok
:= driveri
.(driver
.DriverContext
); ok
{
825 connector
, err
:= driverCtx
.OpenConnector(dataSourceName
)
829 return OpenDB(connector
), nil
832 return OpenDB(dsnConnector
{dsn
: dataSourceName
, driver
: driveri
}), nil
835 func (db
*DB
) pingDC(ctx context
.Context
, dc
*driverConn
, release
func(error
)) error
{
837 if pinger
, ok
:= dc
.ci
.(driver
.Pinger
); ok
{
838 withLock(dc
, func() {
839 err
= pinger
.Ping(ctx
)
846 // PingContext verifies a connection to the database is still alive,
847 // establishing a connection if necessary.
848 func (db
*DB
) PingContext(ctx context
.Context
) error
{
852 for i
:= 0; i
< maxBadConnRetries
; i
++ {
853 dc
, err
= db
.conn(ctx
, cachedOrNewConn
)
854 isBadConn
= errors
.Is(err
, driver
.ErrBadConn
)
860 dc
, err
= db
.conn(ctx
, alwaysNewConn
)
866 return db
.pingDC(ctx
, dc
, dc
.releaseConn
)
869 // Ping verifies a connection to the database is still alive,
870 // establishing a connection if necessary.
872 // Ping uses context.Background internally; to specify the context, use
874 func (db
*DB
) Ping() error
{
875 return db
.PingContext(context
.Background())
878 // Close closes the database and prevents new queries from starting.
879 // Close then waits for all queries that have started processing on the server
882 // It is rare to Close a DB, as the DB handle is meant to be
883 // long-lived and shared between many goroutines.
884 func (db
*DB
) Close() error
{
886 if db
.closed { // Make DB.Close idempotent
890 if db
.cleanerCh
!= nil {
894 fns
:= make([]func() error
, 0, len(db
.freeConn
))
895 for _
, dc
:= range db
.freeConn
{
896 fns
= append(fns
, dc
.closeDBLocked())
900 for _
, req
:= range db
.connRequests
{
904 for _
, fn
:= range fns
{
911 if c
, ok
:= db
.connector
.(io
.Closer
); ok
{
920 const defaultMaxIdleConns
= 2
922 func (db
*DB
) maxIdleConnsLocked() int {
926 // TODO(bradfitz): ask driver, if supported, for its default preference
927 return defaultMaxIdleConns
935 func (db
*DB
) shortestIdleTimeLocked() time
.Duration
{
936 if db
.maxIdleTime
<= 0 {
937 return db
.maxLifetime
939 if db
.maxLifetime
<= 0 {
940 return db
.maxIdleTime
943 min
:= db
.maxIdleTime
944 if min
> db
.maxLifetime
{
950 // SetMaxIdleConns sets the maximum number of connections in the idle
953 // If MaxOpenConns is greater than 0 but less than the new MaxIdleConns,
954 // then the new MaxIdleConns will be reduced to match the MaxOpenConns limit.
956 // If n <= 0, no idle connections are retained.
958 // The default max idle connections is currently 2. This may change in
960 func (db
*DB
) SetMaxIdleConns(n
int) {
965 // No idle connections.
968 // Make sure maxIdle doesn't exceed maxOpen
969 if db
.maxOpen
> 0 && db
.maxIdleConnsLocked() > db
.maxOpen
{
970 db
.maxIdleCount
= db
.maxOpen
972 var closing
[]*driverConn
973 idleCount
:= len(db
.freeConn
)
974 maxIdle
:= db
.maxIdleConnsLocked()
975 if idleCount
> maxIdle
{
976 closing
= db
.freeConn
[maxIdle
:]
977 db
.freeConn
= db
.freeConn
[:maxIdle
]
979 db
.maxIdleClosed
+= int64(len(closing
))
981 for _
, c
:= range closing
{
986 // SetMaxOpenConns sets the maximum number of open connections to the database.
988 // If MaxIdleConns is greater than 0 and the new MaxOpenConns is less than
989 // MaxIdleConns, then MaxIdleConns will be reduced to match the new
990 // MaxOpenConns limit.
992 // If n <= 0, then there is no limit on the number of open connections.
993 // The default is 0 (unlimited).
994 func (db
*DB
) SetMaxOpenConns(n
int) {
1000 syncMaxIdle
:= db
.maxOpen
> 0 && db
.maxIdleConnsLocked() > db
.maxOpen
1003 db
.SetMaxIdleConns(n
)
1007 // SetConnMaxLifetime sets the maximum amount of time a connection may be reused.
1009 // Expired connections may be closed lazily before reuse.
1011 // If d <= 0, connections are not closed due to a connection's age.
1012 func (db
*DB
) SetConnMaxLifetime(d time
.Duration
) {
1017 // Wake cleaner up when lifetime is shortened.
1018 if d
> 0 && d
< db
.maxLifetime
&& db
.cleanerCh
!= nil {
1020 case db
.cleanerCh
<- struct{}{}:
1025 db
.startCleanerLocked()
1029 // SetConnMaxIdleTime sets the maximum amount of time a connection may be idle.
1031 // Expired connections may be closed lazily before reuse.
1033 // If d <= 0, connections are not closed due to a connection's idle time.
1034 func (db
*DB
) SetConnMaxIdleTime(d time
.Duration
) {
1039 defer db
.mu
.Unlock()
1041 // Wake cleaner up when idle time is shortened.
1042 if d
> 0 && d
< db
.maxIdleTime
&& db
.cleanerCh
!= nil {
1044 case db
.cleanerCh
<- struct{}{}:
1049 db
.startCleanerLocked()
1052 // startCleanerLocked starts connectionCleaner if needed.
1053 func (db
*DB
) startCleanerLocked() {
1054 if (db
.maxLifetime
> 0 || db
.maxIdleTime
> 0) && db
.numOpen
> 0 && db
.cleanerCh
== nil {
1055 db
.cleanerCh
= make(chan struct{}, 1)
1056 go db
.connectionCleaner(db
.shortestIdleTimeLocked())
1060 func (db
*DB
) connectionCleaner(d time
.Duration
) {
1061 const minInterval
= time
.Second
1063 if d
< minInterval
{
1066 t
:= time
.NewTimer(d
)
1071 case <-db
.cleanerCh
: // maxLifetime was changed or db was closed.
1076 d
= db
.shortestIdleTimeLocked()
1077 if db
.closed || db
.numOpen
== 0 || d
<= 0 {
1083 d
, closing
:= db
.connectionCleanerRunLocked(d
)
1085 for _
, c
:= range closing
{
1089 if d
< minInterval
{
1103 // connectionCleanerRunLocked removes connections that should be closed from
1104 // freeConn and returns them along side an updated duration to the next check
1105 // if a quicker check is required to ensure connections are checked appropriately.
1106 func (db
*DB
) connectionCleanerRunLocked(d time
.Duration
) (time
.Duration
, []*driverConn
) {
1107 var idleClosing
int64
1108 var closing
[]*driverConn
1109 if db
.maxIdleTime
> 0 {
1110 // As freeConn is ordered by returnedAt process
1111 // in reverse order to minimise the work needed.
1112 idleSince
:= nowFunc().Add(-db
.maxIdleTime
)
1113 last
:= len(db
.freeConn
) - 1
1114 for i
:= last
; i
>= 0; i
-- {
1116 if c
.returnedAt
.Before(idleSince
) {
1118 closing
= db
.freeConn
[:i
:i
]
1119 db
.freeConn
= db
.freeConn
[i
:]
1120 idleClosing
= int64(len(closing
))
1121 db
.maxIdleTimeClosed
+= idleClosing
1126 if len(db
.freeConn
) > 0 {
1128 if d2
:= c
.returnedAt
.Sub(idleSince
); d2
< d
{
1129 // Ensure idle connections are cleaned up as soon as
1136 if db
.maxLifetime
> 0 {
1137 expiredSince
:= nowFunc().Add(-db
.maxLifetime
)
1138 for i
:= 0; i
< len(db
.freeConn
); i
++ {
1140 if c
.createdAt
.Before(expiredSince
) {
1141 closing
= append(closing
, c
)
1143 last
:= len(db
.freeConn
) - 1
1144 // Use slow delete as order is required to ensure
1145 // connections are reused least idle time first.
1146 copy(db
.freeConn
[i
:], db
.freeConn
[i
+1:])
1147 db
.freeConn
[last
] = nil
1148 db
.freeConn
= db
.freeConn
[:last
]
1150 } else if d2
:= c
.createdAt
.Sub(expiredSince
); d2
< d
{
1151 // Prevent connections sitting the freeConn when they
1152 // have expired by updating our next deadline d.
1156 db
.maxLifetimeClosed
+= int64(len(closing
)) - idleClosing
1162 // DBStats contains database statistics.
1163 type DBStats
struct {
1164 MaxOpenConnections
int // Maximum number of open connections to the database.
1167 OpenConnections
int // The number of established connections both in use and idle.
1168 InUse
int // The number of connections currently in use.
1169 Idle
int // The number of idle connections.
1172 WaitCount
int64 // The total number of connections waited for.
1173 WaitDuration time
.Duration
// The total time blocked waiting for a new connection.
1174 MaxIdleClosed
int64 // The total number of connections closed due to SetMaxIdleConns.
1175 MaxIdleTimeClosed
int64 // The total number of connections closed due to SetConnMaxIdleTime.
1176 MaxLifetimeClosed
int64 // The total number of connections closed due to SetConnMaxLifetime.
1179 // Stats returns database statistics.
1180 func (db
*DB
) Stats() DBStats
{
1181 wait
:= atomic
.LoadInt64(&db
.waitDuration
)
1184 defer db
.mu
.Unlock()
1187 MaxOpenConnections
: db
.maxOpen
,
1189 Idle
: len(db
.freeConn
),
1190 OpenConnections
: db
.numOpen
,
1191 InUse
: db
.numOpen
- len(db
.freeConn
),
1193 WaitCount
: db
.waitCount
,
1194 WaitDuration
: time
.Duration(wait
),
1195 MaxIdleClosed
: db
.maxIdleClosed
,
1196 MaxIdleTimeClosed
: db
.maxIdleTimeClosed
,
1197 MaxLifetimeClosed
: db
.maxLifetimeClosed
,
1202 // Assumes db.mu is locked.
1203 // If there are connRequests and the connection limit hasn't been reached,
1204 // then tell the connectionOpener to open new connections.
1205 func (db
*DB
) maybeOpenNewConnections() {
1206 numRequests
:= len(db
.connRequests
)
1208 numCanOpen
:= db
.maxOpen
- db
.numOpen
1209 if numRequests
> numCanOpen
{
1210 numRequests
= numCanOpen
1213 for numRequests
> 0 {
1214 db
.numOpen
++ // optimistically
1219 db
.openerCh
<- struct{}{}
1223 // Runs in a separate goroutine, opens new connections when requested.
1224 func (db
*DB
) connectionOpener(ctx context
.Context
) {
1230 db
.openNewConnection(ctx
)
1235 // Open one new connection
1236 func (db
*DB
) openNewConnection(ctx context
.Context
) {
1237 // maybeOpenNewConnections has already executed db.numOpen++ before it sent
1238 // on db.openerCh. This function must execute db.numOpen-- if the
1239 // connection fails or is closed before returning.
1240 ci
, err
:= db
.connector
.Connect(ctx
)
1242 defer db
.mu
.Unlock()
1252 db
.putConnDBLocked(nil, err
)
1253 db
.maybeOpenNewConnections()
1258 createdAt
: nowFunc(),
1259 returnedAt
: nowFunc(),
1262 if db
.putConnDBLocked(dc
, err
) {
1263 db
.addDepLocked(dc
, dc
)
1270 // connRequest represents one request for a new connection
1271 // When there are no idle connections available, DB.conn will create
1272 // a new connRequest and put it on the db.connRequests list.
1273 type connRequest
struct {
1278 var errDBClosed
= errors
.New("sql: database is closed")
1280 // nextRequestKeyLocked returns the next connection request key.
1281 // It is assumed that nextRequest will not overflow.
1282 func (db
*DB
) nextRequestKeyLocked() uint64 {
1283 next
:= db
.nextRequest
1288 // conn returns a newly-opened or cached *driverConn.
1289 func (db
*DB
) conn(ctx context
.Context
, strategy connReuseStrategy
) (*driverConn
, error
) {
1293 return nil, errDBClosed
1295 // Check if the context is expired.
1300 return nil, ctx
.Err()
1302 lifetime
:= db
.maxLifetime
1304 // Prefer a free connection, if possible.
1305 last
:= len(db
.freeConn
) - 1
1306 if strategy
== cachedOrNewConn
&& last
>= 0 {
1307 // Reuse the lowest idle time connection so we can close
1308 // connections which remain idle as soon as possible.
1309 conn
:= db
.freeConn
[last
]
1310 db
.freeConn
= db
.freeConn
[:last
]
1312 if conn
.expired(lifetime
) {
1313 db
.maxLifetimeClosed
++
1316 return nil, driver
.ErrBadConn
1320 // Reset the session if required.
1321 if err
:= conn
.resetSession(ctx
); errors
.Is(err
, driver
.ErrBadConn
) {
1329 // Out of free connections or we were asked not to use one. If we're not
1330 // allowed to open any more connections, make a request and wait.
1331 if db
.maxOpen
> 0 && db
.numOpen
>= db
.maxOpen
{
1332 // Make the connRequest channel. It's buffered so that the
1333 // connectionOpener doesn't block while waiting for the req to be read.
1334 req
:= make(chan connRequest
, 1)
1335 reqKey
:= db
.nextRequestKeyLocked()
1336 db
.connRequests
[reqKey
] = req
1340 waitStart
:= nowFunc()
1342 // Timeout the connection request with the context.
1345 // Remove the connection request and ensure no value has been sent
1346 // on it after removing.
1348 delete(db
.connRequests
, reqKey
)
1351 atomic
.AddInt64(&db
.waitDuration
, int64(time
.Since(waitStart
)))
1355 case ret
, ok
:= <-req
:
1356 if ok
&& ret
.conn
!= nil {
1357 db
.putConn(ret
.conn
, ret
.err
, false)
1360 return nil, ctx
.Err()
1361 case ret
, ok
:= <-req
:
1362 atomic
.AddInt64(&db
.waitDuration
, int64(time
.Since(waitStart
)))
1365 return nil, errDBClosed
1367 // Only check if the connection is expired if the strategy is cachedOrNewConns.
1368 // If we require a new connection, just re-use the connection without looking
1369 // at the expiry time. If it is expired, it will be checked when it is placed
1370 // back into the connection pool.
1371 // This prioritizes giving a valid connection to a client over the exact connection
1372 // lifetime, which could expire exactly after this point anyway.
1373 if strategy
== cachedOrNewConn
&& ret
.err
== nil && ret
.conn
.expired(lifetime
) {
1375 db
.maxLifetimeClosed
++
1378 return nil, driver
.ErrBadConn
1380 if ret
.conn
== nil {
1384 // Reset the session if required.
1385 if err
:= ret
.conn
.resetSession(ctx
); errors
.Is(err
, driver
.ErrBadConn
) {
1389 return ret
.conn
, ret
.err
1393 db
.numOpen
++ // optimistically
1395 ci
, err
:= db
.connector
.Connect(ctx
)
1398 db
.numOpen
-- // correct for earlier optimism
1399 db
.maybeOpenNewConnections()
1406 createdAt
: nowFunc(),
1407 returnedAt
: nowFunc(),
1411 db
.addDepLocked(dc
, dc
)
1416 // putConnHook is a hook for testing.
1417 var putConnHook
func(*DB
, *driverConn
)
1419 // noteUnusedDriverStatement notes that ds is no longer used and should
1420 // be closed whenever possible (when c is next not in use), unless c is
1422 func (db
*DB
) noteUnusedDriverStatement(c
*driverConn
, ds
*driverStmt
) {
1424 defer db
.mu
.Unlock()
1426 c
.onPut
= append(c
.onPut
, func() {
1439 // debugGetPut determines whether getConn & putConn calls' stack traces
1440 // are returned for more verbose crashes.
1441 const debugGetPut
= false
1443 // putConn adds a connection to the db's free pool.
1444 // err is optionally the last error that occurred on this connection.
1445 func (db
*DB
) putConn(dc
*driverConn
, err error
, resetSession
bool) {
1446 if !errors
.Is(err
, driver
.ErrBadConn
) {
1447 if !dc
.validateConnection(resetSession
) {
1448 err
= driver
.ErrBadConn
1455 fmt
.Printf("putConn(%v) DUPLICATE was: %s\n\nPREVIOUS was: %s", dc
, stack(), db
.lastPut
[dc
])
1457 panic("sql: connection returned that was never out")
1460 if !errors
.Is(err
, driver
.ErrBadConn
) && dc
.expired(db
.maxLifetime
) {
1461 db
.maxLifetimeClosed
++
1462 err
= driver
.ErrBadConn
1465 db
.lastPut
[dc
] = stack()
1468 dc
.returnedAt
= nowFunc()
1470 for _
, fn
:= range dc
.onPut
{
1475 if errors
.Is(err
, driver
.ErrBadConn
) {
1476 // Don't reuse bad connections.
1477 // Since the conn is considered bad and is being discarded, treat it
1478 // as closed. Don't decrement the open count here, finalClose will
1479 // take care of that.
1480 db
.maybeOpenNewConnections()
1485 if putConnHook
!= nil {
1488 added
:= db
.putConnDBLocked(dc
, nil)
1497 // Satisfy a connRequest or put the driverConn in the idle pool and return true
1499 // putConnDBLocked will satisfy a connRequest if there is one, or it will
1500 // return the *driverConn to the freeConn list if err == nil and the idle
1501 // connection limit will not be exceeded.
1502 // If err != nil, the value of dc is ignored.
1503 // If err == nil, then dc must not equal nil.
1504 // If a connRequest was fulfilled or the *driverConn was placed in the
1505 // freeConn list, then true is returned, otherwise false is returned.
1506 func (db
*DB
) putConnDBLocked(dc
*driverConn
, err error
) bool {
1510 if db
.maxOpen
> 0 && db
.numOpen
> db
.maxOpen
{
1513 if c
:= len(db
.connRequests
); c
> 0 {
1514 var req
chan connRequest
1516 for reqKey
, req
= range db
.connRequests
{
1519 delete(db
.connRequests
, reqKey
) // Remove from pending requests.
1528 } else if err
== nil && !db
.closed {
1529 if db
.maxIdleConnsLocked() > len(db
.freeConn
) {
1530 db
.freeConn
= append(db
.freeConn
, dc
)
1531 db
.startCleanerLocked()
1539 // maxBadConnRetries is the number of maximum retries if the driver returns
1540 // driver.ErrBadConn to signal a broken connection before forcing a new
1541 // connection to be opened.
1542 const maxBadConnRetries
= 2
1544 // PrepareContext creates a prepared statement for later queries or executions.
1545 // Multiple queries or executions may be run concurrently from the
1546 // returned statement.
1547 // The caller must call the statement's Close method
1548 // when the statement is no longer needed.
1550 // The provided context is used for the preparation of the statement, not for the
1551 // execution of the statement.
1552 func (db
*DB
) PrepareContext(ctx context
.Context
, query
string) (*Stmt
, error
) {
1556 for i
:= 0; i
< maxBadConnRetries
; i
++ {
1557 stmt
, err
= db
.prepare(ctx
, query
, cachedOrNewConn
)
1558 isBadConn
= errors
.Is(err
, driver
.ErrBadConn
)
1564 return db
.prepare(ctx
, query
, alwaysNewConn
)
1569 // Prepare creates a prepared statement for later queries or executions.
1570 // Multiple queries or executions may be run concurrently from the
1571 // returned statement.
1572 // The caller must call the statement's Close method
1573 // when the statement is no longer needed.
1575 // Prepare uses context.Background internally; to specify the context, use
1577 func (db
*DB
) Prepare(query
string) (*Stmt
, error
) {
1578 return db
.PrepareContext(context
.Background(), query
)
1581 func (db
*DB
) prepare(ctx context
.Context
, query
string, strategy connReuseStrategy
) (*Stmt
, error
) {
1582 // TODO: check if db.driver supports an optional
1583 // driver.Preparer interface and call that instead, if so,
1584 // otherwise we make a prepared statement that's bound
1585 // to a connection, and to execute this prepared statement
1586 // we either need to use this connection (if it's free), else
1587 // get a new connection + re-prepare + execute on that one.
1588 dc
, err
:= db
.conn(ctx
, strategy
)
1592 return db
.prepareDC(ctx
, dc
, dc
.releaseConn
, nil, query
)
1595 // prepareDC prepares a query on the driverConn and calls release before
1596 // returning. When cg == nil it implies that a connection pool is used, and
1597 // when cg != nil only a single driver connection is used.
1598 func (db
*DB
) prepareDC(ctx context
.Context
, dc
*driverConn
, release
func(error
), cg stmtConnGrabber
, query
string) (*Stmt
, error
) {
1604 withLock(dc
, func() {
1605 ds
, err
= dc
.prepareLocked(ctx
, cg
, query
)
1617 // When cg == nil this statement will need to keep track of various
1618 // connections they are prepared on and record the stmt dependency on
1621 stmt
.css
= []connStmt
{{dc
, ds
}}
1622 stmt
.lastNumClosed
= atomic
.LoadUint64(&db
.numClosed
)
1623 db
.addDep(stmt
, stmt
)
1628 // ExecContext executes a query without returning any rows.
1629 // The args are for any placeholder parameters in the query.
1630 func (db
*DB
) ExecContext(ctx context
.Context
, query
string, args
...any
) (Result
, error
) {
1634 for i
:= 0; i
< maxBadConnRetries
; i
++ {
1635 res
, err
= db
.exec(ctx
, query
, args
, cachedOrNewConn
)
1636 isBadConn
= errors
.Is(err
, driver
.ErrBadConn
)
1642 return db
.exec(ctx
, query
, args
, alwaysNewConn
)
1647 // Exec executes a query without returning any rows.
1648 // The args are for any placeholder parameters in the query.
1650 // Exec uses context.Background internally; to specify the context, use
1652 func (db
*DB
) Exec(query
string, args
...any
) (Result
, error
) {
1653 return db
.ExecContext(context
.Background(), query
, args
...)
1656 func (db
*DB
) exec(ctx context
.Context
, query
string, args
[]any
, strategy connReuseStrategy
) (Result
, error
) {
1657 dc
, err
:= db
.conn(ctx
, strategy
)
1661 return db
.execDC(ctx
, dc
, dc
.releaseConn
, query
, args
)
1664 func (db
*DB
) execDC(ctx context
.Context
, dc
*driverConn
, release
func(error
), query
string, args
[]any
) (res Result
, err error
) {
1668 execerCtx
, ok
:= dc
.ci
.(driver
.ExecerContext
)
1669 var execer driver
.Execer
1671 execer
, ok
= dc
.ci
.(driver
.Execer
)
1674 var nvdargs
[]driver
.NamedValue
1675 var resi driver
.Result
1676 withLock(dc
, func() {
1677 nvdargs
, err
= driverArgsConnLocked(dc
.ci
, nil, args
)
1681 resi
, err
= ctxDriverExec(ctx
, execerCtx
, execer
, query
, nvdargs
)
1683 if err
!= driver
.ErrSkip
{
1687 return driverResult
{dc
, resi
}, nil
1692 withLock(dc
, func() {
1693 si
, err
= ctxDriverPrepare(ctx
, dc
.ci
, query
)
1698 ds
:= &driverStmt
{Locker
: dc
, si
: si
}
1700 return resultFromStatement(ctx
, dc
.ci
, ds
, args
...)
1703 // QueryContext executes a query that returns rows, typically a SELECT.
1704 // The args are for any placeholder parameters in the query.
1705 func (db
*DB
) QueryContext(ctx context
.Context
, query
string, args
...any
) (*Rows
, error
) {
1709 for i
:= 0; i
< maxBadConnRetries
; i
++ {
1710 rows
, err
= db
.query(ctx
, query
, args
, cachedOrNewConn
)
1711 isBadConn
= errors
.Is(err
, driver
.ErrBadConn
)
1717 return db
.query(ctx
, query
, args
, alwaysNewConn
)
1722 // Query executes a query that returns rows, typically a SELECT.
1723 // The args are for any placeholder parameters in the query.
1725 // Query uses context.Background internally; to specify the context, use
1727 func (db
*DB
) Query(query
string, args
...any
) (*Rows
, error
) {
1728 return db
.QueryContext(context
.Background(), query
, args
...)
1731 func (db
*DB
) query(ctx context
.Context
, query
string, args
[]any
, strategy connReuseStrategy
) (*Rows
, error
) {
1732 dc
, err
:= db
.conn(ctx
, strategy
)
1737 return db
.queryDC(ctx
, nil, dc
, dc
.releaseConn
, query
, args
)
1740 // queryDC executes a query on the given connection.
1741 // The connection gets released by the releaseConn function.
1742 // The ctx context is from a query method and the txctx context is from an
1743 // optional transaction context.
1744 func (db
*DB
) queryDC(ctx
, txctx context
.Context
, dc
*driverConn
, releaseConn
func(error
), query
string, args
[]any
) (*Rows
, error
) {
1745 queryerCtx
, ok
:= dc
.ci
.(driver
.QueryerContext
)
1746 var queryer driver
.Queryer
1748 queryer
, ok
= dc
.ci
.(driver
.Queryer
)
1751 var nvdargs
[]driver
.NamedValue
1752 var rowsi driver
.Rows
1754 withLock(dc
, func() {
1755 nvdargs
, err
= driverArgsConnLocked(dc
.ci
, nil, args
)
1759 rowsi
, err
= ctxDriverQuery(ctx
, queryerCtx
, queryer
, query
, nvdargs
)
1761 if err
!= driver
.ErrSkip
{
1766 // Note: ownership of dc passes to the *Rows, to be freed
1767 // with releaseConn.
1770 releaseConn
: releaseConn
,
1773 rows
.initContextClose(ctx
, txctx
)
1780 withLock(dc
, func() {
1781 si
, err
= ctxDriverPrepare(ctx
, dc
.ci
, query
)
1788 ds
:= &driverStmt
{Locker
: dc
, si
: si
}
1789 rowsi
, err
:= rowsiFromStatement(ctx
, dc
.ci
, ds
, args
...)
1796 // Note: ownership of ci passes to the *Rows, to be freed
1797 // with releaseConn.
1800 releaseConn
: releaseConn
,
1804 rows
.initContextClose(ctx
, txctx
)
1808 // QueryRowContext executes a query that is expected to return at most one row.
1809 // QueryRowContext always returns a non-nil value. Errors are deferred until
1810 // Row's Scan method is called.
1811 // If the query selects no rows, the *Row's Scan will return ErrNoRows.
1812 // Otherwise, the *Row's Scan scans the first selected row and discards
1814 func (db
*DB
) QueryRowContext(ctx context
.Context
, query
string, args
...any
) *Row
{
1815 rows
, err
:= db
.QueryContext(ctx
, query
, args
...)
1816 return &Row
{rows
: rows
, err
: err
}
1819 // QueryRow executes a query that is expected to return at most one row.
1820 // QueryRow always returns a non-nil value. Errors are deferred until
1821 // Row's Scan method is called.
1822 // If the query selects no rows, the *Row's Scan will return ErrNoRows.
1823 // Otherwise, the *Row's Scan scans the first selected row and discards
1826 // QueryRow uses context.Background internally; to specify the context, use
1828 func (db
*DB
) QueryRow(query
string, args
...any
) *Row
{
1829 return db
.QueryRowContext(context
.Background(), query
, args
...)
1832 // BeginTx starts a transaction.
1834 // The provided context is used until the transaction is committed or rolled back.
1835 // If the context is canceled, the sql package will roll back
1836 // the transaction. Tx.Commit will return an error if the context provided to
1837 // BeginTx is canceled.
1839 // The provided TxOptions is optional and may be nil if defaults should be used.
1840 // If a non-default isolation level is used that the driver doesn't support,
1841 // an error will be returned.
1842 func (db
*DB
) BeginTx(ctx context
.Context
, opts
*TxOptions
) (*Tx
, error
) {
1846 for i
:= 0; i
< maxBadConnRetries
; i
++ {
1847 tx
, err
= db
.begin(ctx
, opts
, cachedOrNewConn
)
1848 isBadConn
= errors
.Is(err
, driver
.ErrBadConn
)
1854 return db
.begin(ctx
, opts
, alwaysNewConn
)
1859 // Begin starts a transaction. The default isolation level is dependent on
1862 // Begin uses context.Background internally; to specify the context, use
1864 func (db
*DB
) Begin() (*Tx
, error
) {
1865 return db
.BeginTx(context
.Background(), nil)
1868 func (db
*DB
) begin(ctx context
.Context
, opts
*TxOptions
, strategy connReuseStrategy
) (tx
*Tx
, err error
) {
1869 dc
, err
:= db
.conn(ctx
, strategy
)
1873 return db
.beginDC(ctx
, dc
, dc
.releaseConn
, opts
)
1876 // beginDC starts a transaction. The provided dc must be valid and ready to use.
1877 func (db
*DB
) beginDC(ctx context
.Context
, dc
*driverConn
, release
func(error
), opts
*TxOptions
) (tx
*Tx
, err error
) {
1879 keepConnOnRollback
:= false
1880 withLock(dc
, func() {
1881 _
, hasSessionResetter
:= dc
.ci
.(driver
.SessionResetter
)
1882 _
, hasConnectionValidator
:= dc
.ci
.(driver
.Validator
)
1883 keepConnOnRollback
= hasSessionResetter
&& hasConnectionValidator
1884 txi
, err
= ctxDriverBegin(ctx
, opts
, dc
.ci
)
1891 // Schedule the transaction to rollback when the context is canceled.
1892 // The cancel function in Tx will be called after done is set to true.
1893 ctx
, cancel
:= context
.WithCancel(ctx
)
1897 releaseConn
: release
,
1900 keepConnOnRollback
: keepConnOnRollback
,
1907 // Driver returns the database's underlying driver.
1908 func (db
*DB
) Driver() driver
.Driver
{
1909 return db
.connector
.Driver()
1912 // ErrConnDone is returned by any operation that is performed on a connection
1913 // that has already been returned to the connection pool.
1914 var ErrConnDone
= errors
.New("sql: connection is already closed")
1916 // Conn returns a single connection by either opening a new connection
1917 // or returning an existing connection from the connection pool. Conn will
1918 // block until either a connection is returned or ctx is canceled.
1919 // Queries run on the same Conn will be run in the same database session.
1921 // Every Conn must be returned to the database pool after use by
1922 // calling Conn.Close.
1923 func (db
*DB
) Conn(ctx context
.Context
) (*Conn
, error
) {
1927 for i
:= 0; i
< maxBadConnRetries
; i
++ {
1928 dc
, err
= db
.conn(ctx
, cachedOrNewConn
)
1929 isBadConn
= errors
.Is(err
, driver
.ErrBadConn
)
1935 dc
, err
= db
.conn(ctx
, alwaysNewConn
)
1948 type releaseConn
func(error
)
1950 // Conn represents a single database connection rather than a pool of database
1951 // connections. Prefer running queries from DB unless there is a specific
1952 // need for a continuous single database connection.
1954 // A Conn must call Close to return the connection to the database pool
1955 // and may do so concurrently with a running query.
1957 // After a call to Close, all operations on the
1958 // connection fail with ErrConnDone.
1962 // closemu prevents the connection from closing while there
1963 // is an active query. It is held for read during queries
1964 // and exclusively during close.
1965 closemu sync
.RWMutex
1967 // dc is owned until close, at which point
1968 // it's returned to the connection pool.
1971 // done transitions from 0 to 1 exactly once, on close.
1972 // Once done, all operations fail with ErrConnDone.
1973 // Use atomic operations on value when checking value.
1977 // grabConn takes a context to implement stmtConnGrabber
1978 // but the context is not used.
1979 func (c
*Conn
) grabConn(context
.Context
) (*driverConn
, releaseConn
, error
) {
1980 if atomic
.LoadInt32(&c
.done
) != 0 {
1981 return nil, nil, ErrConnDone
1984 return c
.dc
, c
.closemuRUnlockCondReleaseConn
, nil
1987 // PingContext verifies the connection to the database is still alive.
1988 func (c
*Conn
) PingContext(ctx context
.Context
) error
{
1989 dc
, release
, err
:= c
.grabConn(ctx
)
1993 return c
.db
.pingDC(ctx
, dc
, release
)
1996 // ExecContext executes a query without returning any rows.
1997 // The args are for any placeholder parameters in the query.
1998 func (c
*Conn
) ExecContext(ctx context
.Context
, query
string, args
...any
) (Result
, error
) {
1999 dc
, release
, err
:= c
.grabConn(ctx
)
2003 return c
.db
.execDC(ctx
, dc
, release
, query
, args
)
2006 // QueryContext executes a query that returns rows, typically a SELECT.
2007 // The args are for any placeholder parameters in the query.
2008 func (c
*Conn
) QueryContext(ctx context
.Context
, query
string, args
...any
) (*Rows
, error
) {
2009 dc
, release
, err
:= c
.grabConn(ctx
)
2013 return c
.db
.queryDC(ctx
, nil, dc
, release
, query
, args
)
2016 // QueryRowContext executes a query that is expected to return at most one row.
2017 // QueryRowContext always returns a non-nil value. Errors are deferred until
2018 // Row's Scan method is called.
2019 // If the query selects no rows, the *Row's Scan will return ErrNoRows.
2020 // Otherwise, the *Row's Scan scans the first selected row and discards
2022 func (c
*Conn
) QueryRowContext(ctx context
.Context
, query
string, args
...any
) *Row
{
2023 rows
, err
:= c
.QueryContext(ctx
, query
, args
...)
2024 return &Row
{rows
: rows
, err
: err
}
2027 // PrepareContext creates a prepared statement for later queries or executions.
2028 // Multiple queries or executions may be run concurrently from the
2029 // returned statement.
2030 // The caller must call the statement's Close method
2031 // when the statement is no longer needed.
2033 // The provided context is used for the preparation of the statement, not for the
2034 // execution of the statement.
2035 func (c
*Conn
) PrepareContext(ctx context
.Context
, query
string) (*Stmt
, error
) {
2036 dc
, release
, err
:= c
.grabConn(ctx
)
2040 return c
.db
.prepareDC(ctx
, dc
, release
, c
, query
)
2043 // Raw executes f exposing the underlying driver connection for the
2044 // duration of f. The driverConn must not be used outside of f.
2046 // Once f returns and err is not driver.ErrBadConn, the Conn will continue to be usable
2047 // until Conn.Close is called.
2048 func (c
*Conn
) Raw(f
func(driverConn any
) error
) (err error
) {
2050 var release releaseConn
2052 // grabConn takes a context to implement stmtConnGrabber, but the context is not used.
2053 dc
, release
, err
= c
.grabConn(nil)
2062 // If f panics fPanic will remain true.
2063 // Ensure an error is passed to release so the connection
2064 // may be discarded.
2066 err
= driver
.ErrBadConn
2076 // BeginTx starts a transaction.
2078 // The provided context is used until the transaction is committed or rolled back.
2079 // If the context is canceled, the sql package will roll back
2080 // the transaction. Tx.Commit will return an error if the context provided to
2081 // BeginTx is canceled.
2083 // The provided TxOptions is optional and may be nil if defaults should be used.
2084 // If a non-default isolation level is used that the driver doesn't support,
2085 // an error will be returned.
2086 func (c
*Conn
) BeginTx(ctx context
.Context
, opts
*TxOptions
) (*Tx
, error
) {
2087 dc
, release
, err
:= c
.grabConn(ctx
)
2091 return c
.db
.beginDC(ctx
, dc
, release
, opts
)
2094 // closemuRUnlockCondReleaseConn read unlocks closemu
2095 // as the sql operation is done with the dc.
2096 func (c
*Conn
) closemuRUnlockCondReleaseConn(err error
) {
2098 if errors
.Is(err
, driver
.ErrBadConn
) {
2103 func (c
*Conn
) txCtx() context
.Context
{
2107 func (c
*Conn
) close(err error
) error
{
2108 if !atomic
.CompareAndSwapInt32(&c
.done
, 0, 1) {
2112 // Lock around releasing the driver connection
2113 // to ensure all queries have been stopped before doing so.
2115 defer c
.closemu
.Unlock()
2117 c
.dc
.releaseConn(err
)
2123 // Close returns the connection to the connection pool.
2124 // All operations after a Close will return with ErrConnDone.
2125 // Close is safe to call concurrently with other operations and will
2126 // block until all other operations finish. It may be useful to first
2127 // cancel any used context and then call close directly after.
2128 func (c
*Conn
) Close() error
{
2132 // Tx is an in-progress database transaction.
2134 // A transaction must end with a call to Commit or Rollback.
2136 // After a call to Commit or Rollback, all operations on the
2137 // transaction fail with ErrTxDone.
2139 // The statements prepared for a transaction by calling
2140 // the transaction's Prepare or Stmt methods are closed
2141 // by the call to Commit or Rollback.
2145 // closemu prevents the transaction from closing while there
2146 // is an active query. It is held for read during queries
2147 // and exclusively during close.
2148 closemu sync
.RWMutex
2150 // dc is owned exclusively until Commit or Rollback, at which point
2151 // it's returned with putConn.
2155 // releaseConn is called once the Tx is closed to release
2156 // any held driverConn back to the pool.
2157 releaseConn
func(error
)
2159 // done transitions from 0 to 1 exactly once, on Commit
2160 // or Rollback. once done, all operations fail with
2162 // Use atomic operations on value when checking value.
2165 // keepConnOnRollback is true if the driver knows
2166 // how to reset the connection's session and if need be discard
2168 keepConnOnRollback
bool
2170 // All Stmts prepared for this transaction. These will be closed after the
2171 // transaction has been committed or rolled back.
2177 // cancel is called after done transitions from 0 to 1.
2180 // ctx lives for the life of the transaction.
2184 // awaitDone blocks until the context in Tx is canceled and rolls back
2185 // the transaction if it's not already done.
2186 func (tx
*Tx
) awaitDone() {
2187 // Wait for either the transaction to be committed or rolled
2188 // back, or for the associated context to be closed.
2191 // Discard and close the connection used to ensure the
2192 // transaction is closed and the resources are released. This
2193 // rollback does nothing if the transaction has already been
2194 // committed or rolled back.
2195 // Do not discard the connection if the connection knows
2196 // how to reset the session.
2197 discardConnection
:= !tx
.keepConnOnRollback
2198 tx
.rollback(discardConnection
)
2201 func (tx
*Tx
) isDone() bool {
2202 return atomic
.LoadInt32(&tx
.done
) != 0
2205 // ErrTxDone is returned by any operation that is performed on a transaction
2206 // that has already been committed or rolled back.
2207 var ErrTxDone
= errors
.New("sql: transaction has already been committed or rolled back")
2209 // close returns the connection to the pool and
2210 // must only be called by Tx.rollback or Tx.Commit while
2211 // tx is already canceled and won't be executed concurrently.
2212 func (tx
*Tx
) close(err error
) {
2218 // hookTxGrabConn specifies an optional hook to be called on
2219 // a successful call to (*Tx).grabConn. For tests.
2220 var hookTxGrabConn
func()
2222 func (tx
*Tx
) grabConn(ctx context
.Context
) (*driverConn
, releaseConn
, error
) {
2226 return nil, nil, ctx
.Err()
2229 // closemu.RLock must come before the check for isDone to prevent the Tx from
2230 // closing while a query is executing.
2233 tx
.closemu
.RUnlock()
2234 return nil, nil, ErrTxDone
2236 if hookTxGrabConn
!= nil { // test hook
2239 return tx
.dc
, tx
.closemuRUnlockRelease
, nil
2242 func (tx
*Tx
) txCtx() context
.Context
{
2246 // closemuRUnlockRelease is used as a func(error) method value in
2247 // ExecContext and QueryContext. Unlocking in the releaseConn keeps
2248 // the driver conn from being returned to the connection pool until
2249 // the Rows has been closed.
2250 func (tx
*Tx
) closemuRUnlockRelease(error
) {
2251 tx
.closemu
.RUnlock()
2254 // Closes all Stmts prepared for this transaction.
2255 func (tx
*Tx
) closePrepared() {
2257 defer tx
.stmts
.Unlock()
2258 for _
, stmt
:= range tx
.stmts
.v
{
2263 // Commit commits the transaction.
2264 func (tx
*Tx
) Commit() error
{
2265 // Check context first to avoid transaction leak.
2266 // If put it behind tx.done CompareAndSwap statement, we can't ensure
2267 // the consistency between tx.done and the real COMMIT operation.
2270 case <-tx
.ctx
.Done():
2271 if atomic
.LoadInt32(&tx
.done
) == 1 {
2276 if !atomic
.CompareAndSwapInt32(&tx
.done
, 0, 1) {
2280 // Cancel the Tx to release any active R-closemu locks.
2281 // This is safe to do because tx.done has already transitioned
2282 // from 0 to 1. Hold the W-closemu lock prior to rollback
2283 // to ensure no other connection has an active query.
2289 withLock(tx
.dc
, func() {
2290 err
= tx
.txi
.Commit()
2292 if !errors
.Is(err
, driver
.ErrBadConn
) {
2299 var rollbackHook
func()
2301 // rollback aborts the transaction and optionally forces the pool to discard
2303 func (tx
*Tx
) rollback(discardConn
bool) error
{
2304 if !atomic
.CompareAndSwapInt32(&tx
.done
, 0, 1) {
2308 if rollbackHook
!= nil {
2312 // Cancel the Tx to release any active R-closemu locks.
2313 // This is safe to do because tx.done has already transitioned
2314 // from 0 to 1. Hold the W-closemu lock prior to rollback
2315 // to ensure no other connection has an active query.
2321 withLock(tx
.dc
, func() {
2322 err
= tx
.txi
.Rollback()
2324 if !errors
.Is(err
, driver
.ErrBadConn
) {
2328 err
= driver
.ErrBadConn
2334 // Rollback aborts the transaction.
2335 func (tx
*Tx
) Rollback() error
{
2336 return tx
.rollback(false)
2339 // PrepareContext creates a prepared statement for use within a transaction.
2341 // The returned statement operates within the transaction and will be closed
2342 // when the transaction has been committed or rolled back.
2344 // To use an existing prepared statement on this transaction, see Tx.Stmt.
2346 // The provided context will be used for the preparation of the context, not
2347 // for the execution of the returned statement. The returned statement
2348 // will run in the transaction context.
2349 func (tx
*Tx
) PrepareContext(ctx context
.Context
, query
string) (*Stmt
, error
) {
2350 dc
, release
, err
:= tx
.grabConn(ctx
)
2355 stmt
, err
:= tx
.db
.prepareDC(ctx
, dc
, release
, tx
, query
)
2360 tx
.stmts
.v
= append(tx
.stmts
.v
, stmt
)
2365 // Prepare creates a prepared statement for use within a transaction.
2367 // The returned statement operates within the transaction and will be closed
2368 // when the transaction has been committed or rolled back.
2370 // To use an existing prepared statement on this transaction, see Tx.Stmt.
2372 // Prepare uses context.Background internally; to specify the context, use
2374 func (tx
*Tx
) Prepare(query
string) (*Stmt
, error
) {
2375 return tx
.PrepareContext(context
.Background(), query
)
2378 // StmtContext returns a transaction-specific prepared statement from
2379 // an existing statement.
2382 // updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")
2384 // tx, err := db.Begin()
2386 // res, err := tx.StmtContext(ctx, updateMoney).Exec(123.45, 98293203)
2388 // The provided context is used for the preparation of the statement, not for the
2389 // execution of the statement.
2391 // The returned statement operates within the transaction and will be closed
2392 // when the transaction has been committed or rolled back.
2393 func (tx
*Tx
) StmtContext(ctx context
.Context
, stmt
*Stmt
) *Stmt
{
2394 dc
, release
, err
:= tx
.grabConn(ctx
)
2396 return &Stmt
{stickyErr
: err
}
2400 if tx
.db
!= stmt
.db
{
2401 return &Stmt
{stickyErr
: errors
.New("sql: Tx.Stmt: statement from different database used")}
2404 var parentStmt
*Stmt
2406 if stmt
.closed || stmt
.cg
!= nil {
2407 // If the statement has been closed or already belongs to a
2408 // transaction, we can't reuse it in this connection.
2409 // Since tx.StmtContext should never need to be called with a
2410 // Stmt already belonging to tx, we ignore this edge case and
2411 // re-prepare the statement in this case. No need to add
2412 // code-complexity for this.
2414 withLock(dc
, func() {
2415 si
, err
= ctxDriverPrepare(ctx
, dc
.ci
, stmt
.query
)
2418 return &Stmt
{stickyErr
: err
}
2421 stmt
.removeClosedStmtLocked()
2422 // See if the statement has already been prepared on this connection,
2423 // and reuse it if possible.
2424 for _
, v
:= range stmt
.css
{
2435 withLock(dc
, func() {
2436 ds
, err
= stmt
.prepareOnConnLocked(ctx
, dc
)
2439 return &Stmt
{stickyErr
: err
}
2453 parentStmt
: parentStmt
,
2456 if parentStmt
!= nil {
2457 tx
.db
.addDep(parentStmt
, txs
)
2460 tx
.stmts
.v
= append(tx
.stmts
.v
, txs
)
2465 // Stmt returns a transaction-specific prepared statement from
2466 // an existing statement.
2469 // updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")
2471 // tx, err := db.Begin()
2473 // res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203)
2475 // The returned statement operates within the transaction and will be closed
2476 // when the transaction has been committed or rolled back.
2478 // Stmt uses context.Background internally; to specify the context, use
2480 func (tx
*Tx
) Stmt(stmt
*Stmt
) *Stmt
{
2481 return tx
.StmtContext(context
.Background(), stmt
)
2484 // ExecContext executes a query that doesn't return rows.
2485 // For example: an INSERT and UPDATE.
2486 func (tx
*Tx
) ExecContext(ctx context
.Context
, query
string, args
...any
) (Result
, error
) {
2487 dc
, release
, err
:= tx
.grabConn(ctx
)
2491 return tx
.db
.execDC(ctx
, dc
, release
, query
, args
)
2494 // Exec executes a query that doesn't return rows.
2495 // For example: an INSERT and UPDATE.
2497 // Exec uses context.Background internally; to specify the context, use
2499 func (tx
*Tx
) Exec(query
string, args
...any
) (Result
, error
) {
2500 return tx
.ExecContext(context
.Background(), query
, args
...)
2503 // QueryContext executes a query that returns rows, typically a SELECT.
2504 func (tx
*Tx
) QueryContext(ctx context
.Context
, query
string, args
...any
) (*Rows
, error
) {
2505 dc
, release
, err
:= tx
.grabConn(ctx
)
2510 return tx
.db
.queryDC(ctx
, tx
.ctx
, dc
, release
, query
, args
)
2513 // Query executes a query that returns rows, typically a SELECT.
2515 // Query uses context.Background internally; to specify the context, use
2517 func (tx
*Tx
) Query(query
string, args
...any
) (*Rows
, error
) {
2518 return tx
.QueryContext(context
.Background(), query
, args
...)
2521 // QueryRowContext executes a query that is expected to return at most one row.
2522 // QueryRowContext always returns a non-nil value. Errors are deferred until
2523 // Row's Scan method is called.
2524 // If the query selects no rows, the *Row's Scan will return ErrNoRows.
2525 // Otherwise, the *Row's Scan scans the first selected row and discards
2527 func (tx
*Tx
) QueryRowContext(ctx context
.Context
, query
string, args
...any
) *Row
{
2528 rows
, err
:= tx
.QueryContext(ctx
, query
, args
...)
2529 return &Row
{rows
: rows
, err
: err
}
2532 // QueryRow executes a query that is expected to return at most one row.
2533 // QueryRow always returns a non-nil value. Errors are deferred until
2534 // Row's Scan method is called.
2535 // If the query selects no rows, the *Row's Scan will return ErrNoRows.
2536 // Otherwise, the *Row's Scan scans the first selected row and discards
2539 // QueryRow uses context.Background internally; to specify the context, use
2541 func (tx
*Tx
) QueryRow(query
string, args
...any
) *Row
{
2542 return tx
.QueryRowContext(context
.Background(), query
, args
...)
2545 // connStmt is a prepared statement on a particular connection.
2546 type connStmt
struct {
2551 // stmtConnGrabber represents a Tx or Conn that will return the underlying
2552 // driverConn and release function.
2553 type stmtConnGrabber
interface {
2554 // grabConn returns the driverConn and the associated release function
2555 // that must be called when the operation completes.
2556 grabConn(context
.Context
) (*driverConn
, releaseConn
, error
)
2558 // txCtx returns the transaction context if available.
2559 // The returned context should be selected on along with
2560 // any query context when awaiting a cancel.
2561 txCtx() context
.Context
2565 _ stmtConnGrabber
= &Tx
{}
2566 _ stmtConnGrabber
= &Conn
{}
2569 // Stmt is a prepared statement.
2570 // A Stmt is safe for concurrent use by multiple goroutines.
2572 // If a Stmt is prepared on a Tx or Conn, it will be bound to a single
2573 // underlying connection forever. If the Tx or Conn closes, the Stmt will
2574 // become unusable and all operations will return an error.
2575 // If a Stmt is prepared on a DB, it will remain usable for the lifetime of the
2576 // DB. When the Stmt needs to execute on a new underlying connection, it will
2577 // prepare itself on the new connection automatically.
2580 db
*DB
// where we came from
2581 query
string // that created the Stmt
2582 stickyErr error
// if non-nil, this error is returned for all operations
2584 closemu sync
.RWMutex
// held exclusively during close, for read otherwise.
2586 // If Stmt is prepared on a Tx or Conn then cg is present and will
2587 // only ever grab a connection from cg.
2588 // If cg is nil then the Stmt must grab an arbitrary connection
2589 // from db and determine if it must prepare the stmt again by
2594 // parentStmt is set when a transaction-specific statement
2595 // is requested from an identical statement prepared on the same
2596 // conn. parentStmt is used to track the dependency of this statement
2597 // on its originating ("parent") statement so that parentStmt may
2598 // be closed by the user without them having to know whether or not
2599 // any transactions are still using it.
2602 mu sync
.Mutex
// protects the rest of the fields
2605 // css is a list of underlying driver statement interfaces
2606 // that are valid on particular connections. This is only
2607 // used if cg == nil and one is found that has idle
2608 // connections. If cg != nil, cgds is always used.
2611 // lastNumClosed is copied from db.numClosed when Stmt is created
2612 // without tx and closed connections in css are removed.
2613 lastNumClosed
uint64
2616 // ExecContext executes a prepared statement with the given arguments and
2617 // returns a Result summarizing the effect of the statement.
2618 func (s
*Stmt
) ExecContext(ctx context
.Context
, args
...any
) (Result
, error
) {
2620 defer s
.closemu
.RUnlock()
2623 strategy
:= cachedOrNewConn
2624 for i
:= 0; i
< maxBadConnRetries
+1; i
++ {
2625 if i
== maxBadConnRetries
{
2626 strategy
= alwaysNewConn
2628 dc
, releaseConn
, ds
, err
:= s
.connStmt(ctx
, strategy
)
2630 if errors
.Is(err
, driver
.ErrBadConn
) {
2636 res
, err
= resultFromStatement(ctx
, dc
.ci
, ds
, args
...)
2638 if !errors
.Is(err
, driver
.ErrBadConn
) {
2642 return nil, driver
.ErrBadConn
2645 // Exec executes a prepared statement with the given arguments and
2646 // returns a Result summarizing the effect of the statement.
2648 // Exec uses context.Background internally; to specify the context, use
2650 func (s
*Stmt
) Exec(args
...any
) (Result
, error
) {
2651 return s
.ExecContext(context
.Background(), args
...)
2654 func resultFromStatement(ctx context
.Context
, ci driver
.Conn
, ds
*driverStmt
, args
...any
) (Result
, error
) {
2658 dargs
, err
:= driverArgsConnLocked(ci
, ds
, args
)
2663 resi
, err
:= ctxDriverStmtExec(ctx
, ds
.si
, dargs
)
2667 return driverResult
{ds
.Locker
, resi
}, nil
2670 // removeClosedStmtLocked removes closed conns in s.css.
2672 // To avoid lock contention on DB.mu, we do it only when
2673 // s.db.numClosed - s.lastNum is large enough.
2674 func (s
*Stmt
) removeClosedStmtLocked() {
2675 t
:= len(s
.css
)/2 + 1
2679 dbClosed
:= atomic
.LoadUint64(&s
.db
.numClosed
)
2680 if dbClosed
-s
.lastNumClosed
< uint64(t
) {
2685 for i
:= 0; i
< len(s
.css
); i
++ {
2686 if s
.css
[i
].dc
.dbmuClosed
{
2687 s
.css
[i
] = s
.css
[len(s
.css
)-1]
2688 s
.css
= s
.css
[:len(s
.css
)-1]
2693 s
.lastNumClosed
= dbClosed
2696 // connStmt returns a free driver connection on which to execute the
2697 // statement, a function to call to release the connection, and a
2698 // statement bound to that connection.
2699 func (s
*Stmt
) connStmt(ctx context
.Context
, strategy connReuseStrategy
) (dc
*driverConn
, releaseConn
func(error
), ds
*driverStmt
, err error
) {
2700 if err
= s
.stickyErr
; err
!= nil {
2706 err
= errors
.New("sql: statement is closed")
2710 // In a transaction or connection, we always use the connection that the
2711 // stmt was created on.
2714 dc
, releaseConn
, err
= s
.cg
.grabConn(ctx
) // blocks, waiting for the connection.
2718 return dc
, releaseConn
, s
.cgds
, nil
2721 s
.removeClosedStmtLocked()
2724 dc
, err
= s
.db
.conn(ctx
, strategy
)
2726 return nil, nil, nil, err
2730 for _
, v
:= range s
.css
{
2733 return dc
, dc
.releaseConn
, v
.ds
, nil
2738 // No luck; we need to prepare the statement on this connection
2739 withLock(dc
, func() {
2740 ds
, err
= s
.prepareOnConnLocked(ctx
, dc
)
2744 return nil, nil, nil, err
2747 return dc
, dc
.releaseConn
, ds
, nil
2750 // prepareOnConnLocked prepares the query in Stmt s on dc and adds it to the list of
2751 // open connStmt on the statement. It assumes the caller is holding the lock on dc.
2752 func (s
*Stmt
) prepareOnConnLocked(ctx context
.Context
, dc
*driverConn
) (*driverStmt
, error
) {
2753 si
, err
:= dc
.prepareLocked(ctx
, s
.cg
, s
.query
)
2757 cs
:= connStmt
{dc
, si
}
2759 s
.css
= append(s
.css
, cs
)
2764 // QueryContext executes a prepared query statement with the given arguments
2765 // and returns the query results as a *Rows.
2766 func (s
*Stmt
) QueryContext(ctx context
.Context
, args
...any
) (*Rows
, error
) {
2768 defer s
.closemu
.RUnlock()
2770 var rowsi driver
.Rows
2771 strategy
:= cachedOrNewConn
2772 for i
:= 0; i
< maxBadConnRetries
+1; i
++ {
2773 if i
== maxBadConnRetries
{
2774 strategy
= alwaysNewConn
2776 dc
, releaseConn
, ds
, err
:= s
.connStmt(ctx
, strategy
)
2778 if errors
.Is(err
, driver
.ErrBadConn
) {
2784 rowsi
, err
= rowsiFromStatement(ctx
, dc
.ci
, ds
, args
...)
2786 // Note: ownership of ci passes to the *Rows, to be freed
2787 // with releaseConn.
2791 // releaseConn set below
2793 // addDep must be added before initContextClose or it could attempt
2794 // to removeDep before it has been added.
2795 s
.db
.addDep(s
, rows
)
2797 // releaseConn must be set before initContextClose or it could
2798 // release the connection before it is set.
2799 rows
.releaseConn
= func(err error
) {
2801 s
.db
.removeDep(s
, rows
)
2803 var txctx context
.Context
2805 txctx
= s
.cg
.txCtx()
2807 rows
.initContextClose(ctx
, txctx
)
2812 if !errors
.Is(err
, driver
.ErrBadConn
) {
2816 return nil, driver
.ErrBadConn
2819 // Query executes a prepared query statement with the given arguments
2820 // and returns the query results as a *Rows.
2822 // Query uses context.Background internally; to specify the context, use
2824 func (s
*Stmt
) Query(args
...any
) (*Rows
, error
) {
2825 return s
.QueryContext(context
.Background(), args
...)
2828 func rowsiFromStatement(ctx context
.Context
, ci driver
.Conn
, ds
*driverStmt
, args
...any
) (driver
.Rows
, error
) {
2831 dargs
, err
:= driverArgsConnLocked(ci
, ds
, args
)
2835 return ctxDriverStmtQuery(ctx
, ds
.si
, dargs
)
2838 // QueryRowContext executes a prepared query statement with the given arguments.
2839 // If an error occurs during the execution of the statement, that error will
2840 // be returned by a call to Scan on the returned *Row, which is always non-nil.
2841 // If the query selects no rows, the *Row's Scan will return ErrNoRows.
2842 // Otherwise, the *Row's Scan scans the first selected row and discards
2844 func (s
*Stmt
) QueryRowContext(ctx context
.Context
, args
...any
) *Row
{
2845 rows
, err
:= s
.QueryContext(ctx
, args
...)
2847 return &Row
{err
: err
}
2849 return &Row
{rows
: rows
}
2852 // QueryRow executes a prepared query statement with the given arguments.
2853 // If an error occurs during the execution of the statement, that error will
2854 // be returned by a call to Scan on the returned *Row, which is always non-nil.
2855 // If the query selects no rows, the *Row's Scan will return ErrNoRows.
2856 // Otherwise, the *Row's Scan scans the first selected row and discards
2862 // err := nameByUseridStmt.QueryRow(id).Scan(&name)
2864 // QueryRow uses context.Background internally; to specify the context, use
2866 func (s
*Stmt
) QueryRow(args
...any
) *Row
{
2867 return s
.QueryRowContext(context
.Background(), args
...)
2870 // Close closes the statement.
2871 func (s
*Stmt
) Close() error
{
2873 defer s
.closemu
.Unlock()
2875 if s
.stickyErr
!= nil {
2890 return s
.db
.removeDep(s
, s
)
2893 if s
.parentStmt
!= nil {
2894 // If parentStmt is set, we must not close s.txds since it's stored
2895 // in the css array of the parentStmt.
2896 return s
.db
.removeDep(s
.parentStmt
, s
)
2901 func (s
*Stmt
) finalClose() error
{
2905 for _
, v
:= range s
.css
{
2906 s
.db
.noteUnusedDriverStatement(v
.dc
, v
.ds
)
2907 v
.dc
.removeOpenStmt(v
.ds
)
2914 // Rows is the result of a query. Its cursor starts before the first row
2915 // of the result set. Use Next to advance from row to row.
2917 dc
*driverConn
// owned; must call releaseConn when closed to release
2918 releaseConn
func(error
)
2920 cancel
func() // called when Rows is closed, may be nil.
2921 closeStmt
*driverStmt
// if non-nil, statement to Close on close
2923 // closemu prevents Rows from closing while there
2924 // is an active streaming result. It is held for read during non-close operations
2925 // and exclusively during close.
2927 // closemu guards lasterr and closed.
2928 closemu sync
.RWMutex
2930 lasterr error
// non-nil only if closed is true
2932 // lastcols is only used in Scan, Next, and NextResultSet which are expected
2933 // not to be called concurrently.
2934 lastcols
[]driver
.Value
2937 // lasterrOrErrLocked returns either lasterr or the provided err.
2938 // rs.closemu must be read-locked.
2939 func (rs
*Rows
) lasterrOrErrLocked(err error
) error
{
2940 if rs
.lasterr
!= nil && rs
.lasterr
!= io
.EOF
{
2946 // bypassRowsAwaitDone is only used for testing.
2947 // If true, it will not close the Rows automatically from the context.
2948 var bypassRowsAwaitDone
= false
2950 func (rs
*Rows
) initContextClose(ctx
, txctx context
.Context
) {
2951 if ctx
.Done() == nil && (txctx
== nil || txctx
.Done() == nil) {
2954 if bypassRowsAwaitDone
{
2957 ctx
, rs
.cancel
= context
.WithCancel(ctx
)
2958 go rs
.awaitDone(ctx
, txctx
)
2961 // awaitDone blocks until either ctx or txctx is canceled. The ctx is provided
2962 // from the query context and is canceled when the query Rows is closed.
2963 // If the query was issued in a transaction, the transaction's context
2964 // is also provided in txctx to ensure Rows is closed if the Tx is closed.
2965 func (rs
*Rows
) awaitDone(ctx
, txctx context
.Context
) {
2966 var txctxDone
<-chan struct{}
2968 txctxDone
= txctx
.Done()
2977 // Next prepares the next result row for reading with the Scan method. It
2978 // returns true on success, or false if there is no next result row or an error
2979 // happened while preparing it. Err should be consulted to distinguish between
2982 // Every call to Scan, even the first one, must be preceded by a call to Next.
2983 func (rs
*Rows
) Next() bool {
2984 var doClose
, ok
bool
2985 withLock(rs
.closemu
.RLocker(), func() {
2986 doClose
, ok
= rs
.nextLocked()
2994 func (rs
*Rows
) nextLocked() (doClose
, ok
bool) {
2999 // Lock the driver connection before calling the driver interface
3000 // rowsi to prevent a Tx from rolling back the connection at the same time.
3002 defer rs
.dc
.Unlock()
3004 if rs
.lastcols
== nil {
3005 rs
.lastcols
= make([]driver
.Value
, len(rs
.rowsi
.Columns()))
3008 rs
.lasterr
= rs
.rowsi
.Next(rs
.lastcols
)
3009 if rs
.lasterr
!= nil {
3010 // Close the connection if there is a driver error.
3011 if rs
.lasterr
!= io
.EOF
{
3014 nextResultSet
, ok
:= rs
.rowsi
.(driver
.RowsNextResultSet
)
3018 // The driver is at the end of the current result set.
3019 // Test to see if there is another result set after the current one.
3020 // Only close Rows if there is no further result sets to read.
3021 if !nextResultSet
.HasNextResultSet() {
3024 return doClose
, false
3029 // NextResultSet prepares the next result set for reading. It reports whether
3030 // there is further result sets, or false if there is no further result set
3031 // or if there is an error advancing to it. The Err method should be consulted
3032 // to distinguish between the two cases.
3034 // After calling NextResultSet, the Next method should always be called before
3035 // scanning. If there are further result sets they may not have rows in the result
3037 func (rs
*Rows
) NextResultSet() bool {
3045 defer rs
.closemu
.RUnlock()
3052 nextResultSet
, ok
:= rs
.rowsi
.(driver
.RowsNextResultSet
)
3058 // Lock the driver connection before calling the driver interface
3059 // rowsi to prevent a Tx from rolling back the connection at the same time.
3061 defer rs
.dc
.Unlock()
3063 rs
.lasterr
= nextResultSet
.NextResultSet()
3064 if rs
.lasterr
!= nil {
3071 // Err returns the error, if any, that was encountered during iteration.
3072 // Err may be called after an explicit or implicit Close.
3073 func (rs
*Rows
) Err() error
{
3075 defer rs
.closemu
.RUnlock()
3076 return rs
.lasterrOrErrLocked(nil)
3079 var errRowsClosed
= errors
.New("sql: Rows are closed")
3080 var errNoRows
= errors
.New("sql: no Rows available")
3082 // Columns returns the column names.
3083 // Columns returns an error if the rows are closed.
3084 func (rs
*Rows
) Columns() ([]string, error
) {
3086 defer rs
.closemu
.RUnlock()
3088 return nil, rs
.lasterrOrErrLocked(errRowsClosed
)
3090 if rs
.rowsi
== nil {
3091 return nil, rs
.lasterrOrErrLocked(errNoRows
)
3094 defer rs
.dc
.Unlock()
3096 return rs
.rowsi
.Columns(), nil
3099 // ColumnTypes returns column information such as column type, length,
3100 // and nullable. Some information may not be available from some drivers.
3101 func (rs
*Rows
) ColumnTypes() ([]*ColumnType
, error
) {
3103 defer rs
.closemu
.RUnlock()
3105 return nil, rs
.lasterrOrErrLocked(errRowsClosed
)
3107 if rs
.rowsi
== nil {
3108 return nil, rs
.lasterrOrErrLocked(errNoRows
)
3111 defer rs
.dc
.Unlock()
3113 return rowsColumnInfoSetupConnLocked(rs
.rowsi
), nil
3116 // ColumnType contains the name and type of a column.
3117 type ColumnType
struct {
3122 hasPrecisionScale
bool
3129 scanType reflect
.Type
3132 // Name returns the name or alias of the column.
3133 func (ci
*ColumnType
) Name() string {
3137 // Length returns the column type length for variable length column types such
3138 // as text and binary field types. If the type length is unbounded the value will
3139 // be math.MaxInt64 (any database limits will still apply).
3140 // If the column type is not variable length, such as an int, or if not supported
3141 // by the driver ok is false.
3142 func (ci
*ColumnType
) Length() (length
int64, ok
bool) {
3143 return ci
.length
, ci
.hasLength
3146 // DecimalSize returns the scale and precision of a decimal type.
3147 // If not applicable or if not supported ok is false.
3148 func (ci
*ColumnType
) DecimalSize() (precision
, scale
int64, ok
bool) {
3149 return ci
.precision
, ci
.scale
, ci
.hasPrecisionScale
3152 // ScanType returns a Go type suitable for scanning into using Rows.Scan.
3153 // If a driver does not support this property ScanType will return
3154 // the type of an empty interface.
3155 func (ci
*ColumnType
) ScanType() reflect
.Type
{
3159 // Nullable reports whether the column may be null.
3160 // If a driver does not support this property ok will be false.
3161 func (ci
*ColumnType
) Nullable() (nullable
, ok
bool) {
3162 return ci
.nullable
, ci
.hasNullable
3165 // DatabaseTypeName returns the database system name of the column type. If an empty
3166 // string is returned, then the driver type name is not supported.
3167 // Consult your driver documentation for a list of driver data types. Length specifiers
3168 // are not included.
3169 // Common type names include "VARCHAR", "TEXT", "NVARCHAR", "DECIMAL", "BOOL",
3170 // "INT", and "BIGINT".
3171 func (ci
*ColumnType
) DatabaseTypeName() string {
3172 return ci
.databaseType
3175 func rowsColumnInfoSetupConnLocked(rowsi driver
.Rows
) []*ColumnType
{
3176 names
:= rowsi
.Columns()
3178 list
:= make([]*ColumnType
, len(names
))
3179 for i
:= range list
{
3185 if prop
, ok
:= rowsi
.(driver
.RowsColumnTypeScanType
); ok
{
3186 ci
.scanType
= prop
.ColumnTypeScanType(i
)
3188 ci
.scanType
= reflect
.TypeOf(new(any
)).Elem()
3190 if prop
, ok
:= rowsi
.(driver
.RowsColumnTypeDatabaseTypeName
); ok
{
3191 ci
.databaseType
= prop
.ColumnTypeDatabaseTypeName(i
)
3193 if prop
, ok
:= rowsi
.(driver
.RowsColumnTypeLength
); ok
{
3194 ci
.length
, ci
.hasLength
= prop
.ColumnTypeLength(i
)
3196 if prop
, ok
:= rowsi
.(driver
.RowsColumnTypeNullable
); ok
{
3197 ci
.nullable
, ci
.hasNullable
= prop
.ColumnTypeNullable(i
)
3199 if prop
, ok
:= rowsi
.(driver
.RowsColumnTypePrecisionScale
); ok
{
3200 ci
.precision
, ci
.scale
, ci
.hasPrecisionScale
= prop
.ColumnTypePrecisionScale(i
)
3206 // Scan copies the columns in the current row into the values pointed
3207 // at by dest. The number of values in dest must be the same as the
3208 // number of columns in Rows.
3210 // Scan converts columns read from the database into the following
3211 // common Go types and special types provided by the sql package:
3215 // *int, *int8, *int16, *int32, *int64
3216 // *uint, *uint8, *uint16, *uint32, *uint64
3218 // *float32, *float64
3221 // *Rows (cursor value)
3222 // any type implementing Scanner (see Scanner docs)
3224 // In the most simple case, if the type of the value from the source
3225 // column is an integer, bool or string type T and dest is of type *T,
3226 // Scan simply assigns the value through the pointer.
3228 // Scan also converts between string and numeric types, as long as no
3229 // information would be lost. While Scan stringifies all numbers
3230 // scanned from numeric database columns into *string, scans into
3231 // numeric types are checked for overflow. For example, a float64 with
3232 // value 300 or a string with value "300" can scan into a uint16, but
3233 // not into a uint8, though float64(255) or "255" can scan into a
3234 // uint8. One exception is that scans of some float64 numbers to
3235 // strings may lose information when stringifying. In general, scan
3236 // floating point columns into *float64.
3238 // If a dest argument has type *[]byte, Scan saves in that argument a
3239 // copy of the corresponding data. The copy is owned by the caller and
3240 // can be modified and held indefinitely. The copy can be avoided by
3241 // using an argument of type *RawBytes instead; see the documentation
3242 // for RawBytes for restrictions on its use.
3244 // If an argument has type *interface{}, Scan copies the value
3245 // provided by the underlying driver without conversion. When scanning
3246 // from a source value of type []byte to *interface{}, a copy of the
3247 // slice is made and the caller owns the result.
3249 // Source values of type time.Time may be scanned into values of type
3250 // *time.Time, *interface{}, *string, or *[]byte. When converting to
3251 // the latter two, time.RFC3339Nano is used.
3253 // Source values of type bool may be scanned into types *bool,
3254 // *interface{}, *string, *[]byte, or *RawBytes.
3256 // For scanning into *bool, the source may be true, false, 1, 0, or
3257 // string inputs parseable by strconv.ParseBool.
3259 // Scan can also convert a cursor returned from a query, such as
3260 // "select cursor(select * from my_table) from dual", into a
3261 // *Rows value that can itself be scanned from. The parent
3262 // select query will close any cursor *Rows if the parent *Rows is closed.
3264 // If any of the first arguments implementing Scanner returns an error,
3265 // that error will be wrapped in the returned error
3266 func (rs
*Rows
) Scan(dest
...any
) error
{
3269 if rs
.lasterr
!= nil && rs
.lasterr
!= io
.EOF
{
3270 rs
.closemu
.RUnlock()
3274 err
:= rs
.lasterrOrErrLocked(errRowsClosed
)
3275 rs
.closemu
.RUnlock()
3278 rs
.closemu
.RUnlock()
3280 if rs
.lastcols
== nil {
3281 return errors
.New("sql: Scan called without calling Next")
3283 if len(dest
) != len(rs
.lastcols
) {
3284 return fmt
.Errorf("sql: expected %d destination arguments in Scan, not %d", len(rs
.lastcols
), len(dest
))
3286 for i
, sv
:= range rs
.lastcols
{
3287 err
:= convertAssignRows(dest
[i
], sv
, rs
)
3289 return fmt
.Errorf(`sql: Scan error on column index %d, name %q: %w`, i
, rs
.rowsi
.Columns()[i
], err
)
3295 // rowsCloseHook returns a function so tests may install the
3296 // hook through a test only mutex.
3297 var rowsCloseHook
= func() func(*Rows
, *error
) { return nil }
3299 // Close closes the Rows, preventing further enumeration. If Next is called
3300 // and returns false and there are no further result sets,
3301 // the Rows are closed automatically and it will suffice to check the
3302 // result of Err. Close is idempotent and does not affect the result of Err.
3303 func (rs
*Rows
) Close() error
{
3304 return rs
.close(nil)
3307 func (rs
*Rows
) close(err error
) error
{
3309 defer rs
.closemu
.Unlock()
3316 if rs
.lasterr
== nil {
3320 withLock(rs
.dc
, func() {
3321 err
= rs
.rowsi
.Close()
3323 if fn
:= rowsCloseHook(); fn
!= nil {
3326 if rs
.cancel
!= nil {
3330 if rs
.closeStmt
!= nil {
3331 rs
.closeStmt
.Close()
3337 // Row is the result of calling QueryRow to select a single row.
3339 // One of these two will be non-nil:
3340 err error
// deferred error for easy chaining
3344 // Scan copies the columns from the matched row into the values
3345 // pointed at by dest. See the documentation on Rows.Scan for details.
3346 // If more than one row matches the query,
3347 // Scan uses the first row and discards the rest. If no row matches
3348 // the query, Scan returns ErrNoRows.
3349 func (r
*Row
) Scan(dest
...any
) error
{
3354 // TODO(bradfitz): for now we need to defensively clone all
3355 // []byte that the driver returned (not permitting
3356 // *RawBytes in Rows.Scan), since we're about to close
3357 // the Rows in our defer, when we return from this function.
3358 // the contract with the driver.Next(...) interface is that it
3359 // can return slices into read-only temporary memory that's
3360 // only valid until the next Scan/Close. But the TODO is that
3361 // for a lot of drivers, this copy will be unnecessary. We
3362 // should provide an optional interface for drivers to
3363 // implement to say, "don't worry, the []bytes that I return
3364 // from Next will not be modified again." (for instance, if
3365 // they were obtained from the network anyway) But for now we
3367 defer r
.rows
.Close()
3368 for _
, dp
:= range dest
{
3369 if _
, ok
:= dp
.(*RawBytes
); ok
{
3370 return errors
.New("sql: RawBytes isn't allowed on Row.Scan")
3375 if err
:= r
.rows
.Err(); err
!= nil {
3380 err
:= r
.rows
.Scan(dest
...)
3384 // Make sure the query can be processed to completion with no errors.
3385 return r
.rows
.Close()
3388 // Err provides a way for wrapping packages to check for
3389 // query errors without calling Scan.
3390 // Err returns the error, if any, that was encountered while running the query.
3391 // If this error is not nil, this error will also be returned from Scan.
3392 func (r
*Row
) Err() error
{
3396 // A Result summarizes an executed SQL command.
3397 type Result
interface {
3398 // LastInsertId returns the integer generated by the database
3399 // in response to a command. Typically this will be from an
3400 // "auto increment" column when inserting a new row. Not all
3401 // databases support this feature, and the syntax of such
3402 // statements varies.
3403 LastInsertId() (int64, error
)
3405 // RowsAffected returns the number of rows affected by an
3406 // update, insert, or delete. Not every database or database
3407 // driver may support this.
3408 RowsAffected() (int64, error
)
3411 type driverResult
struct {
3412 sync
.Locker
// the *driverConn
3416 func (dr driverResult
) LastInsertId() (int64, error
) {
3419 return dr
.resi
.LastInsertId()
3422 func (dr driverResult
) RowsAffected() (int64, error
) {
3425 return dr
.resi
.RowsAffected()
3428 func stack() string {
3429 var buf
[2 << 10]byte
3430 return string(buf
[:runtime
.Stack(buf
[:], false)])
3433 // withLock runs while holding lk.
3434 func withLock(lk sync
.Locker
, fn
func()) {
3436 defer lk
.Unlock() // in case fn panics