Пакет 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 также позволяет запросам принимать параметры опций для каждого запроса, возвращая ErrRemoveArgument из CheckNamedValue.
Если поддерживается несколько наборов результатов, 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, float — в float64, bool, string и []byte — в себя. Если аргумент — пустой указатель, defaultConverter.ConvertValue возвращает пустой 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") ErrRemoveArgument может возвращаться из NamedValueChecker, чтобы указать пакету 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.
тип 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
} тип 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)
} тип 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)
} тип 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)
} тип Connector 1.10
Connector представляет драйвер в фиксированной конфигурации и может создавать любое количество эквивалентных Conn для использования несколькими горутинами.
Connector может быть передан в database/sql.OpenDB, чтобы позволить драйверам реализовывать собственные конструкторы database/sql.DB, или возвращаться методом DriverContext's OpenConnector, чтобы разрешить драйверам доступ к контексту и избежать многократного парсинга конфигурации драйвера.
Если 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
} тип 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)
} тип 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)
} тип Execer
Execer — это необязательный интерфейс, который может быть реализован Conn.
Если Conn не реализует ни ExecerContext, ни Execer, то database/sql.DB.Exec сначала подготовит запрос, выполнит оператор и затем закроет оператор.
Exec может вернуть ErrSkip.
Устаревшее: Драйверы должны реализовывать ExecerContext вместо этого.
type Execer interface {
Exec(query string, args []Value) (Result, error)
} тип 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)
} тип IsolationLevel 1.8
IsolationLevel — это уровень изоляции транзакции, хранящийся в TxOptions.
Этот тип должен рассматриваться как идентичный database/sql.IsolationLevel вместе со всеми значениями, определёнными на нём.
type IsolationLevel int
тип 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
}
тип 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
} тип NotNull
NotNull — это тип, реализующий ValueConverter, запрещающий нулевые значения, но иначе делегирующий другому ValueConverter.
type NotNull struct {
Converter ValueConverter
}
функция (NotNull) ConvertValue
func (n NotNull) ConvertValue(v any) (Value, error)
тип Null
Null — это тип, реализующий ValueConverter, позволяющий нулевые значения, но иначе делегирующий другому ValueConverter.
type Null struct {
Converter ValueConverter
}
функция (Null) ConvertValue
func (n Null) ConvertValue(v any) (Value, error)
тип 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
} тип 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)
} тип 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)
} тип 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)
} тип 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
} тип RowsAffected
RowsAffected реализует Result для операции INSERT или UPDATE, которая изменяет количество строк.
type RowsAffected int64
функция (RowsAffected) LastInsertId
func (RowsAffected) LastInsertId() (int64, error)
функция (RowsAffected) RowsAffected
func (v RowsAffected) RowsAffected() (int64, error)
тип 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
} тип RowsColumnTypeLength 1.8
RowsColumnTypeLength может быть реализован Rows. Он должен вернуть длину типа столбца, если столбец является типом переменной длины. Если столбец не является типом переменной длины, ok должно возвращать false. Если длина не ограничена, кроме системных ограничений, должно возвращаться 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)
} тип RowsColumnTypeNullable 1.8
RowsColumnTypeNullable может быть реализован Rows. Значение nullable должно быть true, если известно, что столбец может быть null, или false, если столбец не может быть null. Если неизвестно, nullable столбца, ok должно быть false.
type RowsColumnTypeNullable interface {
Rows
ColumnTypeNullable(index int) (nullable, ok bool)
} тип RowsColumnTypePrecisionScale 1.8
RowsColumnTypePrecisionScale может быть реализован Rows. Он должен вернуть точность и масштаб для десятичных типов. Если не применимо, ok должно быть false. Ниже приведены примеры возвращаемых значений для различных типов:
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)
} тип RowsColumnTypeScanType 1.8
RowsColumnTypeScanType может быть реализован Rows. Он должен вернуть тип значения, который может быть использован для сканирования типов. Например, для типа базы данных "bigint" это должно вернуть "reflect.TypeOf(int64(0))".
type RowsColumnTypeScanType interface {
Rows
ColumnTypeScanType(index int) reflect.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
} тип SessionResetter 1.10
SessionResetter может быть реализован Conn, чтобы позволить драйверам сбросить состояние сеанса, связанное с подключением, и сигнализировать о плохом подключении.
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
} тип 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)
} тип 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)
} тип 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)
} тип Tx
Tx — транзакция.
type Tx interface {
Commit() error
Rollback() error
} тип TxOptions 1.8
TxOptions хранит параметры транзакции.
Этот тип должен рассматриваться как идентичный database/sql.TxOptions.
type TxOptions struct {
Isolation IsolationLevel
ReadOnly bool
}
тип Validator 1.15
Validator может быть реализован Conn, чтобы позволить драйверам сигнализировать, является ли подключение валидным или его следует отбросить.
Если реализовано, драйверы могут вернуть основную ошибку из запросов, даже если подключение должно быть отброшено пулом подключений.
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
} тип Value
Value — значение, которое драйверы должны уметь обрабатывать. Это либо null, тип, обрабатываемый интерфейсом NamedValueChecker драйвера базы данных, или экземпляр одного из этих типов:
int64 float64 bool []byte string time.Time
Если драйвер поддерживает курсоры, возвращаемое Value также может реализовывать интерфейс Rows в этом пакете. Это используется, например, когда пользователь выбирает курсор, такой как "select cursor(select * from my_table) from dual". Если Rows из select закрывается, курсор Rows также будет закрыт.
type Value any
тип ValueConverter
ValueConverter — это интерфейс, предоставляющий метод ConvertValue.
Различные реализации ValueConverter предоставляются пакетом драйверов для обеспечения согласованных реализаций преобразований между драйверами. ValueConverters используются для нескольких целей:
преобразования из типов Value, предоставляемых пакетом sql, в конкретный тип столбца таблицы базы данных и обеспечение соответствия, например, чтобы определенный int64 соответствовал столбцу uint16 в таблице.
преобразования значения, полученного из базы данных, в один из типов драйвера Value.
пакетом database/sql для преобразования типа Value драйвера в тип пользователя при сканировании.
type ValueConverter interface {
// ConvertValue converts a value to a driver Value.
ConvertValue(v any) (Value, error)
} тип 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/
