Involved Source Files Package driver defines interfaces to be implemented by database
drivers as used by package sql.
Most code should use package sql.
The driver interface has evolved over time. Drivers should implement
Connector and DriverContext interfaces.
The Connector.Connect and Driver.Open methods should never return ErrBadConn.
ErrBadConn should only be returned from Validator, SessionResetter, or
a query method if the connection is already in an invalid (e.g. closed) state.
All Conn implementations should implement the following interfaces:
Pinger, SessionResetter, and Validator.
If named parameters or context are supported, the driver's Conn should implement:
ExecerContext, QueryerContext, ConnPrepareContext, and ConnBeginTx.
To support custom data types, implement NamedValueChecker. NamedValueChecker
also allows queries to accept per-query options as a parameter by returning
ErrRemoveArgument from CheckNamedValue.
If multiple result sets are supported, Rows should implement RowsNextResultSet.
If the driver knows how to describe the types present in the returned result
it should implement the following interfaces: RowsColumnTypeScanType,
RowsColumnTypeDatabaseTypeName, RowsColumnTypeLength, RowsColumnTypeNullable,
and RowsColumnTypePrecisionScale. A given row value may also return a Rows
type, which may represent a database cursor value.
Before a connection is returned to the connection pool after use, IsValid is
called if implemented. Before a connection is reused for another query,
ResetSession is called if implemented. If a connection is never returned to the
connection pool but immediately reused, then ResetSession is called prior to
reuse but IsValid is not called.types.go
Package-Level Type Names (total 36)
/* sort by: | */
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. ColumnConverter returns a ValueConverter for the provided
column index. If the type of a specific column isn't known
or shouldn't be handled specially, DefaultValueConverter
can be returned.
Conn is a connection to a database. It is not used concurrently
by multiple goroutines.
Conn is assumed to be stateful. Begin starts and returns a new transaction.
Deprecated: Drivers should implement ConnBeginTx instead (or additionally). Close invalidates and potentially stops any current
prepared statements and transactions, marking this
connection as no longer in use.
Because the sql package maintains a free pool of
connections and only calls Close when there's a surplus of
idle connections, it shouldn't be necessary for drivers to
do their own connection caching.
Drivers must ensure all network calls made by Close
do not block indefinitely (e.g. apply a timeout). Prepare returns a prepared statement, bound to this connection.
*github.com/jackc/pgx/v5/stdlib.Conn
Conn : io.Closer
func Connector.Connect(context.Context) (Conn, error)
func Driver.Open(name string) (Conn, error)
func github.com/go-sql-driver/mysql.MySQLDriver.Open(dsn string) (Conn, error)
func github.com/jackc/pgx/v5/stdlib.(*Driver).Open(name string) (Conn, error)
ConnBeginTx enhances the Conn interface with context and TxOptions. BeginTx starts and returns a new transaction.
If the context is canceled by the user the sql package will
call Tx.Rollback before discarding and closing the connection.
This must check opts.Isolation to determine if there is a set
isolation level. If the driver does not support a non-default
level and one is set or if there is a non-default isolation level
that is not supported, an error must be returned.
This must also check opts.ReadOnly to determine if the read-only
value is true to either set the read-only transaction property if supported
or return an error if it is not supported.
*github.com/jackc/pgx/v5/stdlib.Conn
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 sql.OpenDB, to allow drivers
to implement their own 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 sql package's DB.Close
method will call Close and return error (if any). Connect returns a connection to the database.
Connect may return a cached connection (one previously
closed), but doing so is unnecessary; the sql package
maintains a pool of idle connections for efficient re-use.
The provided context.Context is for dialing purposes only
(see net.DialContext) and should not be stored or used for
other purposes. A default timeout should still be used
when dialing as a connection pool may call Connect
asynchronously to any query.
The returned connection is only used by one goroutine at a
time. Driver returns the underlying Driver of the Connector,
mainly to maintain compatibility with the Driver method
on sql.DB.
func DriverContext.OpenConnector(name string) (Connector, error)
func github.com/go-sql-driver/mysql.NewConnector(cfg *mysql.Config) (Connector, error)
func github.com/go-sql-driver/mysql.MySQLDriver.OpenConnector(dsn string) (Connector, error)
func github.com/jackc/pgx/v5/stdlib.GetConnector(config pgx.ConnConfig, opts ...stdlib.OptionOpenDB) Connector
func github.com/jackc/pgx/v5/stdlib.(*Driver).OpenConnector(name string) (Connector, error)
func database/sql.OpenDB(c Connector) *sql.DB
ConnPrepareContext enhances the Conn interface with context. PrepareContext returns a prepared statement, bound to this connection.
context is for the preparation of the statement,
it must not store the context within the statement itself.
*github.com/jackc/pgx/v5/stdlib.Conn
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. Open returns a new connection to the database.
The name is a string in a driver-specific format.
Open may return a cached connection (one previously
closed), but doing so is unnecessary; the sql package
maintains a pool of idle connections for efficient re-use.
The returned connection is only used by one goroutine at a
time.
github.com/go-sql-driver/mysql.MySQLDriver
*github.com/jackc/pgx/v5/stdlib.Driver
func Connector.Driver() Driver
func database/sql.(*DB).Driver() Driver
func github.com/jackc/pgx/v5/stdlib.GetDefaultDriver() Driver
func database/sql.Register(name string, driver Driver)
If a Driver implements DriverContext, then 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. OpenConnector must parse the name in the same format that Driver.Open
parses the name parameter.
github.com/go-sql-driver/mysql.MySQLDriver
*github.com/jackc/pgx/v5/stdlib.Driver
Execer is an optional interface that may be implemented by a Conn.
If a Conn implements neither ExecerContext nor Execer,
the sql package's 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.( Execer) Exec(query string, args []Value) (Result, error)
ExecerContext is an optional interface that may be implemented by a Conn.
If a Conn does not implement ExecerContext, the sql package's DB.Exec
will fall back to Execer; if the Conn does not implement Execer either,
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.( ExecerContext) ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
*github.com/jackc/pgx/v5/stdlib.Conn
IsolationLevel is the transaction isolation level stored in TxOptions.
This type should be considered identical to sql.IsolationLevel along
with any values defined on it.
NamedValueChecker may be optionally implemented by Conn or Stmt. It provides
the driver more control to handle Go and database types beyond the default
Values types allowed.
The 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. CheckNamedValue is called before passing arguments to the driver
and is called in place of any ColumnConverter. CheckNamedValue must do type
validation and conversion as appropriate for the driver.
*github.com/jackc/pgx/v5/stdlib.Conn
Pinger is an optional interface that may be implemented by a Conn.
If a Conn does not implement Pinger, the sql package's DB.Ping and
DB.PingContext will check if there is at least one Conn available.
If Conn.Ping returns ErrBadConn, DB.Ping and DB.PingContext will remove
the Conn from pool.( Pinger) Ping(ctx context.Context) error
*github.com/jackc/pgx/v5.Conn
*github.com/jackc/pgx/v5/pgconn.PgConn
*github.com/jackc/pgx/v5/stdlib.Conn
Queryer is an optional interface that may be implemented by a Conn.
If a Conn implements neither QueryerContext nor Queryer,
the sql package's 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.( Queryer) Query(query string, args []Value) (Rows, error)
QueryerContext is an optional interface that may be implemented by a Conn.
If a Conn does not implement QueryerContext, the sql package's DB.Query
will fall back to Queryer; if the Conn does not implement Queryer either,
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.( QueryerContext) QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
*github.com/jackc/pgx/v5/stdlib.Conn
RowsAffected implements Result for an INSERT or UPDATE operation
which mutates a number of rows.( RowsAffected) LastInsertId() (int64, error)( RowsAffected) RowsAffected() (int64, error)
RowsAffected : Result
RowsAffected : database/sql.Result
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". Close closes the rows iterator.( RowsColumnTypeDatabaseTypeName) ColumnTypeDatabaseTypeName(index int) string Columns returns the names of the columns. The number of
columns of the result is inferred from the length of the
slice. If a particular column name isn't known, an empty
string should be returned for that entry. Next is called to populate the next row of data into
the provided slice. The provided slice will be the same
size as the Columns() are wide.
Next should return io.EOF when there are no more rows.
The dest should not be written to outside of Next. Care
should be taken when closing Rows not to modify
a buffer held in dest.
*github.com/jackc/pgx/v5/stdlib.Rows
RowsColumnTypeDatabaseTypeName : Rows
RowsColumnTypeDatabaseTypeName : io.Closer
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) Close closes the rows iterator.( RowsColumnTypeLength) ColumnTypeLength(index int) (length int64, ok bool) Columns returns the names of the columns. The number of
columns of the result is inferred from the length of the
slice. If a particular column name isn't known, an empty
string should be returned for that entry. Next is called to populate the next row of data into
the provided slice. The provided slice will be the same
size as the Columns() are wide.
Next should return io.EOF when there are no more rows.
The dest should not be written to outside of Next. Care
should be taken when closing Rows not to modify
a buffer held in dest.
*github.com/jackc/pgx/v5/stdlib.Rows
RowsColumnTypeLength : Rows
RowsColumnTypeLength : io.Closer
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. Close closes the rows iterator.( RowsColumnTypeNullable) ColumnTypeNullable(index int) (nullable, ok bool) Columns returns the names of the columns. The number of
columns of the result is inferred from the length of the
slice. If a particular column name isn't known, an empty
string should be returned for that entry. Next is called to populate the next row of data into
the provided slice. The provided slice will be the same
size as the Columns() are wide.
Next should return io.EOF when there are no more rows.
The dest should not be written to outside of Next. Care
should be taken when closing Rows not to modify
a buffer held in dest.
RowsColumnTypeNullable : Rows
RowsColumnTypeNullable : io.Closer
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) Close closes the rows iterator.( RowsColumnTypePrecisionScale) ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool) Columns returns the names of the columns. The number of
columns of the result is inferred from the length of the
slice. If a particular column name isn't known, an empty
string should be returned for that entry. Next is called to populate the next row of data into
the provided slice. The provided slice will be the same
size as the Columns() are wide.
Next should return io.EOF when there are no more rows.
The dest should not be written to outside of Next. Care
should be taken when closing Rows not to modify
a buffer held in dest.
*github.com/jackc/pgx/v5/stdlib.Rows
RowsColumnTypePrecisionScale : Rows
RowsColumnTypePrecisionScale : io.Closer
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))". Close closes the rows iterator.( RowsColumnTypeScanType) ColumnTypeScanType(index int) reflect.Type Columns returns the names of the columns. The number of
columns of the result is inferred from the length of the
slice. If a particular column name isn't known, an empty
string should be returned for that entry. Next is called to populate the next row of data into
the provided slice. The provided slice will be the same
size as the Columns() are wide.
Next should return io.EOF when there are no more rows.
The dest should not be written to outside of Next. Care
should be taken when closing Rows not to modify
a buffer held in dest.
*github.com/jackc/pgx/v5/stdlib.Rows
RowsColumnTypeScanType : Rows
RowsColumnTypeScanType : io.Closer
RowsNextResultSet extends the Rows interface by providing a way to signal
the driver to advance to the next result set. Close closes the rows iterator. Columns returns the names of the columns. The number of
columns of the result is inferred from the length of the
slice. If a particular column name isn't known, an empty
string should be returned for that entry. HasNextResultSet is called at the end of the current result set and
reports whether there is another result set after the current one. Next is called to populate the next row of data into
the provided slice. The provided slice will be the same
size as the Columns() are wide.
Next should return io.EOF when there are no more rows.
The dest should not be written to outside of Next. Care
should be taken when closing Rows not to modify
a buffer held in dest. NextResultSet advances the driver to the next result set even
if there are remaining rows in the current result set.
NextResultSet should return io.EOF when there are no more result sets.
RowsNextResultSet : Rows
RowsNextResultSet : io.Closer
SessionResetter may be implemented by Conn to allow drivers to reset the
session state associated with the connection and to signal a bad connection. ResetSession is called prior to executing a query on the connection
if the connection has been used before. If the driver returns ErrBadConn
the connection is discarded.
*github.com/jackc/pgx/v5/stdlib.Conn
Stmt is a prepared statement. It is bound to a Conn and not
used by multiple goroutines concurrently. Close closes the statement.
As of Go 1.1, a Stmt will not be closed if it's in use
by any queries.
Drivers must ensure all network calls made by Close
do not block indefinitely (e.g. apply a timeout). Exec executes a query that doesn't return rows, such
as an INSERT or UPDATE.
Deprecated: Drivers should implement StmtExecContext instead (or additionally). NumInput returns the number of placeholder parameters.
If NumInput returns >= 0, the sql package will sanity check
argument counts from callers and return errors to the caller
before the statement's Exec or Query methods are called.
NumInput may also return -1, if the driver doesn't know
its number of placeholders. In that case, the sql package
will not sanity check Exec or Query argument counts. Query executes a query that may return rows, such as a
SELECT.
Deprecated: Drivers should implement StmtQueryContext instead (or additionally).
*github.com/jackc/pgx/v5/stdlib.Stmt
Stmt : io.Closer
func Conn.Prepare(query string) (Stmt, error)
func ConnPrepareContext.PrepareContext(ctx context.Context, query string) (Stmt, error)
func github.com/jackc/pgx/v5/stdlib.(*Conn).Prepare(query string) (Stmt, error)
func github.com/jackc/pgx/v5/stdlib.(*Conn).PrepareContext(ctx context.Context, query string) (Stmt, error)
StmtExecContext enhances the Stmt interface by providing Exec with context. ExecContext executes a query that doesn't return rows, such
as an INSERT or UPDATE.
ExecContext must honor the context timeout and return when it is canceled.
*github.com/jackc/pgx/v5/stdlib.Stmt
StmtQueryContext enhances the Stmt interface by providing Query with context. QueryContext executes a query that may return rows, such as a
SELECT.
QueryContext must honor the context timeout and return when it is canceled.
*github.com/jackc/pgx/v5/stdlib.Stmt
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. IsValid is called prior to placing the connection into the
connection pool. The connection will be discarded if false is returned.
go/token.Pos
*go/token.Position
internal/reflectlite.Value
net/netip.Addr
net/netip.AddrPort
net/netip.Prefix
reflect.Value
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 sql package, for converting from a driver's Value type
to a user's type in a scan. ConvertValue converts a value to a driver Value.NotNullNull
func ColumnConverter.ColumnConverter(idx int) ValueConverter
Valuer is the interface providing the Value method.
Types implementing Valuer interface are able to convert
themselves to a driver Value. Value returns a driver Value.
Value must not panic.
database/sql.NullBool
database/sql.NullByte
database/sql.NullFloat64
database/sql.NullInt16
database/sql.NullInt32
database/sql.NullInt64
database/sql.NullString
database/sql.NullTime
github.com/dariubs/gorm-jsonb.JSONB
github.com/go-sql-driver/mysql.NullTime
github.com/gofrs/uuid.NullUUID
github.com/gofrs/uuid.UUID
github.com/google/uuid.NullUUID
github.com/google/uuid.UUID
github.com/jackc/pgx/v5/pgtype.Bits
github.com/jackc/pgx/v5/pgtype.Bool
github.com/jackc/pgx/v5/pgtype.Box
github.com/jackc/pgx/v5/pgtype.Circle
github.com/jackc/pgx/v5/pgtype.Date
github.com/jackc/pgx/v5/pgtype.Float4
github.com/jackc/pgx/v5/pgtype.Float8
github.com/jackc/pgx/v5/pgtype.Hstore
github.com/jackc/pgx/v5/pgtype.Int2
github.com/jackc/pgx/v5/pgtype.Int4
github.com/jackc/pgx/v5/pgtype.Int8
github.com/jackc/pgx/v5/pgtype.Interval
github.com/jackc/pgx/v5/pgtype.Line
github.com/jackc/pgx/v5/pgtype.Lseg
github.com/jackc/pgx/v5/pgtype.Numeric
github.com/jackc/pgx/v5/pgtype.Path
github.com/jackc/pgx/v5/pgtype.Point
github.com/jackc/pgx/v5/pgtype.Polygon
github.com/jackc/pgx/v5/pgtype.Text
github.com/jackc/pgx/v5/pgtype.TID
github.com/jackc/pgx/v5/pgtype.Time
github.com/jackc/pgx/v5/pgtype.Timestamp
github.com/jackc/pgx/v5/pgtype.Timestamptz
github.com/jackc/pgx/v5/pgtype.Uint32
github.com/jackc/pgx/v5/pgtype.UUID
github.com/segmentio/ksuid.KSUID
gorm.io/gorm.DeletedAt
Package-Level Functions (total 2)
IsScanValue is equivalent to IsValue.
It exists for compatibility.
IsValue reports whether v is a valid Value parameter type.
Package-Level Variables (total 8)
Bool is a ValueConverter that converts input values to bools.
The conversion rules are:
- booleans are returned unchanged
- for integer types,
1 is true
0 is false,
other integers are an error
- for strings and []byte, same rules as strconv.ParseBool
- all other types are an error
DefaultParameterConverter is the default implementation of
ValueConverter that's used when a Stmt doesn't implement
ColumnConverter.
DefaultParameterConverter returns its argument directly if
IsValue(arg). Otherwise, if the argument implements Valuer, its
Value method is used to return a Value. As a fallback, the provided
argument's underlying type is used to convert it to a Value:
underlying integer types are converted to int64, floats to float64,
bool, string, and []byte to themselves. If the argument is a nil
pointer, ConvertValue returns a nil Value. If the argument is a
non-nil pointer, it is dereferenced and ConvertValue is called
recursively. Other types are an error.
ErrBadConn should be returned by a driver to signal to the sql
package that a driver.Conn is in a bad state (such as the server
having earlier closed the connection) and the sql package should
retry on a new connection.
To prevent duplicate operations, ErrBadConn should NOT be returned
if there's a possibility that the database server might have
performed the operation. Even if the server sends back an error,
you shouldn't return ErrBadConn.
Errors will be checked using errors.Is. An error may
wrap ErrBadConn or implement the Is(error) bool method.
ErrRemoveArgument may be returned from NamedValueChecker to instruct the
sql package to not pass the argument to the driver query interface.
Return when accepting query specific options or structures that aren't
SQL query arguments.
ErrSkip may be returned by some optional interfaces' methods to
indicate at runtime that the fast path is unavailable and the sql
package should continue as if the optional interface was not
implemented. ErrSkip is only supported where explicitly
documented.
Int32 is a ValueConverter that converts input values to int64,
respecting the limits of an int32 value.
ResultNoRows is a pre-defined Result for drivers to return when a DDL
command (such as a CREATE TABLE) succeeds. It returns an error for both
LastInsertId and RowsAffected.
String is a ValueConverter that converts its input to a string.
If the value is already a string or []byte, it's unchanged.
If the value is of another type, conversion to string is done
with fmt.Sprintf("%v", v).
The pages are generated with Goldsv0.6.7. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.
