Daniel Theophanes edited this page Oct 27, 2018 · 6 revisions


The database/sql package provides a generic interface around SQL (or SQL-like) databases. See the official documentation for details.

This page provides example usage patterns.

Database driver

The database/sql package must be used in conjunction with a database driver. See http://golang.org/s/sqldrivers for a list of drivers.

The documentation below assumes a driver has been imported.

Connecting to a database

Open is used to create a database handle:

db, err := sql.Open(driver, dataSourceName)

Where driver specifies a database driver and dataSourceName specifies database-specific connection information such as database name and authentication credentials.

Note that Open does not directly open a database connection: this is deferred until a query is made. To verify that a connection can be made before making a query, use the PingContext function:

if err := db.PingContext(ctx); err != nil {

After use, the database is closed using Close.

Executing queries

ExecContext is used for queries where no rows are returned:

result, err := db.ExecContext(ctx,
	"INSERT INTO users (name, age) VALUES ($1, $2)",

Where result contains the last insert ID and number of rows affected. The availability of these values is dependent on the database driver.

QueryContext is used for retrieval:

rows, err := db.QueryContext(ctx, "SELECT name FROM users WHERE age = $1", age)
if err != nil {
defer rows.Close()
for rows.Next() {
	var name string
	if err := rows.Scan(&name); err != nil {
	fmt.Printf("%s is %d\n", name, age)
if err := rows.Err(); err != nil {

QueryRowContext is used where only a single row is expected:

var age int64
err := db.QueryRowContext(ctx, "SELECT age FROM users WHERE name = $1", name).Scan(&age)

Prepared statements can be created with Prepare:

age := 27
stmt, err := db.PrepareContext(ctx, "SELECT name FROM users WHERE age = $1")
if err != nil {
rows, err := stmt.Query(age)
// process rows

ExecContext, QueryContext and QueryRowContext can be called on statements. After use, a statement should be closed with Close.


Transactions are started with Begin:

tx, err := db.BeginTx(ctx, nil)
if err != nil {

The ExecContext, QueryContext, QueryRowContext and PrepareContext functions already covered can be used in a transaction.

A transaction must end with a call to Commit or Rollback.

Dealing with NULL

If a database column is nullable, one of the types supporting null values should be passed to Scan.

For example, if the name column in the names table is nullable:

var name NullString
err := db.QueryRowContext(ctx, "SELECT name FROM names WHERE id = $1", id).Scan(&name)
if name.Valid {
	// use name.String
} else {
	// value is NULL

Only NullBool, NullFloat64, NullInt64 and NullString are implemented in database/sql. Implementations of database-specific null types are left to the database driver.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.