database/sql Source — Specification¶

1. Intro¶

database/sql is Go's standard interface to relational databases. It does not bundle a driver; it defines the contract that drivers implement and the user-facing types and methods that programs call. The package shipped in Go 1.0 (March 2012) and has lived under the Go 1 compatibility promise ever since: the user-facing API at database/sql is stable, the names do not change, and the behaviour of existing methods is preserved across releases. New capability lands as new optional driver interfaces or as *Context variants rather than as breaking changes to the original surface.

The package is governed by two source trees in the standard library: src/database/sql/ for the user-facing API and src/database/sql/driver/ for the driver contract. The driver tree is the extension point — any package satisfying the driver interfaces and calling sql.Register("name", driverInstance) participates without modifying the standard library. PostgreSQL drivers (lib/pq, jackc/pgx's stdlib adapter), MySQL drivers (go-sql-driver/mysql), SQLite drivers (mattn/go-sqlite3, modernc.org/sqlite), Microsoft SQL Server drivers (microsoft/go-mssqldb), Oracle drivers (sijms/go-ora), ClickHouse drivers (ClickHouse/clickhouse-go), and dozens of niche drivers all interoperate through this single contract. The package itself contains zero database-specific code; every wire-protocol byte is the driver's responsibility.

The architecture is a textbook example of the dependency inversion principle in standard-library form: the high-level policy (pooling, retry, context propagation, prepared-statement caching, transaction tracking) is in database/sql; the low-level mechanism (parsing the DSN, opening a TCP socket, framing a query packet, decoding a result row) is in the driver. The two communicate through the interfaces in database/sql/driver. Adding a new database engine to the Go ecosystem requires zero changes to the standard library — only a new package implementing the driver interfaces.

The package documentation lives at https://pkg.go.dev/database/sql and https://pkg.go.dev/database/sql/driver. Source for the current release is at https://github.com/golang/go/tree/master/src/database/sql. The list of registered third-party drivers is maintained at https://github.com/golang/go/wiki/SQLDrivers. The design rationale is summarised in the original golang-nuts thread "database/sql design" (2011) and elaborated in Brad Fitzpatrick's GopherCon talk "Go database/sql" (2014); both predate Go 1.8 and so do not cover the context revision, but they remain accurate on the architectural split between pool and driver.

2. The two-package design¶

database/sql is split into two packages with distinct audiences:

The split lets application code import only database/sql and never see the driver contract. The driver package is imported by driver authors and by application code only for the side effect of registration (the conventional _ "github.com/go-sql-driver/mysql" blank import calls sql.Register("mysql", &MySQLDriver{}) from the driver's init()).

The handshake between the two packages is mediated by sql.Register and sql.Open. Register stores driver instances in a package-level map; Open(name, dsn) looks up the driver by name and returns a *sql.DB that wraps the driver's Conns in a connection pool with retry, context cancellation, statement caching, and transaction tracking. The driver itself does none of that — its job is to talk wire protocol to a database; the pool, the contexts, and the retry policy are database/sql's job.

A consequence of the split is that the pool semantics are uniform across drivers. SetMaxOpenConns, SetMaxIdleConns, SetConnMaxLifetime, and SetConnMaxIdleTime configure the pool's policy regardless of which database is behind it; an application moving from MySQL to PostgreSQL changes the driver import and the DSN but does not rewrite its pool-tuning code. Likewise, context cancellation, prepared-statement reuse, and transaction tracking are implemented once and inherited by every driver that opts into the relevant interfaces. This is the standard-library payoff of the inversion: complex cross-cutting policy lives in one place and benefits every database.

A second consequence is the testing story. Because the contract is interface-based, an in-memory fake driver (the standard library's own fakedb_test.go, or third-party packages like DATA-DOG/go-sqlmock) can be substituted for a real database in tests. The application code under test still sees *sql.DB and calls Query and Exec; the test driver records the calls or returns canned results. This is impossible in language ecosystems where the database client is a concrete class with no interface surface; in Go it is the default mode of unit testing data-access code.

A third consequence — easy to miss until a production incident exposes it — is that every cross-cutting concern landed in database/sql is shared across every driver. Pool exhaustion behaviour is identical for a MySQL workload and a PostgreSQL workload. Context cancellation propagation is identical. The retry-on-ErrBadConn policy is identical. Operators tuning a production database can read a single set of docs (SetMaxOpenConns, SetConnMaxLifetime, the DBStats fields) and the knowledge transfers across every database their applications talk to.

3. Stable user-facing types¶

The types below are the application-visible surface. Their method sets have been frozen since Go 1.0 except for *Context additions in Go 1.8.

The constructor for NullTime arrived in Go 1.13; the other Null* types have been present since Go 1.0 (NullString, NullInt64, NullFloat64, NullBool) or Go 1.10 (NullInt32, NullInt16, NullByte). Go 1.22 added the generic sql.Null[T any], which subsumes all of them but does not retire the specific types — they remain to avoid breaking decades of code that names them directly.

Lifecycle considerations across these types:

The most common mistake in early Go code is treating *sql.DB as a single connection — calling Close() between requests, opening a new DB per HTTP handler — which defeats the pool. The shape is identical to http.Client: one long-lived handle shared across goroutines.

Pool-tuning knobs deserve enumeration because their interaction is non-obvious:

4. Scanner and driver.Valuer¶

Custom type conversion is the bidirectional bridge between SQL column values and Go types. It is governed by two single-method interfaces.

// in database/sql
type Scanner interface {
    Scan(src any) error
}

// in database/sql/driver
type Valuer interface {
    Value() (Value, error)
}

Scan is called by Rows.Scan when the destination is a Scanner; the driver delivers the column value as one of the documented driver.Value kinds (int64, float64, bool, []byte, string, time.Time, nil) and the type's Scan method narrows it to the Go-side representation. Value is called by the driver when an argument is passed to Query, Exec, or Stmt.Exec; the argument is converted to a driver.Value before crossing the driver boundary.

The pair allows user-defined types — a UUID type, a JSON-backed config struct, a money type with currency — to round-trip through SQL without per-call conversion code. Every Null* type in database/sql is itself a Scanner and Valuer; the same machinery powers third-party types like pgtype.Numeric and uuid.UUID.

The conversion contract has three levels of strictness:

A common pitfall: a value-receiver Scan method (func (u UUID) Scan(src any) error) modifies a copy and silently loses the result. The correct shape is always a pointer receiver. The same trap exists for Valuer, though it bites less often because Value is read-only.

Documentation references:

• database/sql.Scanner: https://pkg.go.dev/database/sql#Scanner
• database/sql/driver.Valuer: https://pkg.go.dev/database/sql/driver#Valuer
• driver.Value kinds: https://pkg.go.dev/database/sql/driver#Value
• convertAssign implementation: https://github.com/golang/go/blob/master/src/database/sql/convert.go

5. Driver interfaces¶

The driver contract is layered. A minimum-viable driver implements Driver and Conn and Stmt and Rows; richer drivers add the optional context-aware and behaviour-extending interfaces below.

The contract scales by feature detection: database/sql checks at runtime whether a driver implements a given optional interface (if _, ok := drv.(driver.QueryerContext); ok) and falls back to the older primitives when the optional interface is absent. A driver written for Go 1.0 still works under Go 1.22; a driver that opts into ConnBeginTx gains isolation-level support without breaking older callers.

The feature-detection pattern is the package's central extension mechanism. New driver capability is added by:

1. Defining a new interface in database/sql/driver whose method signature carries the new capability.
2. Adding a runtime type-assertion in database/sql at the call site that uses the new method when available and falls back to the old path when not.
3. Documenting the interface as optional, with a paragraph in the package docs explaining the fallback.

Existing drivers continue to satisfy driver.Driver and the original required interfaces and need no modification. Drivers that want the new feature implement the new interface. This is the same pattern Go uses for io.WriterTo, io.ReaderFrom, and the http.ResponseWriter extension interfaces (http.Flusher, http.Hijacker); database/sql is the standard library's most aggressive user of it, with the highest count of optional interfaces in a single package.

Reference list of optional interfaces: https://pkg.go.dev/database/sql/driver.

How drivers in production layer the interfaces:

Reading any of these drivers is the practical complement to reading database/sql itself; the contract documentation alone does not convey how it is exercised in anger.

A worked example of how database/sql selects a code path at runtime, expressed in pseudocode:

func (db *DB) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error) {
    dc, err := db.conn(ctx, cachedOrNewConn)
    if err != nil { return nil, err }
    if qc, ok := dc.ci.(driver.QueryerContext); ok {
        return queryDC(ctx, dc, qc, releaseConn, query, args)
    }
    if q, ok := dc.ci.(driver.Queryer); ok {
        return queryLegacy(ctx, dc, q, releaseConn, query, args)
    }
    stmt, err := dc.prepareDC(ctx, query)
    if err != nil { return nil, err }
    return stmt.QueryContext(ctx, args...)
}

The dispatch sequence — context-aware, then legacy, then prepare-and-query — is the central pattern. Every entry point in database/sql follows it for the relevant pair of interfaces.

6. Sentinel errors¶

database/sql exposes a small set of named errors that callers compare against directly. These are stable values; new sentinels are added but existing ones are not renamed or repurposed.

ErrBadConn deserves extra attention because it is the only sentinel that triggers an automatic retry. The retry policy is: on ErrBadConn, discard the connection, and if the operation is idempotent and has not yet written to the wire, request a new connection and retry once. The retry is bounded — at most one — and it is conditional on the operation not having committed any bytes yet. Drivers signal this by returning ErrBadConn only before the first wire byte; once a query packet is en route, ErrBadConn is a contract violation. The constant is exported but should be used by drivers, not application code; application code that sees an ErrBadConn bubbling up is observing a driver bug.

The interaction with errors.Is is straightforward for the package's own sentinels — errors.Is(err, sql.ErrNoRows) is the canonical check — but does not extend to driver-side errors. Database-specific errors (a PostgreSQL pq.Error, a MySQL *mysql.MySQLError) carry SQLSTATE codes and structured fields; portable application code that distinguishes "unique violation" from "deadlock" goes through driver-specific type assertions or through a portability layer like jackc/pgx's pgerrcode. database/sql does not standardise SQLSTATE or any other error taxonomy; that is by design — different databases disagree, and forcing a unified taxonomy would be a leaky abstraction.

Documentation: https://pkg.go.dev/database/sql#pkg-variables, https://pkg.go.dev/database/sql/driver#pkg-variables.

7. Transaction isolation levels¶

Isolation level is set by BeginTx through sql.TxOptions{Isolation: ...}. The constants are declared in database/sql and forwarded to the driver via driver.TxOptions.

Whether a level is honoured is up to the driver and the database. Drivers that do not implement ConnBeginTx ignore the option entirely and return a transaction at the default level; database/sql does not enforce or translate the constants. The mapping from sql.IsolationLevel to SQL syntax is the driver's job.

TxOptions also carries ReadOnly bool, which drivers can map to the database's read-only mode (PostgreSQL SET TRANSACTION READ ONLY, MySQL START TRANSACTION READ ONLY). The hint is advisory; the driver is free to ignore it if the database does not support read-only transactions, and database/sql does not enforce that no writes occur. Use ReadOnly: true to enable database-side query plan optimisations and to let read-only replicas accept the transaction.

Practical mapping of the constants per database engine:

Application code that depends on a specific isolation level must verify it against the target engine's documentation, not against the database/sql constants alone. The constants are a portable request; the database's response is engine-specific.

Documentation: https://pkg.go.dev/database/sql#IsolationLevel, https://pkg.go.dev/database/sql#TxOptions.

8. Source file map¶

The standard-library tree is small enough to enumerate. Paths are relative to src/database/sql/.

Under src/database/sql/driver/:

Browsable source: https://github.com/golang/go/tree/master/src/database/sql.

The most rewarding reading order for a senior engineer working through the source for the first time:

1. driver/types.go and driver/driver.go — the contract, twelve hundred lines, defines everything else.
2. sql.go from the top: the global drivers map and Register, then Open and OpenDB, then DB and the pool implementation (db.conn, db.putConn, the connRequest channel-based wakeup mechanism).
3. The transaction code path: DB.BeginTx, Tx.Commit, Tx.Rollback, and the connection-bound lifecycle.
4. The query path: DB.QueryContext, Stmt.QueryContext, Rows.Next, Rows.Scan.
5. convert.go — convertAssign and the type-conversion matrix.
6. ctxutil.go — the small adapter layer that translates context.Context cancellation into driver.ErrBadConn or an explicit cancel call on Conn.QueryContext.

Approximately 5,000 lines of Go, well-commented, with the architecture mostly visible from the type declarations alone.

Key implementation details worth tracing while reading:

9. Notable additions across releases¶

The Go 1 compatibility promise governs how database/sql evolves: existing names and behaviours are preserved; new capability lands as new methods, new optional interfaces, or new exported types.

Release notes index: https://go.dev/doc/devel/release. database/sql is mentioned by release in the "Minor changes to the library" sections of each release page.

Two themes recur across the additions:

• Capability via optional interfaces, never via method-set growth on required interfaces. Every new feature since Go 1.0 — context cancellation, named parameters, multi-result sets, column type metadata, session reset, validator, isolation level — lands as a new interface that drivers may or may not implement. Required interface method sets are frozen.
• *Context siblings, never replacements. The Go 1.8 context revision added QueryContext, ExecContext, BeginTx, PingContext, PrepareContext, StmtQueryContext, StmtExecContext. The original non-Context methods remained, with their bodies rewritten to delegate to the new methods with context.Background(). Application code that predates Go 1.8 still compiles unchanged.

These two themes are the source of the package's stability and the reason driver code from 2013 still runs in 2026.

10. Compatibility discipline¶

database/sql is one of the cleanest demonstrations of the Go 1 compatibility promise. Three rules govern its evolution:

1. Original interfaces are frozen. driver.Driver, driver.Conn, driver.Stmt, driver.Rows, driver.Tx, driver.Result, driver.Valuer, and sql.Scanner have the same method sets in Go 1.22 that they had in Go 1.0. A driver written against Go 1.0 still compiles and runs against the current standard library.
2. New capability is added as new optional interfaces. ConnBeginTx, QueryerContext, ExecerContext, NamedValueChecker, SessionResetter, and Validator are all opt-in. database/sql performs a type assertion at runtime; if the driver implements the new interface, the new code path is used; otherwise the old fallback is used.
3. *Context methods are siblings, not replacements. Query and QueryContext both exist; the older method internally calls the newer with context.Background(). Application code can adopt context support gradually without rewriting call sites.

The result is that decade-old driver code keeps working, application code written before Go 1.8 still compiles, and migration to context support is incremental rather than disruptive. The cost is interface proliferation: a feature-complete driver implements roughly twenty interfaces from database/sql/driver. That cost is paid by the driver author; the application sees only *sql.DB.

The compatibility discipline also constrains what database/sql can fix. Quirks in the original API — Exec returning a Result whose LastInsertId and RowsAffected may both error out, Rows.Scan requiring exact argument count, the lack of a typed bulk-insert API — cannot be addressed without breaking existing code. They survive as documented behaviour, worked around by drivers and helper libraries (sqlx, sqlc, bun, ent) rather than by the standard library itself.

11. Notable proposals¶

The package's evolution is documented in Go issue tracker proposals. The accepted and significant ones:

The full proposal list for the package: https://github.com/golang/go/issues?q=label%3Aproposal+database%2Fsql.

A handful of proposals were deliberately rejected or remain open for instructive reasons:

The pattern across rejections is the same: anything that requires the standard library to encode database-specific knowledge gets pushed out to drivers or helper libraries; the standard library stays minimal, portable, and stable.

12. Bug reporting¶

Bugs against database/sql and database/sql/driver are filed in the Go issue tracker at https://github.com/golang/go/issues. The convention is to prefix the issue title with database/sql: (or database/sql/driver:) so that the team's triage filters surface it correctly. Driver bugs (mis-behaviour of lib/pq, go-sql-driver/mysql, pgx) are filed against the driver's own repository, not against the standard library; the standard library tracker is for the contract, the pool, the conversion machinery, and the *sql types themselves.

Reproducible bug reports typically include:

• The Go version (go version) and the platform (go env GOOS GOARCH).
• The driver name and version (go list -m).
• A minimal program that reproduces the issue, ideally using the in-tree fakedb_test.go driver when the bug is in database/sql itself rather than a real driver.
• The expected and actual behaviour, citing the relevant section of https://pkg.go.dev/database/sql.

The maintainers for database/sql are listed in https://go.googlesource.com/go/+/master/src/database/sql/ commit history; historically Brad Fitzpatrick, Daniel Theophanes, and Russ Cox have driven the package's evolution. Bug fixes that touch the driver contract require careful review because the optional-interface discipline must be preserved; new interfaces, not modified ones, are the only way capability is added.

For security-sensitive issues — driver-level SQL injection, connection-pool-induced data leaks across users, TLS misuse — the Go security team is reached via security@golang.org, not the public tracker. The standard process is described at https://go.dev/security/policy.

Three categories of issue are filed regularly enough to be worth distinguishing in advance:

The package's stability over thirteen years is a direct consequence of how seriously the maintainers take the Go 1 compatibility promise. The discipline — original interfaces frozen, new capability as optional interfaces, *Context siblings rather than replacements — is the model that the rest of the standard library aspires to and the most concrete answer in the Go ecosystem to the question "how does a foundational library evolve without breaking its users." database/sql is worth reading as much for that discipline as for what it does.

When opening a bug report, including the following decisively shortens triage:

Bug reports that include all six are usually triaged within a week; reports that include only the symptom often languish for months waiting for clarification.