...
Run Format

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

     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 or an instance of one of these types:
    19	//
    20	//   int64
    21	//   float64
    22	//   bool
    23	//   []byte
    24	//   string
    25	//   time.Time
    26	type Value interface{}
    27	
    28	// NamedValue holds both the value name and value.
    29	type NamedValue struct {
    30		// If the Name is not empty it should be used for the parameter identifier and
    31		// not the ordinal position.
    32		//
    33		// Name will not have a symbol prefix.
    34		Name string
    35	
    36		// Ordinal position of the parameter starting from one and is always set.
    37		Ordinal int
    38	
    39		// Value is the parameter value.
    40		Value Value
    41	}
    42	
    43	// Driver is the interface that must be implemented by a database
    44	// driver.
    45	type Driver interface {
    46		// Open returns a new connection to the database.
    47		// The name is a string in a driver-specific format.
    48		//
    49		// Open may return a cached connection (one previously
    50		// closed), but doing so is unnecessary; the sql package
    51		// maintains a pool of idle connections for efficient re-use.
    52		//
    53		// The returned connection is only used by one goroutine at a
    54		// time.
    55		Open(name string) (Conn, error)
    56	}
    57	
    58	// ErrSkip may be returned by some optional interfaces' methods to
    59	// indicate at runtime that the fast path is unavailable and the sql
    60	// package should continue as if the optional interface was not
    61	// implemented. ErrSkip is only supported where explicitly
    62	// documented.
    63	var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")
    64	
    65	// ErrBadConn should be returned by a driver to signal to the sql
    66	// package that a driver.Conn is in a bad state (such as the server
    67	// having earlier closed the connection) and the sql package should
    68	// retry on a new connection.
    69	//
    70	// To prevent duplicate operations, ErrBadConn should NOT be returned
    71	// if there's a possibility that the database server might have
    72	// performed the operation. Even if the server sends back an error,
    73	// you shouldn't return ErrBadConn.
    74	var ErrBadConn = errors.New("driver: bad connection")
    75	
    76	// Pinger is an optional interface that may be implemented by a Conn.
    77	//
    78	// If a Conn does not implement Pinger, the sql package's DB.Ping and
    79	// DB.PingContext will check if there is at least one Conn available.
    80	//
    81	// If Conn.Ping returns ErrBadConn, DB.Ping and DB.PingContext will remove
    82	// the Conn from pool.
    83	type Pinger interface {
    84		Ping(ctx context.Context) error
    85	}
    86	
    87	// Execer is an optional interface that may be implemented by a Conn.
    88	//
    89	// If a Conn does not implement Execer, the sql package's DB.Exec will
    90	// first prepare a query, execute the statement, and then close the
    91	// statement.
    92	//
    93	// Exec may return ErrSkip.
    94	//
    95	// Deprecated: Drivers should implement ExecerContext instead (or additionally).
    96	type Execer interface {
    97		Exec(query string, args []Value) (Result, error)
    98	}
    99	
   100	// ExecerContext is an optional interface that may be implemented by a Conn.
   101	//
   102	// If a Conn does not implement ExecerContext, the sql package's DB.Exec will
   103	// first prepare a query, execute the statement, and then close the
   104	// statement.
   105	//
   106	// ExecerContext may return ErrSkip.
   107	//
   108	// ExecerContext must honor the context timeout and return when the context is canceled.
   109	type ExecerContext interface {
   110		ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
   111	}
   112	
   113	// Queryer is an optional interface that may be implemented by a Conn.
   114	//
   115	// If a Conn does not implement Queryer, the sql package's DB.Query will
   116	// first prepare a query, execute the statement, and then close the
   117	// statement.
   118	//
   119	// Query may return ErrSkip.
   120	//
   121	// Deprecated: Drivers should implement QueryerContext instead (or additionally).
   122	type Queryer interface {
   123		Query(query string, args []Value) (Rows, error)
   124	}
   125	
   126	// QueryerContext is an optional interface that may be implemented by a Conn.
   127	//
   128	// If a Conn does not implement QueryerContext, the sql package's DB.Query will
   129	// first prepare a query, execute the statement, and then close the
   130	// statement.
   131	//
   132	// QueryerContext may return ErrSkip.
   133	//
   134	// QueryerContext must honor the context timeout and return when the context is canceled.
   135	type QueryerContext interface {
   136		QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
   137	}
   138	
   139	// Conn is a connection to a database. It is not used concurrently
   140	// by multiple goroutines.
   141	//
   142	// Conn is assumed to be stateful.
   143	type Conn interface {
   144		// Prepare returns a prepared statement, bound to this connection.
   145		Prepare(query string) (Stmt, error)
   146	
   147		// Close invalidates and potentially stops any current
   148		// prepared statements and transactions, marking this
   149		// connection as no longer in use.
   150		//
   151		// Because the sql package maintains a free pool of
   152		// connections and only calls Close when there's a surplus of
   153		// idle connections, it shouldn't be necessary for drivers to
   154		// do their own connection caching.
   155		Close() error
   156	
   157		// Begin starts and returns a new transaction.
   158		//
   159		// Deprecated: Drivers should implement ConnBeginTx instead (or additionally).
   160		Begin() (Tx, error)
   161	}
   162	
   163	// ConnPrepareContext enhances the Conn interface with context.
   164	type ConnPrepareContext interface {
   165		// PrepareContext returns a prepared statement, bound to this connection.
   166		// context is for the preparation of the statement,
   167		// it must not store the context within the statement itself.
   168		PrepareContext(ctx context.Context, query string) (Stmt, error)
   169	}
   170	
   171	// IsolationLevel is the transaction isolation level stored in TxOptions.
   172	//
   173	// This type should be considered identical to sql.IsolationLevel along
   174	// with any values defined on it.
   175	type IsolationLevel int
   176	
   177	// TxOptions holds the transaction options.
   178	//
   179	// This type should be considered identical to sql.TxOptions.
   180	type TxOptions struct {
   181		Isolation IsolationLevel
   182		ReadOnly  bool
   183	}
   184	
   185	// ConnBeginTx enhances the Conn interface with context and TxOptions.
   186	type ConnBeginTx interface {
   187		// BeginTx starts and returns a new transaction.
   188		// If the context is canceled by the user the sql package will
   189		// call Tx.Rollback before discarding and closing the connection.
   190		//
   191		// This must check opts.Isolation to determine if there is a set
   192		// isolation level. If the driver does not support a non-default
   193		// level and one is set or if there is a non-default isolation level
   194		// that is not supported, an error must be returned.
   195		//
   196		// This must also check opts.ReadOnly to determine if the read-only
   197		// value is true to either set the read-only transaction property if supported
   198		// or return an error if it is not supported.
   199		BeginTx(ctx context.Context, opts TxOptions) (Tx, error)
   200	}
   201	
   202	// Result is the result of a query execution.
   203	type Result interface {
   204		// LastInsertId returns the database's auto-generated ID
   205		// after, for example, an INSERT into a table with primary
   206		// key.
   207		LastInsertId() (int64, error)
   208	
   209		// RowsAffected returns the number of rows affected by the
   210		// query.
   211		RowsAffected() (int64, error)
   212	}
   213	
   214	// Stmt is a prepared statement. It is bound to a Conn and not
   215	// used by multiple goroutines concurrently.
   216	type Stmt interface {
   217		// Close closes the statement.
   218		//
   219		// As of Go 1.1, a Stmt will not be closed if it's in use
   220		// by any queries.
   221		Close() error
   222	
   223		// NumInput returns the number of placeholder parameters.
   224		//
   225		// If NumInput returns >= 0, the sql package will sanity check
   226		// argument counts from callers and return errors to the caller
   227		// before the statement's Exec or Query methods are called.
   228		//
   229		// NumInput may also return -1, if the driver doesn't know
   230		// its number of placeholders. In that case, the sql package
   231		// will not sanity check Exec or Query argument counts.
   232		NumInput() int
   233	
   234		// Exec executes a query that doesn't return rows, such
   235		// as an INSERT or UPDATE.
   236		//
   237		// Deprecated: Drivers should implement StmtExecContext instead (or additionally).
   238		Exec(args []Value) (Result, error)
   239	
   240		// Query executes a query that may return rows, such as a
   241		// SELECT.
   242		//
   243		// Deprecated: Drivers should implement StmtQueryContext instead (or additionally).
   244		Query(args []Value) (Rows, error)
   245	}
   246	
   247	// StmtExecContext enhances the Stmt interface by providing Exec with context.
   248	type StmtExecContext interface {
   249		// ExecContext executes a query that doesn't return rows, such
   250		// as an INSERT or UPDATE.
   251		//
   252		// ExecContext must honor the context timeout and return when it is canceled.
   253		ExecContext(ctx context.Context, args []NamedValue) (Result, error)
   254	}
   255	
   256	// StmtQueryContext enhances the Stmt interface by providing Query with context.
   257	type StmtQueryContext interface {
   258		// QueryContext executes a query that may return rows, such as a
   259		// SELECT.
   260		//
   261		// QueryContext must honor the context timeout and return when it is canceled.
   262		QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
   263	}
   264	
   265	// ColumnConverter may be optionally implemented by Stmt if the
   266	// statement is aware of its own columns' types and can convert from
   267	// any type to a driver Value.
   268	type ColumnConverter interface {
   269		// ColumnConverter returns a ValueConverter for the provided
   270		// column index. If the type of a specific column isn't known
   271		// or shouldn't be handled specially, DefaultValueConverter
   272		// can be returned.
   273		ColumnConverter(idx int) ValueConverter
   274	}
   275	
   276	// Rows is an iterator over an executed query's results.
   277	type Rows interface {
   278		// Columns returns the names of the columns. The number of
   279		// columns of the result is inferred from the length of the
   280		// slice. If a particular column name isn't known, an empty
   281		// string should be returned for that entry.
   282		Columns() []string
   283	
   284		// Close closes the rows iterator.
   285		Close() error
   286	
   287		// Next is called to populate the next row of data into
   288		// the provided slice. The provided slice will be the same
   289		// size as the Columns() are wide.
   290		//
   291		// Next should return io.EOF when there are no more rows.
   292		Next(dest []Value) error
   293	}
   294	
   295	// RowsNextResultSet extends the Rows interface by providing a way to signal
   296	// the driver to advance to the next result set.
   297	type RowsNextResultSet interface {
   298		Rows
   299	
   300		// HasNextResultSet is called at the end of the current result set and
   301		// reports whether there is another result set after the current one.
   302		HasNextResultSet() bool
   303	
   304		// NextResultSet advances the driver to the next result set even
   305		// if there are remaining rows in the current result set.
   306		//
   307		// NextResultSet should return io.EOF when there are no more result sets.
   308		NextResultSet() error
   309	}
   310	
   311	// RowsColumnTypeScanType may be implemented by Rows. It should return
   312	// the value type that can be used to scan types into. For example, the database
   313	// column type "bigint" this should return "reflect.TypeOf(int64(0))".
   314	type RowsColumnTypeScanType interface {
   315		Rows
   316		ColumnTypeScanType(index int) reflect.Type
   317	}
   318	
   319	// RowsColumnTypeDatabaseTypeName may be implemented by Rows. It should return the
   320	// database system type name without the length. Type names should be uppercase.
   321	// Examples of returned types: "VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT",
   322	// "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML",
   323	// "TIMESTAMP".
   324	type RowsColumnTypeDatabaseTypeName interface {
   325		Rows
   326		ColumnTypeDatabaseTypeName(index int) string
   327	}
   328	
   329	// RowsColumnTypeLength may be implemented by Rows. It should return the length
   330	// of the column type if the column is a variable length type. If the column is
   331	// not a variable length type ok should return false.
   332	// If length is not limited other than system limits, it should return math.MaxInt64.
   333	// The following are examples of returned values for various types:
   334	//   TEXT          (math.MaxInt64, true)
   335	//   varchar(10)   (10, true)
   336	//   nvarchar(10)  (10, true)
   337	//   decimal       (0, false)
   338	//   int           (0, false)
   339	//   bytea(30)     (30, true)
   340	type RowsColumnTypeLength interface {
   341		Rows
   342		ColumnTypeLength(index int) (length int64, ok bool)
   343	}
   344	
   345	// RowsColumnTypeNullable may be implemented by Rows. The nullable value should
   346	// be true if it is known the column may be null, or false if the column is known
   347	// to be not nullable.
   348	// If the column nullability is unknown, ok should be false.
   349	type RowsColumnTypeNullable interface {
   350		Rows
   351		ColumnTypeNullable(index int) (nullable, ok bool)
   352	}
   353	
   354	// RowsColumnTypePrecisionScale may be implemented by Rows. It should return
   355	// the precision and scale for decimal types. If not applicable, ok should be false.
   356	// The following are examples of returned values for various types:
   357	//   decimal(38, 4)    (38, 4, true)
   358	//   int               (0, 0, false)
   359	//   decimal           (math.MaxInt64, math.MaxInt64, true)
   360	type RowsColumnTypePrecisionScale interface {
   361		Rows
   362		ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)
   363	}
   364	
   365	// Tx is a transaction.
   366	type Tx interface {
   367		Commit() error
   368		Rollback() error
   369	}
   370	
   371	// RowsAffected implements Result for an INSERT or UPDATE operation
   372	// which mutates a number of rows.
   373	type RowsAffected int64
   374	
   375	var _ Result = RowsAffected(0)
   376	
   377	func (RowsAffected) LastInsertId() (int64, error) {
   378		return 0, errors.New("no LastInsertId available")
   379	}
   380	
   381	func (v RowsAffected) RowsAffected() (int64, error) {
   382		return int64(v), nil
   383	}
   384	
   385	// ResultNoRows is a pre-defined Result for drivers to return when a DDL
   386	// command (such as a CREATE TABLE) succeeds. It returns an error for both
   387	// LastInsertId and RowsAffected.
   388	var ResultNoRows noRows
   389	
   390	type noRows struct{}
   391	
   392	var _ Result = noRows{}
   393	
   394	func (noRows) LastInsertId() (int64, error) {
   395		return 0, errors.New("no LastInsertId available after DDL statement")
   396	}
   397	
   398	func (noRows) RowsAffected() (int64, error) {
   399		return 0, errors.New("no RowsAffected available after DDL statement")
   400	}
   401	

View as plain text