driver

ColumnConverter interface #

ColumnConverter may be optionally implemented by [Stmt] if the statement is aware of its own columns' types and can convert from any type to a driver [Value]. Deprecated: Drivers should implement [NamedValueChecker].

type ColumnConverter interface {
ColumnConverter(idx int) ValueConverter
}

Conn interface #

Conn is a connection to a database. It is not used concurrently by multiple goroutines. Conn is assumed to be stateful.

type Conn interface {
Prepare(query string) (Stmt, error)
Close() error
Begin() (Tx, error)
}

ConnBeginTx interface #

ConnBeginTx enhances the [Conn] interface with context and [TxOptions].

type ConnBeginTx interface {
BeginTx(ctx context.Context, opts TxOptions) (Tx, error)
}

ConnPrepareContext interface #

ConnPrepareContext enhances the [Conn] interface with context.

type ConnPrepareContext interface {
PrepareContext(ctx context.Context, query string) (Stmt, error)
}

Connector interface #

A Connector represents a driver in a fixed configuration and can create any number of equivalent Conns for use by multiple goroutines. A Connector can be passed to [database/sql.OpenDB], to allow drivers to implement their own [database/sql.DB] constructors, or returned by [DriverContext]'s OpenConnector method, to allow drivers access to context and to avoid repeated parsing of driver configuration. If a Connector implements [io.Closer], the [database/sql.DB.Close] method will call the Close method and return error (if any).

type Connector interface {
Connect(context.Context) (Conn, error)
Driver() Driver
}

Driver interface #

Driver is the interface that must be implemented by a database driver. Database drivers may implement [DriverContext] for access to contexts and to parse the name only once for a pool of connections, instead of once per connection.

type Driver interface {
Open(name string) (Conn, error)
}

DriverContext interface #

If a [Driver] implements DriverContext, then [database/sql.DB] will call OpenConnector to obtain a [Connector] and then invoke that [Connector]'s Connect method to obtain each needed connection, instead of invoking the [Driver]'s Open method for each connection. The two-step sequence allows drivers to parse the name just once and also provides access to per-[Conn] contexts.

type DriverContext interface {
OpenConnector(name string) (Connector, error)
}

Execer interface #

Execer is an optional interface that may be implemented by a [Conn]. If a [Conn] implements neither [ExecerContext] nor [Execer], the [database/sql.DB.Exec] will first prepare a query, execute the statement, and then close the statement. Exec may return [ErrSkip]. Deprecated: Drivers should implement [ExecerContext] instead.

type Execer interface {
Exec(query string, args []Value) (Result, error)
}

ExecerContext interface #

ExecerContext is an optional interface that may be implemented by a [Conn]. If a [Conn] does not implement [ExecerContext], the [database/sql.DB.Exec] will fall back to [Execer]; if the Conn does not implement Execer either, [database/sql.DB.Exec] will first prepare a query, execute the statement, and then close the statement. ExecContext may return [ErrSkip]. ExecContext must honor the context timeout and return when the context is canceled.

type ExecerContext interface {
ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
}

NamedValueChecker interface #

NamedValueChecker may be optionally implemented by [Conn] or [Stmt]. It provides the driver more control to handle Go and database types beyond the default [Value] types allowed. The [database/sql] package checks for value checkers in the following order, stopping at the first found match: Stmt.NamedValueChecker, Conn.NamedValueChecker, Stmt.ColumnConverter, [DefaultParameterConverter]. If CheckNamedValue returns [ErrRemoveArgument], the [NamedValue] will not be included in the final query arguments. This may be used to pass special options to the query itself. If [ErrSkip] is returned the column converter error checking path is used for the argument. Drivers may wish to return [ErrSkip] after they have exhausted their own special cases.

type NamedValueChecker interface {
CheckNamedValue(*NamedValue) error
}

Pinger interface #

Pinger is an optional interface that may be implemented by a [Conn]. If a [Conn] does not implement Pinger, the [database/sql.DB.Ping] and [database/sql.DB.PingContext] will check if there is at least one [Conn] available. If Conn.Ping returns [ErrBadConn], [database/sql.DB.Ping] and [database/sql.DB.PingContext] will remove the [Conn] from pool.

type Pinger interface {
Ping(ctx context.Context) error
}

Queryer interface #

Queryer is an optional interface that may be implemented by a [Conn]. If a [Conn] implements neither [QueryerContext] nor [Queryer], the [database/sql.DB.Query] will first prepare a query, execute the statement, and then close the statement. Query may return [ErrSkip]. Deprecated: Drivers should implement [QueryerContext] instead.

type Queryer interface {
Query(query string, args []Value) (Rows, error)
}

QueryerContext interface #

QueryerContext is an optional interface that may be implemented by a [Conn]. If a [Conn] does not implement QueryerContext, the [database/sql.DB.Query] will fall back to [Queryer]; if the [Conn] does not implement [Queryer] either, [database/sql.DB.Query] will first prepare a query, execute the statement, and then close the statement. QueryContext may return [ErrSkip]. QueryContext must honor the context timeout and return when the context is canceled.

type QueryerContext interface {
QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
}

Result interface #

Result is the result of a query execution.

type Result interface {
LastInsertId() (int64, error)
RowsAffected() (int64, error)
}

Rows interface #

Rows is an iterator over an executed query's results.

type Rows interface {
Columns() []string
Close() error
Next(dest []Value) error
}

RowsColumnTypeDatabaseTypeName interface #

RowsColumnTypeDatabaseTypeName may be implemented by [Rows]. It should return the database system type name without the length. Type names should be uppercase. Examples of returned types: "VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT", "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML", "TIMESTAMP".

type RowsColumnTypeDatabaseTypeName interface {
Rows
ColumnTypeDatabaseTypeName(index int) string
}

RowsColumnTypeLength interface #

RowsColumnTypeLength may be implemented by [Rows]. It should return the length of the column type if the column is a variable length type. If the column is not a variable length type ok should return false. If length is not limited other than system limits, it should return [math.MaxInt64]. The following are examples of returned values for various types: TEXT (math.MaxInt64, true) varchar(10) (10, true) nvarchar(10) (10, true) decimal (0, false) int (0, false) bytea(30) (30, true)

type RowsColumnTypeLength interface {
Rows
ColumnTypeLength(index int) (length int64, ok bool)
}

RowsColumnTypeNullable interface #

RowsColumnTypeNullable may be implemented by [Rows]. The nullable value should be true if it is known the column may be null, or false if the column is known to be not nullable. If the column nullability is unknown, ok should be false.

type RowsColumnTypeNullable interface {
Rows
ColumnTypeNullable(index int) (nullable bool, ok bool)
}

RowsColumnTypePrecisionScale interface #

RowsColumnTypePrecisionScale may be implemented by [Rows]. It should return the precision and scale for decimal types. If not applicable, ok should be false. The following are examples of returned values for various types: decimal(38, 4) (38, 4, true) int (0, 0, false) decimal (math.MaxInt64, math.MaxInt64, true)

type RowsColumnTypePrecisionScale interface {
Rows
ColumnTypePrecisionScale(index int) (precision int64, scale int64, ok bool)
}

RowsColumnTypeScanType interface #

RowsColumnTypeScanType may be implemented by [Rows]. It should return the value type that can be used to scan types into. For example, the database column type "bigint" this should return "[reflect.TypeOf](int64(0))".

type RowsColumnTypeScanType interface {
Rows
ColumnTypeScanType(index int) reflect.Type
}

RowsNextResultSet interface #

RowsNextResultSet extends the [Rows] interface by providing a way to signal the driver to advance to the next result set.

type RowsNextResultSet interface {
Rows
HasNextResultSet() bool
NextResultSet() error
}

SessionResetter interface #

SessionResetter may be implemented by [Conn] to allow drivers to reset the session state associated with the connection and to signal a bad connection.

type SessionResetter interface {
ResetSession(ctx context.Context) error
}

Stmt interface #

Stmt is a prepared statement. It is bound to a [Conn] and not used by multiple goroutines concurrently.

type Stmt interface {
Close() error
NumInput() int
Exec(args []Value) (Result, error)
Query(args []Value) (Rows, error)
}

StmtExecContext interface #

StmtExecContext enhances the [Stmt] interface by providing Exec with context.

type StmtExecContext interface {
ExecContext(ctx context.Context, args []NamedValue) (Result, error)
}

StmtQueryContext interface #

StmtQueryContext enhances the [Stmt] interface by providing Query with context.

type StmtQueryContext interface {
QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
}

Tx interface #

Tx is a transaction.

type Tx interface {
Commit() error
Rollback() error
}

Validator interface #

Validator may be implemented by [Conn] to allow drivers to signal if a connection is valid or if it should be discarded. If implemented, drivers may return the underlying error from queries, even if the connection should be discarded by the connection pool.

type Validator interface {
IsValid() bool
}

ValueConverter interface #

ValueConverter is the interface providing the ConvertValue method. Various implementations of ValueConverter are provided by the driver package to provide consistent implementations of conversions between drivers. The ValueConverters have several uses: - converting from the [Value] types as provided by the sql package into a database table's specific column type and making sure it fits, such as making sure a particular int64 fits in a table's uint16 column. - converting a value as given from the database into one of the driver [Value] types. - by the [database/sql] package, for converting from a driver's [Value] type to a user's type in a scan.

type ValueConverter interface {
ConvertValue(v any) (Value, error)
}

Valuer interface #

Valuer is the interface providing the Value method. Errors returned by the [Value] method are wrapped by the database/sql package. This allows callers to use [errors.Is] for precise error handling after operations like [database/sql.Query], [database/sql.Exec], or [database/sql.QueryRow]. Types implementing Valuer interface are able to convert themselves to a driver [Value].

type Valuer interface {
Value() (Value, error)
}

decimalDecompose interface #

type decimalDecompose interface {
Decompose(buf []byte) (form byte, negative bool, coefficient []byte, exponent int32)
}