func Drivers() []string

func Register(namestring, driverdriver.Driver)

type ColumnType struct {// contains filtered or unexported fields}

func (*ColumnType)DatabaseTypeName¶added ingo1.8

func (ci *ColumnType) DatabaseTypeName()string

DatabaseTypeName returns the database system name of the column type. If an emptystring is returned, then the driver type name is not supported.Consult your driver documentation for a list of driver data types.ColumnType.Length specifiersare not included.Common type names include "VARCHAR", "TEXT", "NVARCHAR", "DECIMAL", "BOOL","INT", and "BIGINT".

func (*ColumnType)DecimalSize¶added ingo1.8

func (ci *ColumnType) DecimalSize() (precision, scaleint64, okbool)

DecimalSize returns the scale and precision of a decimal type.If not applicable or if not supported ok is false.

func (*ColumnType)Length¶added ingo1.8

func (ci *ColumnType) Length() (lengthint64, okbool)

Length returns the column type length for variable length column types suchas text and binary field types. If the type length is unbounded the value willbemath.MaxInt64 (any database limits will still apply).If the column type is not variable length, such as an int, or if not supportedby the driver ok is false.

func (*ColumnType)Name¶added ingo1.8

func (ci *ColumnType) Name()string

Name returns the name or alias of the column.

func (*ColumnType)Nullable¶added ingo1.8

func (ci *ColumnType) Nullable() (nullable, okbool)

Nullable reports whether the column may be null.If a driver does not support this property ok will be false.

func (*ColumnType)ScanType¶added ingo1.8

func (ci *ColumnType) ScanType()reflect.Type

ScanType returns a Go type suitable for scanning into usingRows.Scan.If a driver does not support this property ScanType will returnthe type of an empty interface.

type Conn struct {// contains filtered or unexported fields}

func (*Conn)BeginTx¶added ingo1.9

func (c *Conn) BeginTx(ctxcontext.Context, opts *TxOptions) (*Tx,error)

BeginTx starts a transaction.

The provided context is used until the transaction is committed or rolled back.If the context is canceled, the sql package will roll backthe transaction.Tx.Commit will return an error if the context provided toBeginTx is canceled.

The providedTxOptions is optional and may be nil if defaults should be used.If a non-default isolation level is used that the driver doesn't support,an error will be returned.

func (*Conn)Close¶added ingo1.9

func (c *Conn) Close()error

Close returns the connection to the connection pool.All operations after a Close will return withErrConnDone.Close is safe to call concurrently with other operations and willblock until all other operations finish. It may be useful to firstcancel any used context and then call close directly after.

func (*Conn)ExecContext¶added ingo1.9

func (c *Conn) ExecContext(ctxcontext.Context, querystring, args ...any) (Result,error)

ExecContext executes a query without returning any rows.The args are for any placeholder parameters in the query.

package mainimport ("context""database/sql""log")var (ctx context.Contextdb  *sql.DB)func main() {// A *DB is a pool of connections. Call Conn to reserve a connection for// exclusive use.conn, err := db.Conn(ctx)if err != nil {log.Fatal(err)}defer conn.Close() // Return the connection to the pool.id := 41result, err := conn.ExecContext(ctx, `UPDATE balances SET balance = balance + 10 WHERE user_id = ?;`, id)if err != nil {log.Fatal(err)}rows, err := result.RowsAffected()if err != nil {log.Fatal(err)}if rows != 1 {log.Fatalf("expected single row affected, got %d rows affected", rows)}}

func (*Conn)PingContext¶added ingo1.9

func (c *Conn) PingContext(ctxcontext.Context)error

PingContext verifies the connection to the database is still alive.

func (*Conn)PrepareContext¶added ingo1.9

func (c *Conn) PrepareContext(ctxcontext.Context, querystring) (*Stmt,error)

PrepareContext creates a prepared statement for later queries or executions.Multiple queries or executions may be run concurrently from thereturned statement.The caller must call the statement's*Stmt.Close methodwhen the statement is no longer needed.

The provided context is used for the preparation of the statement, not for theexecution of the statement.

func (*Conn)QueryContext¶added ingo1.9

func (c *Conn) QueryContext(ctxcontext.Context, querystring, args ...any) (*Rows,error)

QueryContext executes a query that returns rows, typically a SELECT.The args are for any placeholder parameters in the query.

func (*Conn)QueryRowContext¶added ingo1.9

func (c *Conn) QueryRowContext(ctxcontext.Context, querystring, args ...any) *Row

QueryRowContext executes a query that is expected to return at most one row.QueryRowContext always returns a non-nil value. Errors are deferred untilthe*Row.Scan method is called.If the query selects no rows, the*Row.Scan will returnErrNoRows.Otherwise, the*Row.Scan scans the first selected row and discardsthe rest.

func (*Conn)Raw¶added ingo1.13

func (c *Conn) Raw(f func(driverConnany)error) (errerror)

Raw executes f exposing the underlying driver connection for theduration of f. The driverConn must not be used outside of f.

Once f returns and err is notdriver.ErrBadConn, theConn will continue to be usableuntilConn.Close is called.

type DB struct {// contains filtered or unexported fields}

funcOpen¶

func Open(driverName, dataSourceNamestring) (*DB,error)

Open opens a database specified by its database driver name and adriver-specific data source name, usually consisting of at least adatabase name and connection information.

Most users will open a database via a driver-specific connectionhelper function that returns a*DB. No database drivers are includedin the Go standard library. Seehttps://golang.org/s/sqldrivers fora list of third-party drivers.

Open may just validate its arguments without creating a connectionto the database. To verify that the data source name is valid, callDB.Ping.

The returnedDB is safe for concurrent use by multiple goroutinesand maintains its own pool of idle connections. Thus, the Openfunction should be called just once. It is rarely necessary toclose aDB.

funcOpenDB¶added ingo1.10

func OpenDB(cdriver.Connector) *DB

OpenDB opens a database using adriver.Connector, allowing drivers tobypass a string based data source name.

Most users will open a database via a driver-specific connectionhelper function that returns a*DB. No database drivers are includedin the Go standard library. Seehttps://golang.org/s/sqldrivers fora list of third-party drivers.

OpenDB may just validate its arguments without creating a connectionto the database. To verify that the data source name is valid, callDB.Ping.

The returnedDB is safe for concurrent use by multiple goroutinesand maintains its own pool of idle connections. Thus, the OpenDBfunction should be called just once. It is rarely necessary toclose aDB.

func (*DB)Begin¶

func (db *DB) Begin() (*Tx,error)

Begin starts a transaction. The default isolation level is dependent onthe driver.

Begin usescontext.Background internally; to specify the context, useDB.BeginTx.

func (*DB)BeginTx¶added ingo1.8

func (db *DB) BeginTx(ctxcontext.Context, opts *TxOptions) (*Tx,error)

BeginTx starts a transaction.

The provided context is used until the transaction is committed or rolled back.If the context is canceled, the sql package will roll backthe transaction.Tx.Commit will return an error if the context provided toBeginTx is canceled.

The providedTxOptions is optional and may be nil if defaults should be used.If a non-default isolation level is used that the driver doesn't support,an error will be returned.

package mainimport ("context""database/sql""log")var (ctx context.Contextdb  *sql.DB)func main() {tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable})if err != nil {log.Fatal(err)}id := 37_, execErr := tx.Exec(`UPDATE users SET status = ? WHERE id = ?`, "paid", id)if execErr != nil {_ = tx.Rollback()log.Fatal(execErr)}if err := tx.Commit(); err != nil {log.Fatal(err)}}

func (*DB)Close¶

func (db *DB) Close()error

Close closes the database and prevents new queries from starting.Close then waits for all queries that have started processing on the serverto finish.

It is rare to Close aDB, as theDB handle is meant to belong-lived and shared between many goroutines.

func (*DB)Conn¶added ingo1.9

func (db *DB) Conn(ctxcontext.Context) (*Conn,error)

Conn returns a single connection by either opening a new connectionor returning an existing connection from the connection pool. Conn willblock until either a connection is returned or ctx is canceled.Queries run on the same Conn will be run in the same database session.

Every Conn must be returned to the database pool after use bycallingConn.Close.

func (*DB)Driver¶

func (db *DB) Driver()driver.Driver

Driver returns the database's underlying driver.

func (*DB)Exec¶

func (db *DB) Exec(querystring, args ...any) (Result,error)

Exec executes a query without returning any rows.The args are for any placeholder parameters in the query.

Exec usescontext.Background internally; to specify the context, useDB.ExecContext.

func (*DB)ExecContext¶added ingo1.8

func (db *DB) ExecContext(ctxcontext.Context, querystring, args ...any) (Result,error)

ExecContext executes a query without returning any rows.The args are for any placeholder parameters in the query.

package mainimport ("context""database/sql""log")var (ctx context.Contextdb  *sql.DB)func main() {id := 47result, err := db.ExecContext(ctx, "UPDATE balances SET balance = balance + 10 WHERE user_id = ?", id)if err != nil {log.Fatal(err)}rows, err := result.RowsAffected()if err != nil {log.Fatal(err)}if rows != 1 {log.Fatalf("expected to affect 1 row, affected %d", rows)}}

func (*DB)Ping¶added ingo1.1

func (db *DB) Ping()error

Ping verifies a connection to the database is still alive,establishing a connection if necessary.

Ping usescontext.Background internally; to specify the context, useDB.PingContext.

func (*DB)PingContext¶added ingo1.8

func (db *DB) PingContext(ctxcontext.Context)error

PingContext verifies a connection to the database is still alive,establishing a connection if necessary.

package mainimport ("context""database/sql""log""time")var (ctx context.Contextdb  *sql.DB)func main() {// Ping and PingContext may be used to determine if communication with// the database server is still possible.//// When used in a command line application Ping may be used to establish// that further queries are possible; that the provided DSN is valid.//// When used in long running service Ping may be part of the health// checking system.ctx, cancel := context.WithTimeout(ctx, 1*time.Second)defer cancel()status := "up"if err := db.PingContext(ctx); err != nil {status = "down"}log.Println(status)}

func (*DB)Prepare¶

func (db *DB) Prepare(querystring) (*Stmt,error)

Prepare creates a prepared statement for later queries or executions.Multiple queries or executions may be run concurrently from thereturned statement.The caller must call the statement's*Stmt.Close methodwhen the statement is no longer needed.

Prepare usescontext.Background internally; to specify the context, useDB.PrepareContext.

package mainimport ("context""database/sql""log")var db *sql.DBfunc main() {projects := []struct {mascot  stringrelease int}{{"tux", 1991},{"duke", 1996},{"gopher", 2009},{"moby dock", 2013},}stmt, err := db.Prepare("INSERT INTO projects(id, mascot, release, category) VALUES( ?, ?, ?, ? )")if err != nil {log.Fatal(err)}defer stmt.Close() // Prepared statements take up server resources and should be closed after use.for id, project := range projects {if _, err := stmt.Exec(id+1, project.mascot, project.release, "open source"); err != nil {log.Fatal(err)}}}

func (*DB)PrepareContext¶added ingo1.8

func (db *DB) PrepareContext(ctxcontext.Context, querystring) (*Stmt,error)

PrepareContext creates a prepared statement for later queries or executions.Multiple queries or executions may be run concurrently from thereturned statement.The caller must call the statement's*Stmt.Close methodwhen the statement is no longer needed.

The provided context is used for the preparation of the statement, not for theexecution of the statement.

func (*DB)Query¶

func (db *DB) Query(querystring, args ...any) (*Rows,error)

Query executes a query that returns rows, typically a SELECT.The args are for any placeholder parameters in the query.

Query usescontext.Background internally; to specify the context, useDB.QueryContext.

package mainimport ("context""database/sql""log")var db *sql.DBfunc main() {age := 27q := `create temp table uid (id bigint); -- Create temp table for queries.insert into uidselect id from users where age < ?; -- Populate temp table.-- First result set.selectusers.id, namefromusersjoin uid on users.id = uid.id;-- Second result set.select ur.user, ur.rolefromuser_roles as urjoin uid on uid.id = ur.user;`rows, err := db.Query(q, age)if err != nil {log.Fatal(err)}defer rows.Close()for rows.Next() {var (id   int64name string)if err := rows.Scan(&id, &name); err != nil {log.Fatal(err)}log.Printf("id %d name is %s\n", id, name)}if !rows.NextResultSet() {log.Fatalf("expected more result sets: %v", rows.Err())}var roleMap = map[int64]string{1: "user",2: "admin",3: "gopher",}for rows.Next() {var (id   int64role int64)if err := rows.Scan(&id, &role); err != nil {log.Fatal(err)}log.Printf("id %d has role %s\n", id, roleMap[role])}if err := rows.Err(); err != nil {log.Fatal(err)}}

func (*DB)QueryContext¶added ingo1.8

func (db *DB) QueryContext(ctxcontext.Context, querystring, args ...any) (*Rows,error)

QueryContext executes a query that returns rows, typically a SELECT.The args are for any placeholder parameters in the query.

package mainimport ("context""database/sql""fmt""log""strings")var (ctx context.Contextdb  *sql.DB)func main() {age := 27rows, err := db.QueryContext(ctx, "SELECT name FROM users WHERE age=?", age)if err != nil {log.Fatal(err)}defer rows.Close()names := make([]string, 0)for rows.Next() {var name stringif err := rows.Scan(&name); err != nil {// Check for a scan error.// Query rows will be closed with defer.log.Fatal(err)}names = append(names, name)}// If the database is being written to ensure to check for Close// errors that may be returned from the driver. The query may// encounter an auto-commit error and be forced to rollback changes.rerr := rows.Close()if rerr != nil {log.Fatal(rerr)}// Rows.Err will report the last error encountered by Rows.Scan.if err := rows.Err(); err != nil {log.Fatal(err)}fmt.Printf("%s are %d years old", strings.Join(names, ", "), age)}

func (*DB)QueryRow¶

func (db *DB) QueryRow(querystring, args ...any) *Row

QueryRow executes a query that is expected to return at most one row.QueryRow always returns a non-nil value. Errors are deferred untilRow's Scan method is called.If the query selects no rows, the*Row.Scan will returnErrNoRows.Otherwise,*Row.Scan scans the first selected row and discardsthe rest.

QueryRow usescontext.Background internally; to specify the context, useDB.QueryRowContext.

func (*DB)QueryRowContext¶added ingo1.8

func (db *DB) QueryRowContext(ctxcontext.Context, querystring, args ...any) *Row

QueryRowContext executes a query that is expected to return at most one row.QueryRowContext always returns a non-nil value. Errors are deferred untilRow's Scan method is called.If the query selects no rows, the*Row.Scan will returnErrNoRows.Otherwise,*Row.Scan scans the first selected row and discardsthe rest.

package mainimport ("context""database/sql""log""time")var (ctx context.Contextdb  *sql.DB)func main() {id := 123var username stringvar created time.Timeerr := db.QueryRowContext(ctx, "SELECT username, created_at FROM users WHERE id=?", id).Scan(&username, &created)switch {case err == sql.ErrNoRows:log.Printf("no user with id %d\n", id)case err != nil:log.Fatalf("query error: %v\n", err)default:log.Printf("username is %q, account created on %s\n", username, created)}}

func (*DB)SetConnMaxIdleTime¶added ingo1.15

func (db *DB) SetConnMaxIdleTime(dtime.Duration)

SetConnMaxIdleTime sets the maximum amount of time a connection may be idle.

Expired connections may be closed lazily before reuse.

If d <= 0, connections are not closed due to a connection's idle time.

func (*DB)SetConnMaxLifetime¶added ingo1.6

func (db *DB) SetConnMaxLifetime(dtime.Duration)

SetConnMaxLifetime sets the maximum amount of time a connection may be reused.

Expired connections may be closed lazily before reuse.

If d <= 0, connections are not closed due to a connection's age.

func (*DB)SetMaxIdleConns¶added ingo1.1

func (db *DB) SetMaxIdleConns(nint)

SetMaxIdleConns sets the maximum number of connections in the idleconnection pool.

If MaxOpenConns is greater than 0 but less than the new MaxIdleConns,then the new MaxIdleConns will be reduced to match the MaxOpenConns limit.

If n <= 0, no idle connections are retained.

The default max idle connections is currently 2. This may change ina future release.

func (*DB)SetMaxOpenConns¶added ingo1.2

func (db *DB) SetMaxOpenConns(nint)

SetMaxOpenConns sets the maximum number of open connections to the database.

If MaxIdleConns is greater than 0 and the new MaxOpenConns is less thanMaxIdleConns, then MaxIdleConns will be reduced to match the newMaxOpenConns limit.

If n <= 0, then there is no limit on the number of open connections.The default is 0 (unlimited).

func (*DB)Stats¶added ingo1.5

func (db *DB) Stats()DBStats

Stats returns database statistics.

type DBStats struct {MaxOpenConnectionsint// Maximum number of open connections to the database.// Pool StatusOpenConnectionsint// The number of established connections both in use and idle.InUseint// The number of connections currently in use.Idleint// The number of idle connections.// CountersWaitCountint64// The total number of connections waited for.WaitDurationtime.Duration// The total time blocked waiting for a new connection.MaxIdleClosedint64// The total number of connections closed due to SetMaxIdleConns.MaxIdleTimeClosedint64// The total number of connections closed due to SetConnMaxIdleTime.MaxLifetimeClosedint64// The total number of connections closed due to SetConnMaxLifetime.}

type IsolationLevelint

const (LevelDefaultIsolationLevel =iotaLevelReadUncommittedLevelReadCommittedLevelWriteCommittedLevelRepeatableReadLevelSnapshotLevelSerializableLevelLinearizable)

Various isolation levels that drivers may support inDB.BeginTx.If a driver does not support a given isolation level an error may be returned.

Seehttps://en.wikipedia.org/wiki/Isolation_(database_systems)#Isolation_levels.

func (IsolationLevel)String¶added ingo1.11

func (iIsolationLevel) String()string

String returns the name of the transaction isolation level.

type NamedArg struct {// Name is the name of the parameter placeholder.//// If empty, the ordinal position in the argument list will be// used.//// Name must omit any symbol prefix.Namestring// Value is the value of the parameter.// It may be assigned the same value types as the query// arguments.Valueany// contains filtered or unexported fields}

funcNamed¶added ingo1.8

func Named(namestring, valueany)NamedArg

Named provides a more concise way to createNamedArg values.

Example usage:

db.ExecContext(ctx, `    delete from Invoice    where        TimeCreated < @end        and TimeCreated >= @start;`,    sql.Named("start", startTime),    sql.Named("end", endTime),)

type Null[Tany] struct {V     TValidbool}

func (*Null[T])Scan¶added ingo1.22.0

func (n *Null[T]) Scan(valueany)error

func (Null[T])Value¶added ingo1.22.0

func (nNull[T]) Value() (driver.Value,error)

type NullBool struct {BoolboolValidbool// Valid is true if Bool is not NULL}

func (*NullBool)Scan¶

func (n *NullBool) Scan(valueany)error

Scan implements theScanner interface.

func (NullBool)Value¶

func (nNullBool) Value() (driver.Value,error)

Value implements thedriver.Valuer interface.

type NullByte struct {BytebyteValidbool// Valid is true if Byte is not NULL}

func (*NullByte)Scan¶added ingo1.17

func (n *NullByte) Scan(valueany)error

Scan implements theScanner interface.

func (NullByte)Value¶added ingo1.17

func (nNullByte) Value() (driver.Value,error)

Value implements thedriver.Valuer interface.

type NullFloat64 struct {Float64float64Validbool// Valid is true if Float64 is not NULL}

func (*NullFloat64)Scan¶

func (n *NullFloat64) Scan(valueany)error

Scan implements theScanner interface.

func (NullFloat64)Value¶

func (nNullFloat64) Value() (driver.Value,error)

Value implements thedriver.Valuer interface.

type NullInt16 struct {Int16int16Validbool// Valid is true if Int16 is not NULL}

func (*NullInt16)Scan¶added ingo1.17

func (n *NullInt16) Scan(valueany)error

Scan implements theScanner interface.

func (NullInt16)Value¶added ingo1.17

func (nNullInt16) Value() (driver.Value,error)

Value implements thedriver.Valuer interface.

type NullInt32 struct {Int32int32Validbool// Valid is true if Int32 is not NULL}

func (*NullInt32)Scan¶added ingo1.13

func (n *NullInt32) Scan(valueany)error

Scan implements theScanner interface.

func (NullInt32)Value¶added ingo1.13

func (nNullInt32) Value() (driver.Value,error)

Value implements thedriver.Valuer interface.

type NullInt64 struct {Int64int64Validbool// Valid is true if Int64 is not NULL}

func (*NullInt64)Scan¶

func (n *NullInt64) Scan(valueany)error

Scan implements theScanner interface.

func (NullInt64)Value¶

func (nNullInt64) Value() (driver.Value,error)

Value implements thedriver.Valuer interface.

type NullString struct {StringstringValidbool// Valid is true if String is not NULL}

func (*NullString)Scan¶

func (ns *NullString) Scan(valueany)error

Scan implements theScanner interface.

func (NullString)Value¶

func (nsNullString) Value() (driver.Value,error)

Value implements thedriver.Valuer interface.

type NullTime struct {Timetime.TimeValidbool// Valid is true if Time is not NULL}

func (*NullTime)Scan¶added ingo1.13

func (n *NullTime) Scan(valueany)error

Scan implements theScanner interface.

func (NullTime)Value¶added ingo1.13

func (nNullTime) Value() (driver.Value,error)

Value implements thedriver.Valuer interface.

type Out struct {// Dest is a pointer to the value that will be set to the result of the// stored procedure's OUTPUT parameter.Destany// In is whether the parameter is an INOUT parameter. If so, the input value to the stored// procedure is the dereferenced value of Dest's pointer, which is then replaced with// the output value.Inbool// contains filtered or unexported fields}

type RawBytes []byte

type Result interface {// LastInsertId returns the integer generated by the database// in response to a command. Typically this will be from an// "auto increment" column when inserting a new row. Not all// databases support this feature, and the syntax of such// statements varies.LastInsertId() (int64,error)// RowsAffected returns the number of rows affected by an// update, insert, or delete. Not every database or database// driver may support this.RowsAffected() (int64,error)}

type Row struct {// contains filtered or unexported fields}

func (*Row)Err¶added ingo1.15

func (r *Row) Err()error

Err provides a way for wrapping packages to check forquery errors without callingRow.Scan.Err returns the error, if any, that was encountered while running the query.If this error is not nil, this error will also be returned fromRow.Scan.

func (*Row)Scan¶

func (r *Row) Scan(dest ...any)error

Scan copies the columns from the matched row into the valuespointed at by dest. See the documentation onRows.Scan for details.If more than one row matches the query,Scan uses the first row and discards the rest. If no row matchesthe query, Scan returnsErrNoRows.

type Rows struct {// contains filtered or unexported fields}

func (*Rows)Close¶

func (rs *Rows) Close()error

Close closes theRows, preventing further enumeration. IfRows.Next is calledand returns false and there are no further result sets,theRows are closed automatically and it will suffice to check theresult ofRows.Err. Close is idempotent and does not affect the result ofRows.Err.

func (*Rows)ColumnTypes¶added ingo1.8

func (rs *Rows) ColumnTypes() ([]*ColumnType,error)

ColumnTypes returns column information such as column type, length,and nullable. Some information may not be available from some drivers.

func (*Rows)Columns¶

func (rs *Rows) Columns() ([]string,error)

Columns returns the column names.Columns returns an error if the rows are closed.

func (*Rows)Err¶

func (rs *Rows) Err()error

Err returns the error, if any, that was encountered during iteration.Err may be called after an explicit or implicitRows.Close.

func (*Rows)Next¶

func (rs *Rows) Next()bool

Next prepares the next result row for reading with theRows.Scan method. Itreturns true on success, or false if there is no next result row or an errorhappened while preparing it.Rows.Err should be consulted to distinguish betweenthe two cases.

Every call toRows.Scan, even the first one, must be preceded by a call toRows.Next.

func (*Rows)NextResultSet¶added ingo1.8

func (rs *Rows) NextResultSet()bool

NextResultSet prepares the next result set for reading. It reports whetherthere is further result sets, or false if there is no further result setor if there is an error advancing to it. TheRows.Err method should be consultedto distinguish between the two cases.

After calling NextResultSet, theRows.Next method should always be called beforescanning. If there are further result sets they may not have rows in the resultset.

func (*Rows)Scan¶

func (rs *Rows) Scan(dest ...any)error

Scan copies the columns in the current row into the values pointedat by dest. The number of values in dest must be the same as thenumber of columns inRows.

Scan converts columns read from the database into the followingcommon Go types and special types provided by the sql package:

*string*[]byte*int, *int8, *int16, *int32, *int64*uint, *uint8, *uint16, *uint32, *uint64*bool*float32, *float64*interface{}*RawBytes*Rows (cursor value)any type implementing Scanner (see Scanner docs)

In the most simple case, if the type of the value from the sourcecolumn is an integer, bool or string type T and dest is of type *T,Scan simply assigns the value through the pointer.

Scan also converts between string and numeric types, as long as noinformation would be lost. While Scan stringifies all numbersscanned from numeric database columns into *string, scans intonumeric types are checked for overflow. For example, a float64 withvalue 300 or a string with value "300" can scan into a uint16, butnot into a uint8, though float64(255) or "255" can scan into auint8. One exception is that scans of some float64 numbers tostrings may lose information when stringifying. In general, scanfloating point columns into *float64.

If a dest argument has type *[]byte, Scan saves in that argument acopy of the corresponding data. The copy is owned by the caller andcan be modified and held indefinitely. The copy can be avoided byusing an argument of type*RawBytes instead; see the documentationforRawBytes for restrictions on its use.

If an argument has type *interface{}, Scan copies the valueprovided by the underlying driver without conversion. When scanningfrom a source value of type []byte to *interface{}, a copy of theslice is made and the caller owns the result.

Source values of typetime.Time may be scanned into values of type*time.Time, *interface{}, *string, or *[]byte. When converting tothe latter two,time.RFC3339Nano is used.

Source values of type bool may be scanned into types *bool,*interface{}, *string, *[]byte, or*RawBytes.

For scanning into *bool, the source may be true, false, 1, 0, orstring inputs parseable bystrconv.ParseBool.

Scan can also convert a cursor returned from a query, such as"select cursor(select * from my_table) from dual", into a*Rows value that can itself be scanned from. The parentselect query will close any cursor*Rows if the parent*Rows is closed.

If any of the first arguments implementingScanner returns an error,that error will be wrapped in the returned error.

type Scanner interface {// Scan assigns a value from a database driver.//// The src value will be of one of the following types:////    int64//    float64//    bool//    []byte//    string//    time.Time//    nil - for NULL values//// An error should be returned if the value cannot be stored// without loss of information.//// Reference types such as []byte are only valid until the next call to Scan// and should not be retained. Their underlying memory is owned by the driver.// If retention is necessary, copy their values before the next call to Scan.Scan(srcany)error}

type Stmt struct {// contains filtered or unexported fields}

func (*Stmt)Close¶

func (s *Stmt) Close()error

Close closes the statement.

func (*Stmt)Exec¶

func (s *Stmt) Exec(args ...any) (Result,error)

Exec executes a prepared statement with the given arguments andreturns aResult summarizing the effect of the statement.

Exec usescontext.Background internally; to specify the context, useStmt.ExecContext.

func (*Stmt)ExecContext¶added ingo1.8

func (s *Stmt) ExecContext(ctxcontext.Context, args ...any) (Result,error)

ExecContext executes a prepared statement with the given arguments andreturns aResult summarizing the effect of the statement.

func (*Stmt)Query¶

func (s *Stmt) Query(args ...any) (*Rows,error)

Query executes a prepared query statement with the given argumentsand returns the query results as a *Rows.

Query usescontext.Background internally; to specify the context, useStmt.QueryContext.

func (*Stmt)QueryContext¶added ingo1.8

func (s *Stmt) QueryContext(ctxcontext.Context, args ...any) (*Rows,error)

QueryContext executes a prepared query statement with the given argumentsand returns the query results as a*Rows.

func (*Stmt)QueryRow¶

func (s *Stmt) QueryRow(args ...any) *Row

QueryRow executes a prepared query statement with the given arguments.If an error occurs during the execution of the statement, that error willbe returned by a call to Scan on the returned*Row, which is always non-nil.If the query selects no rows, the*Row.Scan will returnErrNoRows.Otherwise, the*Row.Scan scans the first selected row and discardsthe rest.

Example usage:

var name stringerr := nameByUseridStmt.QueryRow(id).Scan(&name)

QueryRow usescontext.Background internally; to specify the context, useStmt.QueryRowContext.

func (*Stmt)QueryRowContext¶added ingo1.8

func (s *Stmt) QueryRowContext(ctxcontext.Context, args ...any) *Row

QueryRowContext executes a prepared query statement with the given arguments.If an error occurs during the execution of the statement, that error willbe returned by a call to Scan on the returned*Row, which is always non-nil.If the query selects no rows, the*Row.Scan will returnErrNoRows.Otherwise, the*Row.Scan scans the first selected row and discardsthe rest.

package mainimport ("context""database/sql""log")var (ctx context.Contextdb  *sql.DB)func main() {// In normal use, create one Stmt when your process starts.stmt, err := db.PrepareContext(ctx, "SELECT username FROM users WHERE id = ?")if err != nil {log.Fatal(err)}defer stmt.Close()// Then reuse it each time you need to issue the query.id := 43var username stringerr = stmt.QueryRowContext(ctx, id).Scan(&username)switch {case err == sql.ErrNoRows:log.Fatalf("no user with id %d", id)case err != nil:log.Fatal(err)default:log.Printf("username is %s\n", username)}}

type Tx struct {// contains filtered or unexported fields}

func (*Tx)Commit¶

func (tx *Tx) Commit()error

Commit commits the transaction.

func (*Tx)Exec¶

func (tx *Tx) Exec(querystring, args ...any) (Result,error)

Exec executes a query that doesn't return rows.For example: an INSERT and UPDATE.

Exec usescontext.Background internally; to specify the context, useTx.ExecContext.

func (*Tx)ExecContext¶added ingo1.8

func (tx *Tx) ExecContext(ctxcontext.Context, querystring, args ...any) (Result,error)

ExecContext executes a query that doesn't return rows.For example: an INSERT and UPDATE.

package mainimport ("context""database/sql""log")var (ctx context.Contextdb  *sql.DB)func main() {tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable})if err != nil {log.Fatal(err)}id := 37_, execErr := tx.ExecContext(ctx, "UPDATE users SET status = ? WHERE id = ?", "paid", id)if execErr != nil {if rollbackErr := tx.Rollback(); rollbackErr != nil {log.Fatalf("update failed: %v, unable to rollback: %v\n", execErr, rollbackErr)}log.Fatalf("update failed: %v", execErr)}if err := tx.Commit(); err != nil {log.Fatal(err)}}

func (*Tx)Prepare¶

func (tx *Tx) Prepare(querystring) (*Stmt,error)

Prepare creates a prepared statement for use within a transaction.

The returned statement operates within the transaction and will be closedwhen the transaction has been committed or rolled back.

To use an existing prepared statement on this transaction, seeTx.Stmt.

Prepare usescontext.Background internally; to specify the context, useTx.PrepareContext.

package mainimport ("context""database/sql""log")var db *sql.DBfunc main() {projects := []struct {mascot  stringrelease int}{{"tux", 1991},{"duke", 1996},{"gopher", 2009},{"moby dock", 2013},}tx, err := db.Begin()if err != nil {log.Fatal(err)}defer tx.Rollback() // The rollback will be ignored if the tx has been committed later in the function.stmt, err := tx.Prepare("INSERT INTO projects(id, mascot, release, category) VALUES( ?, ?, ?, ? )")if err != nil {log.Fatal(err)}defer stmt.Close() // Prepared statements take up server resources and should be closed after use.for id, project := range projects {if _, err := stmt.Exec(id+1, project.mascot, project.release, "open source"); err != nil {log.Fatal(err)}}if err := tx.Commit(); err != nil {log.Fatal(err)}}

func (*Tx)PrepareContext¶added ingo1.8

func (tx *Tx) PrepareContext(ctxcontext.Context, querystring) (*Stmt,error)

PrepareContext creates a prepared statement for use within a transaction.

The returned statement operates within the transaction and will be closedwhen the transaction has been committed or rolled back.

To use an existing prepared statement on this transaction, seeTx.Stmt.

The provided context will be used for the preparation of the context, notfor the execution of the returned statement. The returned statementwill run in the transaction context.

func (*Tx)Query¶

func (tx *Tx) Query(querystring, args ...any) (*Rows,error)

Query executes a query that returns rows, typically a SELECT.

Query usescontext.Background internally; to specify the context, useTx.QueryContext.

func (*Tx)QueryContext¶added ingo1.8

func (tx *Tx) QueryContext(ctxcontext.Context, querystring, args ...any) (*Rows,error)

QueryContext executes a query that returns rows, typically a SELECT.

func (*Tx)QueryRow¶

func (tx *Tx) QueryRow(querystring, args ...any) *Row

QueryRow executes a query that is expected to return at most one row.QueryRow always returns a non-nil value. Errors are deferred untilRow's Scan method is called.If the query selects no rows, the*Row.Scan will returnErrNoRows.Otherwise, the*Row.Scan scans the first selected row and discardsthe rest.

QueryRow usescontext.Background internally; to specify the context, useTx.QueryRowContext.

func (*Tx)QueryRowContext¶added ingo1.8

func (tx *Tx) QueryRowContext(ctxcontext.Context, querystring, args ...any) *Row

QueryRowContext executes a query that is expected to return at most one row.QueryRowContext always returns a non-nil value. Errors are deferred untilRow's Scan method is called.If the query selects no rows, the*Row.Scan will returnErrNoRows.Otherwise, the*Row.Scan scans the first selected row and discardsthe rest.

func (*Tx)Rollback¶

func (tx *Tx) Rollback()error

Rollback aborts the transaction.

package mainimport ("context""database/sql""log")var (ctx context.Contextdb  *sql.DB)func main() {tx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable})if err != nil {log.Fatal(err)}id := 53_, err = tx.ExecContext(ctx, "UPDATE drivers SET status = ? WHERE id = ?;", "assigned", id)if err != nil {if rollbackErr := tx.Rollback(); rollbackErr != nil {log.Fatalf("update drivers: unable to rollback: %v", rollbackErr)}log.Fatal(err)}_, err = tx.ExecContext(ctx, "UPDATE pickups SET driver_id = $1;", id)if err != nil {if rollbackErr := tx.Rollback(); rollbackErr != nil {log.Fatalf("update failed: %v, unable to back: %v", err, rollbackErr)}log.Fatal(err)}if err := tx.Commit(); err != nil {log.Fatal(err)}}

func (*Tx)Stmt¶

func (tx *Tx) Stmt(stmt *Stmt) *Stmt

Stmt returns a transaction-specific prepared statement froman existing statement.

Example:

updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")...tx, err := db.Begin()...res, err := tx.Stmt(updateMoney).Exec(123.45, 98293203)

The returned statement operates within the transaction and will be closedwhen the transaction has been committed or rolled back.

Stmt usescontext.Background internally; to specify the context, useTx.StmtContext.

func (*Tx)StmtContext¶added ingo1.8

func (tx *Tx) StmtContext(ctxcontext.Context, stmt *Stmt) *Stmt

StmtContext returns a transaction-specific prepared statement froman existing statement.

Example:

updateMoney, err := db.Prepare("UPDATE balance SET money=money+? WHERE id=?")...tx, err := db.Begin()...res, err := tx.StmtContext(ctx, updateMoney).Exec(123.45, 98293203)

The provided context is used for the preparation of the statement, not for theexecution of the statement.

The returned statement operates within the transaction and will be closedwhen the transaction has been committed or rolled back.

type TxOptions struct {// Isolation is the transaction isolation level.// If zero, the driver or database's default level is used.IsolationIsolationLevelReadOnlybool}