...
Run Format

Source file src/database/sql/driver/driver.go

Documentation: database/sql/driver

     1  // Copyright 2011 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package driver defines interfaces to be implemented by database
     6  // drivers as used by package sql.
     7  //
     8  // Most code should use package sql.
     9  package driver
    10  
    11  import (
    12  	"context"
    13  	"errors"
    14  	"reflect"
    15  )
    16  
    17  // Value is a value that drivers must be able to handle.
    18  // It is either nil, a type handled by a database driver's NamedValueChecker
    19  // interface, or an instance of one of these types:
    20  //
    21  //   int64
    22  //   float64
    23  //   bool
    24  //   []byte
    25  //   string
    26  //   time.Time
    27  //
    28  // If the driver supports cursors, a returned Value may also implement the Rows interface
    29  // in this package. This is used when, for example, when a user selects a cursor
    30  // such as "select cursor(select * from my_table) from dual". If the Rows
    31  // from the select is closed, the cursor Rows will also be closed.
    32  type Value interface{}
    33  
    34  // NamedValue holds both the value name and value.
    35  type NamedValue struct {
    36  	// If the Name is not empty it should be used for the parameter identifier and
    37  	// not the ordinal position.
    38  	//
    39  	// Name will not have a symbol prefix.
    40  	Name string
    41  
    42  	// Ordinal position of the parameter starting from one and is always set.
    43  	Ordinal int
    44  
    45  	// Value is the parameter value.
    46  	Value Value
    47  }
    48  
    49  // Driver is the interface that must be implemented by a database
    50  // driver.
    51  //
    52  // Database drivers may implement DriverContext for access
    53  // to contexts and to parse the name only once for a pool of connections,
    54  // instead of once per connection.
    55  type Driver interface {
    56  	// Open returns a new connection to the database.
    57  	// The name is a string in a driver-specific format.
    58  	//
    59  	// Open may return a cached connection (one previously
    60  	// closed), but doing so is unnecessary; the sql package
    61  	// maintains a pool of idle connections for efficient re-use.
    62  	//
    63  	// The returned connection is only used by one goroutine at a
    64  	// time.
    65  	Open(name string) (Conn, error)
    66  }
    67  
    68  // If a Driver implements DriverContext, then sql.DB will call
    69  // OpenConnector to obtain a Connector and then invoke
    70  // that Connector's Conn method to obtain each needed connection,
    71  // instead of invoking the Driver's Open method for each connection.
    72  // The two-step sequence allows drivers to parse the name just once
    73  // and also provides access to per-Conn contexts.
    74  type DriverContext interface {
    75  	// OpenConnector must parse the name in the same format that Driver.Open
    76  	// parses the name parameter.
    77  	OpenConnector(name string) (Connector, error)
    78  }
    79  
    80  // A Connector represents a driver in a fixed configuration
    81  // and can create any number of equivalent Conns for use
    82  // by multiple goroutines.
    83  //
    84  // A Connector can be passed to sql.OpenDB, to allow drivers
    85  // to implement their own sql.DB constructors, or returned by
    86  // DriverContext's OpenConnector method, to allow drivers
    87  // access to context and to avoid repeated parsing of driver
    88  // configuration.
    89  type Connector interface {
    90  	// Connect returns a connection to the database.
    91  	// Connect may return a cached connection (one previously
    92  	// closed), but doing so is unnecessary; the sql package
    93  	// maintains a pool of idle connections for efficient re-use.
    94  	//
    95  	// The provided context.Context is for dialing purposes only
    96  	// (see net.DialContext) and should not be stored or used for
    97  	// other purposes.
    98  	//
    99  	// The returned connection is only used by one goroutine at a
   100  	// time.
   101  	Connect(context.Context) (Conn, error)
   102  
   103  	// Driver returns the underlying Driver of the Connector,
   104  	// mainly to maintain compatibility with the Driver method
   105  	// on sql.DB.
   106  	Driver() Driver
   107  }
   108  
   109  // ErrSkip may be returned by some optional interfaces' methods to
   110  // indicate at runtime that the fast path is unavailable and the sql
   111  // package should continue as if the optional interface was not
   112  // implemented. ErrSkip is only supported where explicitly
   113  // documented.
   114  var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")
   115  
   116  // ErrBadConn should be returned by a driver to signal to the sql
   117  // package that a driver.Conn is in a bad state (such as the server
   118  // having earlier closed the connection) and the sql package should
   119  // retry on a new connection.
   120  //
   121  // To prevent duplicate operations, ErrBadConn should NOT be returned
   122  // if there's a possibility that the database server might have
   123  // performed the operation. Even if the server sends back an error,
   124  // you shouldn't return ErrBadConn.
   125  var ErrBadConn = errors.New("driver: bad connection")
   126  
   127  // Pinger is an optional interface that may be implemented by a Conn.
   128  //
   129  // If a Conn does not implement Pinger, the sql package's DB.Ping and
   130  // DB.PingContext will check if there is at least one Conn available.
   131  //
   132  // If Conn.Ping returns ErrBadConn, DB.Ping and DB.PingContext will remove
   133  // the Conn from pool.
   134  type Pinger interface {
   135  	Ping(ctx context.Context) error
   136  }
   137  
   138  // Execer is an optional interface that may be implemented by a Conn.
   139  //
   140  // If a Conn implements neither ExecerContext nor Execer,
   141  // the sql package's DB.Exec will first prepare a query, execute the statement,
   142  // and then close the statement.
   143  //
   144  // Exec may return ErrSkip.
   145  //
   146  // Deprecated: Drivers should implement ExecerContext instead.
   147  type Execer interface {
   148  	Exec(query string, args []Value) (Result, error)
   149  }
   150  
   151  // ExecerContext is an optional interface that may be implemented by a Conn.
   152  //
   153  // If a Conn does not implement ExecerContext, the sql package's DB.Exec
   154  // will fall back to Execer; if the Conn does not implement Execer either,
   155  // DB.Exec will first prepare a query, execute the statement, and then
   156  // close the statement.
   157  //
   158  // ExecerContext may return ErrSkip.
   159  //
   160  // ExecerContext must honor the context timeout and return when the context is canceled.
   161  type ExecerContext interface {
   162  	ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
   163  }
   164  
   165  // Queryer is an optional interface that may be implemented by a Conn.
   166  //
   167  // If a Conn implements neither QueryerContext nor Queryer,
   168  // the sql package's DB.Query will first prepare a query, execute the statement,
   169  // and then close the statement.
   170  //
   171  // Query may return ErrSkip.
   172  //
   173  // Deprecated: Drivers should implement QueryerContext instead.
   174  type Queryer interface {
   175  	Query(query string, args []Value) (Rows, error)
   176  }
   177  
   178  // QueryerContext is an optional interface that may be implemented by a Conn.
   179  //
   180  // If a Conn does not implement QueryerContext, the sql package's DB.Query
   181  // will fall back to Queryer; if the Conn does not implement Queryer either,
   182  // DB.Query will first prepare a query, execute the statement, and then
   183  // close the statement.
   184  //
   185  // QueryerContext may return ErrSkip.
   186  //
   187  // QueryerContext must honor the context timeout and return when the context is canceled.
   188  type QueryerContext interface {
   189  	QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
   190  }
   191  
   192  // Conn is a connection to a database. It is not used concurrently
   193  // by multiple goroutines.
   194  //
   195  // Conn is assumed to be stateful.
   196  type Conn interface {
   197  	// Prepare returns a prepared statement, bound to this connection.
   198  	Prepare(query string) (Stmt, error)
   199  
   200  	// Close invalidates and potentially stops any current
   201  	// prepared statements and transactions, marking this
   202  	// connection as no longer in use.
   203  	//
   204  	// Because the sql package maintains a free pool of
   205  	// connections and only calls Close when there's a surplus of
   206  	// idle connections, it shouldn't be necessary for drivers to
   207  	// do their own connection caching.
   208  	Close() error
   209  
   210  	// Begin starts and returns a new transaction.
   211  	//
   212  	// Deprecated: Drivers should implement ConnBeginTx instead (or additionally).
   213  	Begin() (Tx, error)
   214  }
   215  
   216  // ConnPrepareContext enhances the Conn interface with context.
   217  type ConnPrepareContext interface {
   218  	// PrepareContext returns a prepared statement, bound to this connection.
   219  	// context is for the preparation of the statement,
   220  	// it must not store the context within the statement itself.
   221  	PrepareContext(ctx context.Context, query string) (Stmt, error)
   222  }
   223  
   224  // IsolationLevel is the transaction isolation level stored in TxOptions.
   225  //
   226  // This type should be considered identical to sql.IsolationLevel along
   227  // with any values defined on it.
   228  type IsolationLevel int
   229  
   230  // TxOptions holds the transaction options.
   231  //
   232  // This type should be considered identical to sql.TxOptions.
   233  type TxOptions struct {
   234  	Isolation IsolationLevel
   235  	ReadOnly  bool
   236  }
   237  
   238  // ConnBeginTx enhances the Conn interface with context and TxOptions.
   239  type ConnBeginTx interface {
   240  	// BeginTx starts and returns a new transaction.
   241  	// If the context is canceled by the user the sql package will
   242  	// call Tx.Rollback before discarding and closing the connection.
   243  	//
   244  	// This must check opts.Isolation to determine if there is a set
   245  	// isolation level. If the driver does not support a non-default
   246  	// level and one is set or if there is a non-default isolation level
   247  	// that is not supported, an error must be returned.
   248  	//
   249  	// This must also check opts.ReadOnly to determine if the read-only
   250  	// value is true to either set the read-only transaction property if supported
   251  	// or return an error if it is not supported.
   252  	BeginTx(ctx context.Context, opts TxOptions) (Tx, error)
   253  }
   254  
   255  // SessionResetter may be implemented by Conn to allow drivers to reset the
   256  // session state associated with the connection and to signal a bad connection.
   257  type SessionResetter interface {
   258  	// ResetSession is called while a connection is in the connection
   259  	// pool. No queries will run on this connection until this method returns.
   260  	//
   261  	// If the connection is bad this should return driver.ErrBadConn to prevent
   262  	// the connection from being returned to the connection pool. Any other
   263  	// error will be discarded.
   264  	ResetSession(ctx context.Context) error
   265  }
   266  
   267  // Result is the result of a query execution.
   268  type Result interface {
   269  	// LastInsertId returns the database's auto-generated ID
   270  	// after, for example, an INSERT into a table with primary
   271  	// key.
   272  	LastInsertId() (int64, error)
   273  
   274  	// RowsAffected returns the number of rows affected by the
   275  	// query.
   276  	RowsAffected() (int64, error)
   277  }
   278  
   279  // Stmt is a prepared statement. It is bound to a Conn and not
   280  // used by multiple goroutines concurrently.
   281  type Stmt interface {
   282  	// Close closes the statement.
   283  	//
   284  	// As of Go 1.1, a Stmt will not be closed if it's in use
   285  	// by any queries.
   286  	Close() error
   287  
   288  	// NumInput returns the number of placeholder parameters.
   289  	//
   290  	// If NumInput returns >= 0, the sql package will sanity check
   291  	// argument counts from callers and return errors to the caller
   292  	// before the statement's Exec or Query methods are called.
   293  	//
   294  	// NumInput may also return -1, if the driver doesn't know
   295  	// its number of placeholders. In that case, the sql package
   296  	// will not sanity check Exec or Query argument counts.
   297  	NumInput() int
   298  
   299  	// Exec executes a query that doesn't return rows, such
   300  	// as an INSERT or UPDATE.
   301  	//
   302  	// Deprecated: Drivers should implement StmtExecContext instead (or additionally).
   303  	Exec(args []Value) (Result, error)
   304  
   305  	// Query executes a query that may return rows, such as a
   306  	// SELECT.
   307  	//
   308  	// Deprecated: Drivers should implement StmtQueryContext instead (or additionally).
   309  	Query(args []Value) (Rows, error)
   310  }
   311  
   312  // StmtExecContext enhances the Stmt interface by providing Exec with context.
   313  type StmtExecContext interface {
   314  	// ExecContext executes a query that doesn't return rows, such
   315  	// as an INSERT or UPDATE.
   316  	//
   317  	// ExecContext must honor the context timeout and return when it is canceled.
   318  	ExecContext(ctx context.Context, args []NamedValue) (Result, error)
   319  }
   320  
   321  // StmtQueryContext enhances the Stmt interface by providing Query with context.
   322  type StmtQueryContext interface {
   323  	// QueryContext executes a query that may return rows, such as a
   324  	// SELECT.
   325  	//
   326  	// QueryContext must honor the context timeout and return when it is canceled.
   327  	QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
   328  }
   329  
   330  // ErrRemoveArgument may be returned from NamedValueChecker to instruct the
   331  // sql package to not pass the argument to the driver query interface.
   332  // Return when accepting query specific options or structures that aren't
   333  // SQL query arguments.
   334  var ErrRemoveArgument = errors.New("driver: remove argument from query")
   335  
   336  // NamedValueChecker may be optionally implemented by Conn or Stmt. It provides
   337  // the driver more control to handle Go and database types beyond the default
   338  // Values types allowed.
   339  //
   340  // The sql package checks for value checkers in the following order,
   341  // stopping at the first found match: Stmt.NamedValueChecker, Conn.NamedValueChecker,
   342  // Stmt.ColumnConverter, DefaultParameterConverter.
   343  //
   344  // If CheckNamedValue returns ErrRemoveArgument, the NamedValue will not be included in
   345  // the final query arguments. This may be used to pass special options to
   346  // the query itself.
   347  //
   348  // If ErrSkip is returned the column converter error checking
   349  // path is used for the argument. Drivers may wish to return ErrSkip after
   350  // they have exhausted their own special cases.
   351  type NamedValueChecker interface {
   352  	// CheckNamedValue is called before passing arguments to the driver
   353  	// and is called in place of any ColumnConverter. CheckNamedValue must do type
   354  	// validation and conversion as appropriate for the driver.
   355  	CheckNamedValue(*NamedValue) error
   356  }
   357  
   358  // ColumnConverter may be optionally implemented by Stmt if the
   359  // statement is aware of its own columns' types and can convert from
   360  // any type to a driver Value.
   361  //
   362  // Deprecated: Drivers should implement NamedValueChecker.
   363  type ColumnConverter interface {
   364  	// ColumnConverter returns a ValueConverter for the provided
   365  	// column index. If the type of a specific column isn't known
   366  	// or shouldn't be handled specially, DefaultValueConverter
   367  	// can be returned.
   368  	ColumnConverter(idx int) ValueConverter
   369  }
   370  
   371  // Rows is an iterator over an executed query's results.
   372  type Rows interface {
   373  	// Columns returns the names of the columns. The number of
   374  	// columns of the result is inferred from the length of the
   375  	// slice. If a particular column name isn't known, an empty
   376  	// string should be returned for that entry.
   377  	Columns() []string
   378  
   379  	// Close closes the rows iterator.
   380  	Close() error
   381  
   382  	// Next is called to populate the next row of data into
   383  	// the provided slice. The provided slice will be the same
   384  	// size as the Columns() are wide.
   385  	//
   386  	// Next should return io.EOF when there are no more rows.
   387  	//
   388  	// The dest should not be written to outside of Next. Care
   389  	// should be taken when closing Rows not to modify
   390  	// a buffer held in dest.
   391  	Next(dest []Value) error
   392  }
   393  
   394  // RowsNextResultSet extends the Rows interface by providing a way to signal
   395  // the driver to advance to the next result set.
   396  type RowsNextResultSet interface {
   397  	Rows
   398  
   399  	// HasNextResultSet is called at the end of the current result set and
   400  	// reports whether there is another result set after the current one.
   401  	HasNextResultSet() bool
   402  
   403  	// NextResultSet advances the driver to the next result set even
   404  	// if there are remaining rows in the current result set.
   405  	//
   406  	// NextResultSet should return io.EOF when there are no more result sets.
   407  	NextResultSet() error
   408  }
   409  
   410  // RowsColumnTypeScanType may be implemented by Rows. It should return
   411  // the value type that can be used to scan types into. For example, the database
   412  // column type "bigint" this should return "reflect.TypeOf(int64(0))".
   413  type RowsColumnTypeScanType interface {
   414  	Rows
   415  	ColumnTypeScanType(index int) reflect.Type
   416  }
   417  
   418  // RowsColumnTypeDatabaseTypeName may be implemented by Rows. It should return the
   419  // database system type name without the length. Type names should be uppercase.
   420  // Examples of returned types: "VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT",
   421  // "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML",
   422  // "TIMESTAMP".
   423  type RowsColumnTypeDatabaseTypeName interface {
   424  	Rows
   425  	ColumnTypeDatabaseTypeName(index int) string
   426  }
   427  
   428  // RowsColumnTypeLength may be implemented by Rows. It should return the length
   429  // of the column type if the column is a variable length type. If the column is
   430  // not a variable length type ok should return false.
   431  // If length is not limited other than system limits, it should return math.MaxInt64.
   432  // The following are examples of returned values for various types:
   433  //   TEXT          (math.MaxInt64, true)
   434  //   varchar(10)   (10, true)
   435  //   nvarchar(10)  (10, true)
   436  //   decimal       (0, false)
   437  //   int           (0, false)
   438  //   bytea(30)     (30, true)
   439  type RowsColumnTypeLength interface {
   440  	Rows
   441  	ColumnTypeLength(index int) (length int64, ok bool)
   442  }
   443  
   444  // RowsColumnTypeNullable may be implemented by Rows. The nullable value should
   445  // be true if it is known the column may be null, or false if the column is known
   446  // to be not nullable.
   447  // If the column nullability is unknown, ok should be false.
   448  type RowsColumnTypeNullable interface {
   449  	Rows
   450  	ColumnTypeNullable(index int) (nullable, ok bool)
   451  }
   452  
   453  // RowsColumnTypePrecisionScale may be implemented by Rows. It should return
   454  // the precision and scale for decimal types. If not applicable, ok should be false.
   455  // The following are examples of returned values for various types:
   456  //   decimal(38, 4)    (38, 4, true)
   457  //   int               (0, 0, false)
   458  //   decimal           (math.MaxInt64, math.MaxInt64, true)
   459  type RowsColumnTypePrecisionScale interface {
   460  	Rows
   461  	ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)
   462  }
   463  
   464  // Tx is a transaction.
   465  type Tx interface {
   466  	Commit() error
   467  	Rollback() error
   468  }
   469  
   470  // RowsAffected implements Result for an INSERT or UPDATE operation
   471  // which mutates a number of rows.
   472  type RowsAffected int64
   473  
   474  var _ Result = RowsAffected(0)
   475  
   476  func (RowsAffected) LastInsertId() (int64, error) {
   477  	return 0, errors.New("LastInsertId is not supported by this driver")
   478  }
   479  
   480  func (v RowsAffected) RowsAffected() (int64, error) {
   481  	return int64(v), nil
   482  }
   483  
   484  // ResultNoRows is a pre-defined Result for drivers to return when a DDL
   485  // command (such as a CREATE TABLE) succeeds. It returns an error for both
   486  // LastInsertId and RowsAffected.
   487  var ResultNoRows noRows
   488  
   489  type noRows struct{}
   490  
   491  var _ Result = noRows{}
   492  
   493  func (noRows) LastInsertId() (int64, error) {
   494  	return 0, errors.New("no LastInsertId available after DDL statement")
   495  }
   496  
   497  func (noRows) RowsAffected() (int64, error) {
   498  	return 0, errors.New("no RowsAffected available after DDL statement")
   499  }
   500  

View as plain text