Пакет driver
Обзор
Пакет driver определяет интерфейсы, которые должны реализовывать драйверы баз данных, используемые пакетом sql.
В большинстве случаев следует использовать пакет database/sql.
Интерфейс драйвера со временем менялся. Драйверы должны реализовывать интерфейсы Connector и DriverContext. Методы Connector.Connect и Driver.Open не должны возвращать ErrBadConn. ErrBadConn следует возвращать только из Validator, SessionResetter или метода запроса, если соединение уже находится в недопустимом состоянии (например, закрыто).
Все реализации Conn должны реализовывать следующие интерфейсы: Pinger, SessionResetter и Validator.
Если поддерживаются именованные параметры или контекст, Conn драйвера должен реализовывать интерфейсы ExecerContext, QueryerContext, ConnPrepareContext и ConnBeginTx.
Для поддержки пользовательских типов данных реализуйте NamedValueChecker. NamedValueChecker также позволяет передавать в запрос параметры, относящиеся к конкретному запросу: для этого CheckNamedValue должен возвращать ErrRemoveArgument.
Если поддерживается несколько наборов результатов, Rows должен реализовывать RowsNextResultSet. Если драйвер умеет описывать типы в возвращаемом результате, он должен реализовывать следующие интерфейсы: RowsColumnTypeScanType, RowsColumnTypeDatabaseTypeName, RowsColumnTypeLength, RowsColumnTypeNullable и RowsColumnTypePrecisionScale. Значение строки также может возвращать тип Rows, представляющий значение курсора базы данных.
Если Conn реализует Validator, перед возвращением соединения в пул соединений вызывается метод IsValid. Если запись в пуле соединений реализует SessionResetter, перед повторным использованием соединения для другого запроса вызывается ResetSession. Если соединение не возвращается в пул соединений, а используется повторно сразу же, перед повторным использованием вызывается ResetSession, но IsValid не вызывается.
Указатель
Файлы пакета
driver.go types.go
Переменные
Bool — это ValueConverter, преобразующий входные значения в bool.
Правила преобразования:
- логические значения возвращаются без изменений
- для целочисленных типов 1 означает true, 0 — false; другие целые числа приводят к ошибке
- для строк и []byte действуют те же правила, что и для strconv.ParseBool
- все остальные типы приводят к ошибке
var Bool boolType
DefaultParameterConverter — реализация ValueConverter по умолчанию, используемая, если Stmt не реализует ColumnConverter.
DefaultParameterConverter возвращает аргумент непосредственно, если IsValue(arg). В противном случае, если аргумент реализует Valuer, для получения Value используется его метод Value. В качестве запасного варианта базовый тип переданного аргумента преобразуется в Value: целочисленные базовые типы преобразуются в int64, числа с плавающей точкой — в float64, а bool, string и []byte остаются без изменений. Если аргумент — nil-указатель, defaultConverter.ConvertValue возвращает nil Value. Если аргумент — ненулевой указатель, он разыменовывается, и defaultConverter.ConvertValue вызывается рекурсивно. Для остальных типов возникает ошибка.
var DefaultParameterConverter defaultConverter
Драйвер должен возвращать ErrBadConn, чтобы сообщить пакету database/sql, что driver.Conn находится в недопустимом состоянии (например, сервер ранее закрыл соединение) и пакету database/sql следует повторить операцию на новом соединении.
Чтобы предотвратить дублирование операций, НЕ следует возвращать ErrBadConn, если есть вероятность, что сервер базы данных выполнил операцию. Даже если сервер вернул ошибку, не следует возвращать ErrBadConn.
Ошибки проверяются с помощью errors.Is. Ошибка может оборачивать ErrBadConn или реализовывать метод Is(error) bool.
var ErrBadConn = errors.New("driver: bad connection") NamedValueChecker может возвращать ErrRemoveArgument, чтобы указать пакету database/sql не передавать аргумент интерфейсу запроса драйвера. Возвращайте это значение при обработке параметров или структур, относящихся к конкретному запросу и не являющихся аргументами SQL-запроса.
var ErrRemoveArgument = errors.New("driver: remove argument from query") Некоторые методы необязательных интерфейсов могут возвращать ErrSkip, чтобы во время выполнения указать, что быстрый путь недоступен и пакету sql следует продолжить работу так, как если бы необязательный интерфейс не был реализован. ErrSkip поддерживается только там, где это явно указано в документации.
var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented") Int32 — это ValueConverter, преобразующий входные значения в int64 с учетом ограничений значения int32.
var Int32 int32Type
ResultNoRows — это предопределенный Result, который драйверы должны возвращать при успешном выполнении команды DDL (например, CREATE TABLE). Для LastInsertId и RowsAffected он возвращает ошибку.
var ResultNoRows noRows
String — это ValueConverter, преобразующий входное значение в строку. Если значение уже является строкой или []byte, оно остается без изменений. Если значение имеет другой тип, преобразование в строку выполняется с помощью fmt.Sprintf("%v", v).
var String stringType
func IsScanValue
func IsScanValue(v any) bool
IsScanValue эквивалентна IsValue. Она существует для совместимости.
func IsValue
func IsValue(v any) bool
IsValue сообщает, является ли v допустимым типом параметра Value.
type ColumnConverter
ColumnConverter может быть реализован в качестве дополнительного интерфейса типом Stmt, если оператор знает типы собственных столбцов и может преобразовать любой тип в Value драйвера.
Устарел: драйверам следует реализовывать NamedValueChecker.
type ColumnConverter interface {
// 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, [DefaultParameterConverter]
// can be returned.
ColumnConverter(idx int) ValueConverter
} type Conn
Conn — это соединение с базой данных. Оно не используется одновременно несколькими горутинами.
Предполагается, что Conn хранит состояние.
type Conn interface {
// Prepare returns a prepared statement, bound to this connection.
Prepare(query string) (Stmt, error)
// 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).
Close() error
// Begin starts and returns a new transaction.
//
// Deprecated: Drivers should implement ConnBeginTx instead (or additionally).
Begin() (Tx, error)
} type ConnBeginTx 1.8
ConnBeginTx расширяет интерфейс Conn, добавляя контекст и TxOptions.
type ConnBeginTx interface {
// 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.
BeginTx(ctx context.Context, opts TxOptions) (Tx, error)
} type ConnPrepareContext 1.8
ConnPrepareContext расширяет интерфейс Conn, добавляя контекст.
type ConnPrepareContext interface {
// 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.
PrepareContext(ctx context.Context, query string) (Stmt, error)
} type Connector 1.10
Connector представляет драйвер с фиксированной конфигурацией и может создавать любое количество эквивалентных Conn для использования несколькими горутинами.
Connector можно передать в database/sql.OpenDB, чтобы драйверы могли реализовать собственные конструкторы database/sql.DB, либо вернуть из метода OpenConnector интерфейса DriverContext, чтобы драйверы могли получать доступ к контексту и не разбирать конфигурацию драйвера повторно.
Если Connector реализует io.Closer, метод database/sql.DB.Close вызовет метод Close и вернет ошибку (если она возникнет).
type Connector interface {
// 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.
Connect(context.Context) (Conn, error)
// Driver returns the underlying Driver of the Connector,
// mainly to maintain compatibility with the Driver method
// on sql.DB.
Driver() Driver
} type Driver
Driver — это интерфейс, который должен реализовывать драйвер базы данных.
Драйверы баз данных могут реализовать DriverContext для доступа к контекстам и однократного разбора имени для пула соединений вместо разбора имени для каждого соединения.
type Driver interface {
// 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.
Open(name string) (Conn, error)
} type DriverContext 1.10
Если Driver реализует DriverContext, то database/sql.DB вызовет OpenConnector, чтобы получить Connector, а затем вызовет метод Connect этого Connector, чтобы получить каждое необходимое соединение, вместо того чтобы вызывать метод Open интерфейса Driver для каждого соединения. Такая последовательность из двух шагов позволяет драйверам разобрать имя только один раз, а также предоставляет доступ к контекстам отдельных Conn.
type DriverContext interface {
// OpenConnector must parse the name in the same format that Driver.Open
// parses the name parameter.
OpenConnector(name string) (Connector, error)
} type Execer
Execer — это необязательный интерфейс, который может реализовать Conn.
Если Conn не реализует ни ExecerContext, ни Execer, database/sql.DB.Exec сначала подготовит запрос, выполнит оператор, а затем закроет его.
Exec может возвращать ErrSkip.
Устарел: драйверам следует реализовывать ExecerContext.
type Execer interface {
Exec(query string, args []Value) (Result, error)
} type ExecerContext 1.8
ExecerContext — это необязательный интерфейс, который может реализовать Conn.
Если Conn не реализует ExecerContext, database/sql.DB.Exec использует Execer; если Conn также не реализует Execer, database/sql.DB.Exec сначала подготовит запрос, выполнит оператор, а затем закроет его.
ExecContext может возвращать ErrSkip.
ExecContext должен учитывать тайм-аут контекста и возвращать управление при отмене контекста.
type ExecerContext interface {
ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
} type IsolationLevel 1.8
IsolationLevel — это уровень изоляции транзакции, хранящийся в TxOptions.
Этот тип следует считать идентичным database/sql.IsolationLevel, включая определенные для него значения.
type IsolationLevel int
type NamedValue 1.8
NamedValue содержит и имя значения, и само значение.
type NamedValue struct {
// If the Name is not empty it should be used for the parameter identifier and
// not the ordinal position.
//
// Name will not have a symbol prefix.
Name string
// Ordinal position of the parameter starting from one and is always set.
Ordinal int
// Value is the parameter value.
Value Value
}
type NamedValueChecker 1.9
NamedValueChecker может быть реализован в качестве дополнительного интерфейса типом Conn или Stmt. Он предоставляет драйверу больше возможностей для обработки типов Go и типов базы данных, выходящих за рамки допустимых типов Value по умолчанию.
Пакет database/sql проверяет наличие проверяющих значений в следующем порядке и останавливается при первом совпадении: Stmt.NamedValueChecker, Conn.NamedValueChecker, Stmt.ColumnConverter, DefaultParameterConverter.
Если CheckNamedValue возвращает ErrRemoveArgument, NamedValue не будет включен в итоговые аргументы запроса. Это можно использовать для передачи специальных параметров непосредственно запросу.
Если возвращен ErrSkip, для аргумента используется путь проверки ошибок преобразователя столбцов. Драйверы могут возвращать ErrSkip, когда исчерпаны все их собственные особые случаи.
type NamedValueChecker interface {
// 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.
CheckNamedValue(*NamedValue) error
} type NotNull
NotNull — это тип, реализующий ValueConverter: он запрещает nil-значения, а в остальном делегирует преобразование другому ValueConverter.
type NotNull struct {
Converter ValueConverter
}
func (NotNull) ConvertValue
func (n NotNull) ConvertValue(v any) (Value, error)
type Null
Null — это тип, реализующий ValueConverter: он допускает nil-значения, а в остальном делегирует преобразование другому ValueConverter.
type Null struct {
Converter ValueConverter
}
func (Null) ConvertValue
func (n Null) ConvertValue(v any) (Value, error)
type Pinger 1.8
Pinger — это необязательный интерфейс, который может реализовать Conn.
Если Conn не реализует Pinger, методы database/sql.DB.Ping и database/sql.DB.PingContext проверят, доступно ли хотя бы одно соединение Conn.
Если Conn.Ping возвращает ErrBadConn, методы database/sql.DB.Ping и database/sql.DB.PingContext удалят Conn из пула.
type Pinger interface {
Ping(ctx context.Context) error
} type Queryer 1.1
Queryer — это необязательный интерфейс, который может реализовать Conn.
Если Conn не реализует ни QueryerContext, ни Queryer, database/sql.DB.Query сначала подготовит запрос, выполнит оператор, а затем закроет его.
Query может возвращать ErrSkip.
Устарел: драйверам следует реализовывать QueryerContext.
type Queryer interface {
Query(query string, args []Value) (Rows, error)
} type QueryerContext 1.8
QueryerContext — это необязательный интерфейс, который может реализовать Conn.
Если Conn не реализует QueryerContext, database/sql.DB.Query использует Queryer; если Conn также не реализует Queryer, database/sql.DB.Query сначала подготовит запрос, выполнит оператор, а затем закроет его.
QueryContext может возвращать ErrSkip.
QueryContext должен учитывать тайм-аут контекста и возвращать управление при отмене контекста.
type QueryerContext interface {
QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
} type Result
Result — это результат выполнения запроса.
type Result interface {
// LastInsertId returns the database's auto-generated ID
// after, for example, an INSERT into a table with primary
// key.
LastInsertId() (int64, error)
// RowsAffected returns the number of rows affected by the
// query.
RowsAffected() (int64, error)
} type Rows
Rows — это итератор по результатам выполненного запроса.
type Rows interface {
// 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.
Columns() []string
// Close closes the rows iterator.
Close() error
// 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.
Next(dest []Value) error
} type RowsAffected
RowsAffected реализует Result для операции INSERT или UPDATE, изменяющей некоторое количество строк.
type RowsAffected int64
func (RowsAffected) LastInsertId
func (RowsAffected) LastInsertId() (int64, error)
func (RowsAffected) RowsAffected
func (v RowsAffected) RowsAffected() (int64, error)
type RowsColumnScanner 1.27
RowsColumnScanner расширяет интерфейс Rows, позволяя драйверу сканировать данные непосредственно в предоставленное пользователем целевое значение.
RowsColumnScanner заменяет метод Rows.Next.
Начиная с Go 1.27, database/sql не вызывает Next, если Rows реализует RowsColumnScanner. Реализации Rows могут по-прежнему реализовывать метод Next для поддержки более старых версий Go.
type RowsColumnScanner interface {
Rows
// NextRow advances to the next row of data.
// It should return io.EOF when there are no more rows.
NextRow() error
// ScanColumn copies the column at the given index in the current row
// into the value pointed to by dest.
//
// The driver may assign a driver.Value to dest using [database/sql.ConvertAssign].
ScanColumn(scanCtx ScanContext, index int, dest any) error
} type RowsColumnTypeDatabaseTypeName 1.8
RowsColumnTypeDatabaseTypeName может быть реализован типом Rows. Он должен возвращать имя типа в системе базы данных без указания длины. Имена типов должны быть в верхнем регистре. Примеры возвращаемых типов: "VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT", "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML", "TIMESTAMP".
type RowsColumnTypeDatabaseTypeName interface {
Rows
ColumnTypeDatabaseTypeName(index int) string
} type RowsColumnTypeLength 1.8
RowsColumnTypeLength может быть реализован типом Rows. Если тип столбца имеет переменную длину, он должен возвращать длину этого типа. Если тип столбца не имеет переменной длины, следует возвращать false для ok. Если длина ограничена только системными пределами, следует возвращать math.MaxInt64. Ниже приведены примеры возвращаемых значений для различных типов:
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)
} type RowsColumnTypeNullable 1.8
RowsColumnTypeNullable может быть реализован типом Rows. Значение nullable должно быть true, если известно, что столбец может содержать null, или false, если известно, что столбец не допускает null. Если допустимость null для столбца неизвестна, следует возвращать false для ok.
type RowsColumnTypeNullable interface {
Rows
ColumnTypeNullable(index int) (nullable, ok bool)
} type RowsColumnTypePrecisionScale 1.8
RowsColumnTypePrecisionScale может быть реализован типом Rows. Для десятичных типов он должен возвращать точность и масштаб. Если это неприменимо, следует возвращать false для ok. Ниже приведены примеры возвращаемых значений для различных типов:
decimal(38, 4) (38, 4, true) int (0, 0, false) decimal (math.MaxInt64, math.MaxInt64, true)
type RowsColumnTypePrecisionScale interface {
Rows
ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)
} type RowsColumnTypeScanType 1.8
RowsColumnTypeScanType может быть реализован типом Rows. Он должен возвращать тип значения, в который можно сканировать данные. Например, для типа столбца базы данных "bigint" следует вернуть "reflect.TypeOf(int64(0))".
type RowsColumnTypeScanType interface {
Rows
ColumnTypeScanType(index int) reflect.Type
} type RowsNextResultSet 1.8
RowsNextResultSet расширяет интерфейс Rows, позволяя указать драйверу перейти к следующему набору результатов.
type RowsNextResultSet interface {
Rows
// HasNextResultSet is called at the end of the current result set and
// reports whether there is another result set after the current one.
HasNextResultSet() bool
// 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.
NextResultSet() error
} type ScanContext 1.27
ScanContext передает состояние текущего запроса через функцию RowsColumnScanner.ScanColumn в database/sql.ConvertAssign.
type ScanContext internal.ScanContext
type SessionResetter 1.10
Conn может реализовать SessionResetter, чтобы позволить драйверам сбрасывать состояние сеанса, связанное с соединением, и сообщать о недопустимом соединении.
type SessionResetter interface {
// 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.
ResetSession(ctx context.Context) error
} type Stmt
Stmt — это подготовленный оператор. Он привязан к Conn и не используется одновременно несколькими горутинами.
type Stmt interface {
// 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).
Close() error
// 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.
NumInput() int
// Exec executes a query that doesn't return rows, such
// as an INSERT or UPDATE.
//
// Deprecated: Drivers should implement StmtExecContext instead (or additionally).
Exec(args []Value) (Result, error)
// Query executes a query that may return rows, such as a
// SELECT.
//
// Deprecated: Drivers should implement StmtQueryContext instead (or additionally).
Query(args []Value) (Rows, error)
} type StmtExecContext 1.8
StmtExecContext расширяет интерфейс Stmt, добавляя контекст в Exec.
type StmtExecContext interface {
// 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.
ExecContext(ctx context.Context, args []NamedValue) (Result, error)
} type StmtQueryContext 1.8
StmtQueryContext расширяет интерфейс Stmt, добавляя контекст в Query.
type StmtQueryContext interface {
// QueryContext executes a query that may return rows, such as a
// SELECT.
//
// QueryContext must honor the context timeout and return when it is canceled.
QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
} type Tx
Tx — это транзакция.
type Tx interface {
Commit() error
Rollback() error
} type TxOptions 1.8
TxOptions содержит параметры транзакции.
Этот тип следует считать идентичным database/sql.TxOptions.
type TxOptions struct {
Isolation IsolationLevel
ReadOnly bool
}
type Validator 1.15
Conn может реализовать Validator, чтобы позволить драйверам сообщать, действительно ли соединение или его следует отбросить.
При реализации этого интерфейса драйверы могут возвращать исходную ошибку из запросов, даже если пул соединений должен отбросить соединение.
type Validator interface {
// IsValid is called prior to placing the connection into the
// connection pool. The connection will be discarded if false is returned.
IsValid() bool
} type Value
Value — это значение, которое драйверы должны уметь обрабатывать. Это либо nil, либо тип, обрабатываемый интерфейсом NamedValueChecker драйвера базы данных, либо экземпляр одного из следующих типов:
int64 float64 bool []byte string time.Time
Если драйвер поддерживает курсоры, возвращаемое значение Value также может реализовывать интерфейс Rows из этого пакета. Например, это используется, когда пользователь выбирает курсор, такой как "select cursor(select * from my_table) from dual". Если Rows, полученный в результате выбора, закрывается, курсор Rows также будет закрыт.
type Value any
type ValueConverter
ValueConverter — это интерфейс, предоставляющий метод ConvertValue.
Пакет driver предоставляет различные реализации ValueConverter, обеспечивающие единообразное преобразование значений между драйверами. ValueConverter используются для нескольких целей:
преобразование типов Value, предоставляемых пакетом sql, в конкретный тип столбца таблицы базы данных с проверкой соответствия ограничениям, например чтобы убедиться, что конкретное значение int64 помещается в столбец uint16 таблицы.
преобразование значения, полученного из базы данных, в один из типов Value драйвера.
использование пакетом database/sql для преобразования типа Value драйвера в пользовательский тип при сканировании.
type ValueConverter interface {
// ConvertValue converts a value to a driver Value.
ConvertValue(v any) (Value, error)
} type Valuer
Valuer — это интерфейс, предоставляющий метод Value.
Ошибки, возвращаемые методом Value, оборачиваются пакетом database/sql. Это позволяет вызывающим сторонам точно обрабатывать ошибки с помощью errors.Is после таких операций, как database/sql.Query, database/sql.Exec или database/sql.QueryRow.
Типы, реализующие интерфейс Valuer, могут преобразовывать себя в Value драйвера.
type Valuer interface {
// Value returns a driver Value.
// Value must not panic.
Value() (Value, error)
}
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/database/sql/driver/
