path: root/devdocs/go/database%2Fsql%2Fdriver%2Findex.html

<h1> Package driver  </h1>     <ul id="short-nav">
<li><code>import "database/sql/driver"</code></li>
<li><a href="#pkg-overview" class="overviewLink">Overview</a></li>
<li><a href="#pkg-index" class="indexLink">Index</a></li>
</ul>     <h2 id="pkg-overview">Overview </h2> <p>Package driver defines interfaces to be implemented by database drivers as used by package sql. </p>
<p>Most code should use the <span>database/sql</span> package. </p>
<p>The driver interface has evolved over time. Drivers should implement <a href="#Connector">Connector</a> and <a href="#DriverContext">DriverContext</a> interfaces. The Connector.Connect and Driver.Open methods should never return <a href="#ErrBadConn">ErrBadConn</a>. <a href="#ErrBadConn">ErrBadConn</a> should only be returned from <a href="#Validator">Validator</a>, <a href="#SessionResetter">SessionResetter</a>, or a query method if the connection is already in an invalid (e.g. closed) state. </p>
<p>All <a href="#Conn">Conn</a> implementations should implement the following interfaces: <a href="#Pinger">Pinger</a>, <a href="#SessionResetter">SessionResetter</a>, and <a href="#Validator">Validator</a>. </p>
<p>If named parameters or context are supported, the driver's <a href="#Conn">Conn</a> should implement: <a href="#ExecerContext">ExecerContext</a>, <a href="#QueryerContext">QueryerContext</a>, <a href="#ConnPrepareContext">ConnPrepareContext</a>, and <a href="#ConnBeginTx">ConnBeginTx</a>. </p>
<p>To support custom data types, implement <a href="#NamedValueChecker">NamedValueChecker</a>. <a href="#NamedValueChecker">NamedValueChecker</a> also allows queries to accept per-query options as a parameter by returning <a href="#ErrRemoveArgument">ErrRemoveArgument</a> from CheckNamedValue. </p>
<p>If multiple result sets are supported, <a href="#Rows">Rows</a> should implement <a href="#RowsNextResultSet">RowsNextResultSet</a>. If the driver knows how to describe the types present in the returned result it should implement the following interfaces: <a href="#RowsColumnTypeScanType">RowsColumnTypeScanType</a>, <a href="#RowsColumnTypeDatabaseTypeName">RowsColumnTypeDatabaseTypeName</a>, <a href="#RowsColumnTypeLength">RowsColumnTypeLength</a>, <a href="#RowsColumnTypeNullable">RowsColumnTypeNullable</a>, and <a href="#RowsColumnTypePrecisionScale">RowsColumnTypePrecisionScale</a>. A given row value may also return a <a href="#Rows">Rows</a> type, which may represent a database cursor value. </p>
<p>If a <a href="#Conn">Conn</a> implements <a href="#Validator">Validator</a>, then the IsValid method is called before returning the connection to the connection pool. If an entry in the connection pool implements <a href="#SessionResetter">SessionResetter</a>, then ResetSession is called before reusing the connection for another query. If a connection is never returned to the connection pool but is immediately reused, then ResetSession is called prior to reuse but IsValid is not called. </p>     <h2 id="pkg-index">Index </h2>  <ul id="manual-nav">
<li><a href="#pkg-variables">Variables</a></li>
<li><a href="#IsScanValue">func IsScanValue(v any) bool</a></li>
<li><a href="#IsValue">func IsValue(v any) bool</a></li>
<li><a href="#ColumnConverter">type ColumnConverter</a></li>
<li><a href="#Conn">type Conn</a></li>
<li><a href="#ConnBeginTx">type ConnBeginTx</a></li>
<li><a href="#ConnPrepareContext">type ConnPrepareContext</a></li>
<li><a href="#Connector">type Connector</a></li>
<li><a href="#Driver">type Driver</a></li>
<li><a href="#DriverContext">type DriverContext</a></li>
<li><a href="#Execer">type Execer</a></li>
<li><a href="#ExecerContext">type ExecerContext</a></li>
<li><a href="#IsolationLevel">type IsolationLevel</a></li>
<li><a href="#NamedValue">type NamedValue</a></li>
<li><a href="#NamedValueChecker">type NamedValueChecker</a></li>
<li><a href="#NotNull">type NotNull</a></li>
<li> <a href="#NotNull.ConvertValue">func (n NotNull) ConvertValue(v any) (Value, error)</a>
</li>
<li><a href="#Null">type Null</a></li>
<li> <a href="#Null.ConvertValue">func (n Null) ConvertValue(v any) (Value, error)</a>
</li>
<li><a href="#Pinger">type Pinger</a></li>
<li><a href="#Queryer">type Queryer</a></li>
<li><a href="#QueryerContext">type QueryerContext</a></li>
<li><a href="#Result">type Result</a></li>
<li><a href="#Rows">type Rows</a></li>
<li><a href="#RowsAffected">type RowsAffected</a></li>
<li> <a href="#RowsAffected.LastInsertId">func (RowsAffected) LastInsertId() (int64, error)</a>
</li>
<li> <a href="#RowsAffected.RowsAffected">func (v RowsAffected) RowsAffected() (int64, error)</a>
</li>
<li><a href="#RowsColumnTypeDatabaseTypeName">type RowsColumnTypeDatabaseTypeName</a></li>
<li><a href="#RowsColumnTypeLength">type RowsColumnTypeLength</a></li>
<li><a href="#RowsColumnTypeNullable">type RowsColumnTypeNullable</a></li>
<li><a href="#RowsColumnTypePrecisionScale">type RowsColumnTypePrecisionScale</a></li>
<li><a href="#RowsColumnTypeScanType">type RowsColumnTypeScanType</a></li>
<li><a href="#RowsNextResultSet">type RowsNextResultSet</a></li>
<li><a href="#SessionResetter">type SessionResetter</a></li>
<li><a href="#Stmt">type Stmt</a></li>
<li><a href="#StmtExecContext">type StmtExecContext</a></li>
<li><a href="#StmtQueryContext">type StmtQueryContext</a></li>
<li><a href="#Tx">type Tx</a></li>
<li><a href="#TxOptions">type TxOptions</a></li>
<li><a href="#Validator">type Validator</a></li>
<li><a href="#Value">type Value</a></li>
<li><a href="#ValueConverter">type ValueConverter</a></li>
<li><a href="#Valuer">type Valuer</a></li>
</ul> <h3>Package files</h3> <p>  <span>driver.go</span> <span>types.go</span>  </p>   <h2 id="pkg-variables">Variables</h2> <p>Bool is a <a href="#ValueConverter">ValueConverter</a> that converts input values to bool. </p>
<p>The conversion rules are: </p>
<ul> <li>booleans are returned unchanged </li>
<li>for integer types, 1 is true 0 is false, other integers are an error </li>
<li>for strings and []byte, same rules as <span>strconv.ParseBool</span> </li>
<li>all other types are an error </li>
</ul> <pre data-language="go">var Bool boolType</pre> <p>DefaultParameterConverter is the default implementation of <a href="#ValueConverter">ValueConverter</a> that's used when a <a href="#Stmt">Stmt</a> doesn't implement <a href="#ColumnConverter">ColumnConverter</a>. </p>
<p>DefaultParameterConverter returns its argument directly if IsValue(arg). Otherwise, if the argument implements <a href="#Valuer">Valuer</a>, its Value method is used to return a <a href="#Value">Value</a>. As a fallback, the provided argument's underlying type is used to convert it to a <a href="#Value">Value</a>: underlying integer types are converted to int64, floats to float64, bool, string, and []byte to themselves. If the argument is a nil pointer, defaultConverter.ConvertValue returns a nil <a href="#Value">Value</a>. If the argument is a non-nil pointer, it is dereferenced and defaultConverter.ConvertValue is called recursively. Other types are an error. </p>
<pre data-language="go">var DefaultParameterConverter defaultConverter</pre> <p>ErrBadConn should be returned by a driver to signal to the <span>database/sql</span> package that a driver.<a href="#Conn">Conn</a> is in a bad state (such as the server having earlier closed the connection) and the <span>database/sql</span> package should retry on a new connection. </p>
<p>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. </p>
<p>Errors will be checked using <span>errors.Is</span>. An error may wrap ErrBadConn or implement the Is(error) bool method. </p>
<pre data-language="go">var ErrBadConn = errors.New("driver: bad connection")</pre> <p>ErrRemoveArgument may be returned from <a href="#NamedValueChecker">NamedValueChecker</a> to instruct the <span>database/sql</span> 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. </p>
<pre data-language="go">var ErrRemoveArgument = errors.New("driver: remove argument from query")</pre> <p>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. </p>
<pre data-language="go">var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")</pre> <p>Int32 is a <a href="#ValueConverter">ValueConverter</a> that converts input values to int64, respecting the limits of an int32 value. </p>
<pre data-language="go">var Int32 int32Type</pre> <p>ResultNoRows is a pre-defined <a href="#Result">Result</a> for drivers to return when a DDL command (such as a CREATE TABLE) succeeds. It returns an error for both LastInsertId and <a href="#RowsAffected">RowsAffected</a>. </p>
<pre data-language="go">var ResultNoRows noRows</pre> <p>String is a <a href="#ValueConverter">ValueConverter</a> 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). </p>
<pre data-language="go">var String stringType</pre> <h2 id="IsScanValue">func <span>IsScanValue</span>  </h2> <pre data-language="go">func IsScanValue(v any) bool</pre> <p>IsScanValue is equivalent to <a href="#IsValue">IsValue</a>. It exists for compatibility. </p>
<h2 id="IsValue">func <span>IsValue</span>  </h2> <pre data-language="go">func IsValue(v any) bool</pre> <p>IsValue reports whether v is a valid <a href="#Value">Value</a> parameter type. </p>
<h2 id="ColumnConverter">type <span>ColumnConverter</span>  </h2> <p>ColumnConverter may be optionally implemented by <a href="#Stmt">Stmt</a> if the statement is aware of its own columns' types and can convert from any type to a driver <a href="#Value">Value</a>. </p>
<p>Deprecated: Drivers should implement <a href="#NamedValueChecker">NamedValueChecker</a>. </p>
<pre data-language="go">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, DefaultValueConverter
    // can be returned.
    ColumnConverter(idx int) ValueConverter
}</pre> <h2 id="Conn">type <span>Conn</span>  </h2> <p>Conn is a connection to a database. It is not used concurrently by multiple goroutines. </p>
<p>Conn is assumed to be stateful. </p>
<pre data-language="go">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)
}</pre> <h2 id="ConnBeginTx">type <span>ConnBeginTx</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>ConnBeginTx enhances the <a href="#Conn">Conn</a> interface with context and <a href="#TxOptions">TxOptions</a>. </p>
<pre data-language="go">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)
}</pre> <h2 id="ConnPrepareContext">type <span>ConnPrepareContext</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>ConnPrepareContext enhances the <a href="#Conn">Conn</a> interface with context. </p>
<pre data-language="go">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)
}</pre> <h2 id="Connector">type <span>Connector</span>  <span title="Added in Go 1.10">1.10</span> </h2> <p>A Connector represents a driver in a fixed configuration and can create any number of equivalent Conns for use by multiple goroutines. </p>
<p>A Connector can be passed to <span>database/sql.OpenDB</span>, to allow drivers to implement their own <span>database/sql.DB</span> constructors, or returned by <a href="#DriverContext">DriverContext</a>'s OpenConnector method, to allow drivers access to context and to avoid repeated parsing of driver configuration. </p>
<p>If a Connector implements <span>io.Closer</span>, the <span>database/sql.DB.Close</span> method will call the Close method and return error (if any). </p>
<pre data-language="go">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
}</pre> <h2 id="Driver">type <span>Driver</span>  </h2> <p>Driver is the interface that must be implemented by a database driver. </p>
<p>Database drivers may implement <a href="#DriverContext">DriverContext</a> for access to contexts and to parse the name only once for a pool of connections, instead of once per connection. </p>
<pre data-language="go">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)
}</pre> <h2 id="DriverContext">type <span>DriverContext</span>  <span title="Added in Go 1.10">1.10</span> </h2> <p>If a <a href="#Driver">Driver</a> implements DriverContext, then <span>database/sql.DB</span> will call OpenConnector to obtain a <a href="#Connector">Connector</a> and then invoke that <a href="#Connector">Connector</a>'s Connect method to obtain each needed connection, instead of invoking the <a href="#Driver">Driver</a>'s Open method for each connection. The two-step sequence allows drivers to parse the name just once and also provides access to per-<a href="#Conn">Conn</a> contexts. </p>
<pre data-language="go">type DriverContext interface {
    // OpenConnector must parse the name in the same format that Driver.Open
    // parses the name parameter.
    OpenConnector(name string) (Connector, error)
}</pre> <h2 id="Execer">type <span>Execer</span>  </h2> <p>Execer is an optional interface that may be implemented by a <a href="#Conn">Conn</a>. </p>
<p>If a <a href="#Conn">Conn</a> implements neither <a href="#ExecerContext">ExecerContext</a> nor <a href="#Execer">Execer</a>, the <span>database/sql.DB.Exec</span> will first prepare a query, execute the statement, and then close the statement. </p>
<p>Exec may return <a href="#ErrSkip">ErrSkip</a>. </p>
<p>Deprecated: Drivers should implement <a href="#ExecerContext">ExecerContext</a> instead. </p>
<pre data-language="go">type Execer interface {
    Exec(query string, args []Value) (Result, error)
}</pre> <h2 id="ExecerContext">type <span>ExecerContext</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>ExecerContext is an optional interface that may be implemented by a <a href="#Conn">Conn</a>. </p>
<p>If a <a href="#Conn">Conn</a> does not implement <a href="#ExecerContext">ExecerContext</a>, the <span>database/sql.DB.Exec</span> will fall back to <a href="#Execer">Execer</a>; if the Conn does not implement Execer either, <span>database/sql.DB.Exec</span> will first prepare a query, execute the statement, and then close the statement. </p>
<p>ExecContext may return <a href="#ErrSkip">ErrSkip</a>. </p>
<p>ExecContext must honor the context timeout and return when the context is canceled. </p>
<pre data-language="go">type ExecerContext interface {
    ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
}</pre> <h2 id="IsolationLevel">type <span>IsolationLevel</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>IsolationLevel is the transaction isolation level stored in <a href="#TxOptions">TxOptions</a>. </p>
<p>This type should be considered identical to <span>database/sql.IsolationLevel</span> along with any values defined on it. </p>
<pre data-language="go">type IsolationLevel int</pre> <h2 id="NamedValue">type <span>NamedValue</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>NamedValue holds both the value name and value. </p>
<pre data-language="go">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
}
</pre> <h2 id="NamedValueChecker">type <span>NamedValueChecker</span>  <span title="Added in Go 1.9">1.9</span> </h2> <p>NamedValueChecker may be optionally implemented by <a href="#Conn">Conn</a> or <a href="#Stmt">Stmt</a>. It provides the driver more control to handle Go and database types beyond the default <a href="#Value">Value</a> types allowed. </p>
<p>The <span>database/sql</span> package checks for value checkers in the following order, stopping at the first found match: Stmt.NamedValueChecker, Conn.NamedValueChecker, Stmt.ColumnConverter, <a href="#DefaultParameterConverter">DefaultParameterConverter</a>. </p>
<p>If CheckNamedValue returns <a href="#ErrRemoveArgument">ErrRemoveArgument</a>, the <a href="#NamedValue">NamedValue</a> will not be included in the final query arguments. This may be used to pass special options to the query itself. </p>
<p>If <a href="#ErrSkip">ErrSkip</a> is returned the column converter error checking path is used for the argument. Drivers may wish to return <a href="#ErrSkip">ErrSkip</a> after they have exhausted their own special cases. </p>
<pre data-language="go">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
}</pre> <h2 id="NotNull">type <span>NotNull</span>  </h2> <p>NotNull is a type that implements <a href="#ValueConverter">ValueConverter</a> by disallowing nil values but otherwise delegating to another <a href="#ValueConverter">ValueConverter</a>. </p>
<pre data-language="go">type NotNull struct {
    Converter ValueConverter
}
</pre> <h3 id="NotNull.ConvertValue">func (NotNull) <span>ConvertValue</span>  </h3> <pre data-language="go">func (n NotNull) ConvertValue(v any) (Value, error)</pre> <h2 id="Null">type <span>Null</span>  </h2> <p>Null is a type that implements <a href="#ValueConverter">ValueConverter</a> by allowing nil values but otherwise delegating to another <a href="#ValueConverter">ValueConverter</a>. </p>
<pre data-language="go">type Null struct {
    Converter ValueConverter
}
</pre> <h3 id="Null.ConvertValue">func (Null) <span>ConvertValue</span>  </h3> <pre data-language="go">func (n Null) ConvertValue(v any) (Value, error)</pre> <h2 id="Pinger">type <span>Pinger</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>Pinger is an optional interface that may be implemented by a <a href="#Conn">Conn</a>. </p>
<p>If a <a href="#Conn">Conn</a> does not implement Pinger, the <span>database/sql.DB.Ping</span> and <span>database/sql.DB.PingContext</span> will check if there is at least one <a href="#Conn">Conn</a> available. </p>
<p>If Conn.Ping returns <a href="#ErrBadConn">ErrBadConn</a>, <span>database/sql.DB.Ping</span> and <span>database/sql.DB.PingContext</span> will remove the <a href="#Conn">Conn</a> from pool. </p>
<pre data-language="go">type Pinger interface {
    Ping(ctx context.Context) error
}</pre> <h2 id="Queryer">type <span>Queryer</span>  <span title="Added in Go 1.1">1.1</span> </h2> <p>Queryer is an optional interface that may be implemented by a <a href="#Conn">Conn</a>. </p>
<p>If a <a href="#Conn">Conn</a> implements neither <a href="#QueryerContext">QueryerContext</a> nor <a href="#Queryer">Queryer</a>, the <span>database/sql.DB.Query</span> will first prepare a query, execute the statement, and then close the statement. </p>
<p>Query may return <a href="#ErrSkip">ErrSkip</a>. </p>
<p>Deprecated: Drivers should implement <a href="#QueryerContext">QueryerContext</a> instead. </p>
<pre data-language="go">type Queryer interface {
    Query(query string, args []Value) (Rows, error)
}</pre> <h2 id="QueryerContext">type <span>QueryerContext</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>QueryerContext is an optional interface that may be implemented by a <a href="#Conn">Conn</a>. </p>
<p>If a <a href="#Conn">Conn</a> does not implement QueryerContext, the <span>database/sql.DB.Query</span> will fall back to <a href="#Queryer">Queryer</a>; if the <a href="#Conn">Conn</a> does not implement <a href="#Queryer">Queryer</a> either, <span>database/sql.DB.Query</span> will first prepare a query, execute the statement, and then close the statement. </p>
<p>QueryContext may return <a href="#ErrSkip">ErrSkip</a>. </p>
<p>QueryContext must honor the context timeout and return when the context is canceled. </p>
<pre data-language="go">type QueryerContext interface {
    QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
}</pre> <h2 id="Result">type <span>Result</span>  </h2> <p>Result is the result of a query execution. </p>
<pre data-language="go">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)
}</pre> <h2 id="Rows">type <span>Rows</span>  </h2> <p>Rows is an iterator over an executed query's results. </p>
<pre data-language="go">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
}</pre> <h2 id="RowsAffected">type <span>RowsAffected</span>  </h2> <p>RowsAffected implements <a href="#Result">Result</a> for an INSERT or UPDATE operation which mutates a number of rows. </p>
<pre data-language="go">type RowsAffected int64</pre> <h3 id="RowsAffected.LastInsertId">func (RowsAffected) <span>LastInsertId</span>  </h3> <pre data-language="go">func (RowsAffected) LastInsertId() (int64, error)</pre> <h3 id="RowsAffected.RowsAffected">func (RowsAffected) <span>RowsAffected</span>  </h3> <pre data-language="go">func (v RowsAffected) RowsAffected() (int64, error)</pre> <h2 id="RowsColumnTypeDatabaseTypeName">type <span>RowsColumnTypeDatabaseTypeName</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>RowsColumnTypeDatabaseTypeName may be implemented by <a href="#Rows">Rows</a>. 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". </p>
<pre data-language="go">type RowsColumnTypeDatabaseTypeName interface {
    Rows
    ColumnTypeDatabaseTypeName(index int) string
}</pre> <h2 id="RowsColumnTypeLength">type <span>RowsColumnTypeLength</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>RowsColumnTypeLength may be implemented by <a href="#Rows">Rows</a>. 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 <span>math.MaxInt64</span>. The following are examples of returned values for various types: </p>
<pre data-language="go">TEXT          (math.MaxInt64, true)
varchar(10)   (10, true)
nvarchar(10)  (10, true)
decimal       (0, false)
int           (0, false)
bytea(30)     (30, true)
</pre> <pre data-language="go">type RowsColumnTypeLength interface {
    Rows
    ColumnTypeLength(index int) (length int64, ok bool)
}</pre> <h2 id="RowsColumnTypeNullable">type <span>RowsColumnTypeNullable</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>RowsColumnTypeNullable may be implemented by <a href="#Rows">Rows</a>. 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. </p>
<pre data-language="go">type RowsColumnTypeNullable interface {
    Rows
    ColumnTypeNullable(index int) (nullable, ok bool)
}</pre> <h2 id="RowsColumnTypePrecisionScale">type <span>RowsColumnTypePrecisionScale</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>RowsColumnTypePrecisionScale may be implemented by <a href="#Rows">Rows</a>. 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: </p>
<pre data-language="go">decimal(38, 4)    (38, 4, true)
int               (0, 0, false)
decimal           (math.MaxInt64, math.MaxInt64, true)
</pre> <pre data-language="go">type RowsColumnTypePrecisionScale interface {
    Rows
    ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)
}</pre> <h2 id="RowsColumnTypeScanType">type <span>RowsColumnTypeScanType</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>RowsColumnTypeScanType may be implemented by <a href="#Rows">Rows</a>. It should return the value type that can be used to scan types into. For example, the database column type "bigint" this should return "<span>reflect.TypeOf</span>(int64(0))". </p>
<pre data-language="go">type RowsColumnTypeScanType interface {
    Rows
    ColumnTypeScanType(index int) reflect.Type
}</pre> <h2 id="RowsNextResultSet">type <span>RowsNextResultSet</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>RowsNextResultSet extends the <a href="#Rows">Rows</a> interface by providing a way to signal the driver to advance to the next result set. </p>
<pre data-language="go">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
}</pre> <h2 id="SessionResetter">type <span>SessionResetter</span>  <span title="Added in Go 1.10">1.10</span> </h2> <p>SessionResetter may be implemented by <a href="#Conn">Conn</a> to allow drivers to reset the session state associated with the connection and to signal a bad connection. </p>
<pre data-language="go">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
}</pre> <h2 id="Stmt">type <span>Stmt</span>  </h2> <p>Stmt is a prepared statement. It is bound to a <a href="#Conn">Conn</a> and not used by multiple goroutines concurrently. </p>
<pre data-language="go">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 &gt;= 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)
}</pre> <h2 id="StmtExecContext">type <span>StmtExecContext</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>StmtExecContext enhances the <a href="#Stmt">Stmt</a> interface by providing Exec with context. </p>
<pre data-language="go">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)
}</pre> <h2 id="StmtQueryContext">type <span>StmtQueryContext</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>StmtQueryContext enhances the <a href="#Stmt">Stmt</a> interface by providing Query with context. </p>
<pre data-language="go">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)
}</pre> <h2 id="Tx">type <span>Tx</span>  </h2> <p>Tx is a transaction. </p>
<pre data-language="go">type Tx interface {
    Commit() error
    Rollback() error
}</pre> <h2 id="TxOptions">type <span>TxOptions</span>  <span title="Added in Go 1.8">1.8</span> </h2> <p>TxOptions holds the transaction options. </p>
<p>This type should be considered identical to <span>database/sql.TxOptions</span>. </p>
<pre data-language="go">type TxOptions struct {
    Isolation IsolationLevel
    ReadOnly  bool
}
</pre> <h2 id="Validator">type <span>Validator</span>  <span title="Added in Go 1.15">1.15</span> </h2> <p>Validator may be implemented by <a href="#Conn">Conn</a> to allow drivers to signal if a connection is valid or if it should be discarded. </p>
<p>If implemented, drivers may return the underlying error from queries, even if the connection should be discarded by the connection pool. </p>
<pre data-language="go">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
}</pre> <h2 id="Value">type <span>Value</span>  </h2> <p>Value is a value that drivers must be able to handle. It is either nil, a type handled by a database driver's <a href="#NamedValueChecker">NamedValueChecker</a> interface, or an instance of one of these types: </p>
<pre data-language="go">int64
float64
bool
[]byte
string
time.Time
</pre> <p>If the driver supports cursors, a returned Value may also implement the <a href="#Rows">Rows</a> interface in this package. This is used, for example, when a user selects a cursor such as "select cursor(select * from my_table) from dual". If the <a href="#Rows">Rows</a> from the select is closed, the cursor <a href="#Rows">Rows</a> will also be closed. </p>
<pre data-language="go">type Value any</pre> <h2 id="ValueConverter">type <span>ValueConverter</span>  </h2> <p>ValueConverter is the interface providing the ConvertValue method. </p>
<p>Various implementations of ValueConverter are provided by the driver package to provide consistent implementations of conversions between drivers. The ValueConverters have several uses: </p>
<ul> <li><p>converting from the <a href="#Value">Value</a> 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. </p></li>
<li><p>converting a value as given from the database into one of the driver <a href="#Value">Value</a> types. </p></li>
<li><p>by the <span>database/sql</span> package, for converting from a driver's <a href="#Value">Value</a> type to a user's type in a scan. </p></li>
</ul> <pre data-language="go">type ValueConverter interface {
    // ConvertValue converts a value to a driver Value.
    ConvertValue(v any) (Value, error)
}</pre> <h2 id="Valuer">type <span>Valuer</span>  </h2> <p>Valuer is the interface providing the Value method. </p>
<p>Types implementing Valuer interface are able to convert themselves to a driver <a href="#Value">Value</a>. </p>
<pre data-language="go">type Valuer interface {
    // Value returns a driver Value.
    // Value must not panic.
    Value() (Value, error)
}</pre><div class="_attribution">
  <p class="_attribution-p">
    &copy; Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br>
    <a href="http://golang.org/pkg/database/sql/driver/" class="_attribution-link">http://golang.org/pkg/database/sql/driver/</a>
  </p>
</div>