libgo: update to Go1.10rc2

[official-gcc.git] / libgo / go / database / sql / driver / driver.go

// Copyright 2011 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Package driver defines interfaces to be implemented by database
// drivers as used by package sql.
//
// Most code should use package sql.
package driver

import (
        "context"
        "errors"
        "reflect"
)

// Value is a value that drivers must be able to handle.
// It is either nil, a type handled by a database driver's NamedValueChecker
// interface, or an instance of one of these types:
//
//   int64
//   float64
//   bool
//   []byte
//   string
//   time.Time
type Value interface{}

// NamedValue holds both the value name and value.
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
}

// Driver is the interface that must be implemented by a database
// driver.
//
// Database drivers may implement DriverContext for access
// to contexts and to parse the name only once for a pool of connections,
// instead of once per connection.
type Driver interface {
        // Open 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)
}

// If a Driver implements DriverContext, then sql.DB will call
// OpenConnector to obtain a Connector and then invoke
// that Connector's Conn method to obtain each needed connection,
// instead of invoking the Driver's Open method for each connection.
// The two-step sequence allows drivers to parse the name just once
// and also provides access to per-Conn contexts.
type DriverContext interface {
        // OpenConnector must parse the name in the same format that Driver.Open
        // parses the name parameter.
        OpenConnector(name string) (Connector, error)
}

// 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.
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.
        //
        // 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
}

// 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.
var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")

// 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.
var ErrBadConn = errors.New("driver: bad connection")

// 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.
type Pinger interface {
        Ping(ctx context.Context) error
}

// Execer is an optional interface that may be implemented by a Conn.
//
// If a Conn implements neither ExecerContext nor Execer 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.
type Execer interface {
        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.
//
// ExecerContext may return ErrSkip.
//
// ExecerContext must honor the context timeout and return when the context is canceled.
type ExecerContext interface {
        ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
}

// 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.
type Queryer interface {
        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.
//
// QueryerContext may return ErrSkip.
//
// QueryerContext must honor the context timeout and return when the context is canceled.
type QueryerContext interface {
        QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
}

// Conn is a connection to a database. It is not used concurrently
// by multiple goroutines.
//
// Conn is assumed to be stateful.
type Conn interface {
        // Prepare 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.
        Close() error

        // Begin starts and returns a new transaction.
        //
        // Deprecated: Drivers should implement ConnBeginTx instead (or additionally).
        Begin() (Tx, error)
}

// ConnPrepareContext enhances the Conn interface with context.
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)
}

// 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.
type IsolationLevel int

// TxOptions holds the transaction options.
//
// This type should be considered identical to sql.TxOptions.
type TxOptions struct {
        Isolation IsolationLevel
        ReadOnly  bool
}

// ConnBeginTx enhances the Conn interface with context and 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)
}

// SessionResetter may be implemented by Conn to allow drivers to reset the
// session state associated with the connection and to signal a bad connection.
type SessionResetter interface {
        // ResetSession is called while a connection is in the connection
        // pool. No queries will run on this connection until this method returns.
        //
        // If the connection is bad this should return driver.ErrBadConn to prevent
        // the connection from being returned to the connection pool. Any other
        // error will be discarded.
        ResetSession(ctx context.Context) error
}

// Result is the result of a query execution.
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)
}

// Stmt is a prepared statement. It is bound to a Conn and not
// used by multiple goroutines concurrently.
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.
        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 enhances the Stmt interface by providing Exec with context.
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 enhances the Stmt interface by providing Query with context.
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)
}

// 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.
var ErrRemoveArgument = errors.New("driver: remove argument from query")

// 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.
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
}

// ColumnConverter may be optionally implemented by Stmt if the
// statement is aware of its own columns' types and can convert from
// any type to a driver Value.
//
// Deprecated: Drivers should implement NamedValueChecker.
type ColumnConverter interface {
        // ColumnConverter 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
}

// Rows is an iterator over an executed query's results.
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
}

// RowsNextResultSet extends the Rows interface by providing a way to signal
// the driver to advance to the next result set.
type RowsNextResultSet interface {
        Rows

        // HasNextResultSet 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
}

// RowsColumnTypeScanType may be implemented by Rows. It should return
// the value type that can be used to scan types into. For example, the database
// column type "bigint" this should return "reflect.TypeOf(int64(0))".
type RowsColumnTypeScanType interface {
        Rows
        ColumnTypeScanType(index int) reflect.Type
}

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

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

// RowsColumnTypeNullable may be implemented by Rows. The nullable value should
// be true if it is known the column may be null, or false if the column is known
// to be not nullable.
// If the column nullability is unknown, ok should be false.
type RowsColumnTypeNullable interface {
        Rows
        ColumnTypeNullable(index int) (nullable, ok bool)
}

// RowsColumnTypePrecisionScale may be implemented by Rows. It should return
// the precision and scale for decimal types. If not applicable, ok should be false.
// The following are examples of returned values for various types:
//   decimal(38, 4)    (38, 4, true)
//   int               (0, 0, false)
//   decimal           (math.MaxInt64, math.MaxInt64, true)
type RowsColumnTypePrecisionScale interface {
        Rows
        ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)
}

// Tx is a transaction.
type Tx interface {
        Commit() error
        Rollback() error
}

// RowsAffected implements Result for an INSERT or UPDATE operation
// which mutates a number of rows.
type RowsAffected int64

var _ Result = RowsAffected(0)

func (RowsAffected) LastInsertId() (int64, error) {
        return 0, errors.New("no LastInsertId available")
}

func (v RowsAffected) RowsAffected() (int64, error) {
        return int64(v), nil
}

// 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.
var ResultNoRows noRows

type noRows struct{}

var _ Result = noRows{}

func (noRows) LastInsertId() (int64, error) {
        return 0, errors.New("no LastInsertId available after DDL statement")
}

func (noRows) RowsAffected() (int64, error) {
        return 0, errors.New("no RowsAffected available after DDL statement")
}