src/pkg/database/sql/driver/driver.go - The Go Programming Language

Golang

Source file src/pkg/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 "errors"
    12	
    13	// A driver Value is a value that drivers must be able to handle.
    14	// A Value is either nil or an instance of one of these types:
    15	//
    16	//   int64
    17	//   float64
    18	//   bool
    19	//   []byte
    20	//   string   [*] everywhere except from Rows.Next.
    21	//   time.Time
    22	type Value interface{}
    23	
    24	// Driver is the interface that must be implemented by a database
    25	// driver.
    26	type Driver interface {
    27		// Open returns a new connection to the database.
    28		// The name is a string in a driver-specific format.
    29		//
    30		// Open may return a cached connection (one previously
    31		// closed), but doing so is unnecessary; the sql package
    32		// maintains a pool of idle connections for efficient re-use.
    33		//
    34		// The returned connection is only used by one goroutine at a
    35		// time.
    36		Open(name string) (Conn, error)
    37	}
    38	
    39	// ErrSkip may be returned by some optional interfaces' methods to
    40	// indicate at runtime that the fast path is unavailable and the sql
    41	// package should continue as if the optional interface was not
    42	// implemented. ErrSkip is only supported where explicitly
    43	// documented.
    44	var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")
    45	
    46	// ErrBadConn should be returned by a driver to signal to the sql
    47	// package that a driver.Conn is in a bad state (such as the server
    48	// having earlier closed the connection) and the sql package should
    49	// retry on a new connection.
    50	//
    51	// To prevent duplicate operations, ErrBadConn should NOT be returned
    52	// if there's a possibility that the database server might have
    53	// performed the operation. Even if the server sends back an error,
    54	// you shouldn't return ErrBadConn.
    55	var ErrBadConn = errors.New("driver: bad connection")
    56	
    57	// Execer is an optional interface that may be implemented by a Conn.
    58	//
    59	// If a Conn does not implement Execer, the db package's DB.Exec will
    60	// first prepare a query, execute the statement, and then close the
    61	// statement.
    62	//
    63	// Exec may return ErrSkip.
    64	type Execer interface {
    65		Exec(query string, args []Value) (Result, error)
    66	}
    67	
    68	// Conn is a connection to a database. It is not used concurrently
    69	// by multiple goroutines.
    70	//
    71	// Conn is assumed to be stateful.
    72	type Conn interface {
    73		// Prepare returns a prepared statement, bound to this connection.
    74		Prepare(query string) (Stmt, error)
    75	
    76		// Close invalidates and potentially stops any current
    77		// prepared statements and transactions, marking this
    78		// connection as no longer in use.
    79		//
    80		// Because the sql package maintains a free pool of
    81		// connections and only calls Close when there's a surplus of
    82		// idle connections, it shouldn't be necessary for drivers to
    83		// do their own connection caching.
    84		Close() error
    85	
    86		// Begin starts and returns a new transaction.
    87		Begin() (Tx, error)
    88	}
    89	
    90	// Result is the result of a query execution.
    91	type Result interface {
    92		// LastInsertId returns the database's auto-generated ID
    93		// after, for example, an INSERT into a table with primary
    94		// key.
    95		LastInsertId() (int64, error)
    96	
    97		// RowsAffected returns the number of rows affected by the
    98		// query.
    99		RowsAffected() (int64, error)
   100	}
   101	
   102	// Stmt is a prepared statement. It is bound to a Conn and not
   103	// used by multiple goroutines concurrently.
   104	type Stmt interface {
   105		// Close closes the statement.
   106		//
   107		// Closing a statement should not interrupt any outstanding
   108		// query created from that statement. That is, the following
   109		// order of operations is valid:
   110		//
   111		//  * create a driver statement
   112		//  * call Query on statement, returning Rows
   113		//  * close the statement
   114		//  * read from Rows
   115		//
   116		// If closing a statement invalidates currently-running
   117		// queries, the final step above will incorrectly fail.
   118		//
   119		// TODO(bradfitz): possibly remove the restriction above, if
   120		// enough driver authors object and find it complicates their
   121		// code too much. The sql package could be smarter about
   122		// refcounting the statement and closing it at the appropriate
   123		// time.
   124		Close() error
   125	
   126		// NumInput returns the number of placeholder parameters.
   127		//
   128		// If NumInput returns >= 0, the sql package will sanity check
   129		// argument counts from callers and return errors to the caller
   130		// before the statement's Exec or Query methods are called.
   131		//
   132		// NumInput may also return -1, if the driver doesn't know
   133		// its number of placeholders. In that case, the sql package
   134		// will not sanity check Exec or Query argument counts.
   135		NumInput() int
   136	
   137		// Exec executes a query that doesn't return rows, such
   138		// as an INSERT or UPDATE.
   139		Exec(args []Value) (Result, error)
   140	
   141		// Exec executes a query that may return rows, such as a
   142		// SELECT.
   143		Query(args []Value) (Rows, error)
   144	}
   145	
   146	// ColumnConverter may be optionally implemented by Stmt if the
   147	// the statement is aware of its own columns' types and can
   148	// convert from any type to a driver Value.
   149	type ColumnConverter interface {
   150		// ColumnConverter returns a ValueConverter for the provided
   151		// column index.  If the type of a specific column isn't known
   152		// or shouldn't be handled specially, DefaultValueConverter
   153		// can be returned.
   154		ColumnConverter(idx int) ValueConverter
   155	}
   156	
   157	// Rows is an iterator over an executed query's results.
   158	type Rows interface {
   159		// Columns returns the names of the columns. The number of
   160		// columns of the result is inferred from the length of the
   161		// slice.  If a particular column name isn't known, an empty
   162		// string should be returned for that entry.
   163		Columns() []string
   164	
   165		// Close closes the rows iterator.
   166		Close() error
   167	
   168		// Next is called to populate the next row of data into
   169		// the provided slice. The provided slice will be the same
   170		// size as the Columns() are wide.
   171		//
   172		// The dest slice may be populated only with
   173		// a driver Value type, but excluding string.
   174		// All string values must be converted to []byte.
   175		//
   176		// Next should return io.EOF when there are no more rows.
   177		Next(dest []Value) error
   178	}
   179	
   180	// Tx is a transaction.
   181	type Tx interface {
   182		Commit() error
   183		Rollback() error
   184	}
   185	
   186	// RowsAffected implements Result for an INSERT or UPDATE operation
   187	// which mutates a number of rows.
   188	type RowsAffected int64
   189	
   190	var _ Result = RowsAffected(0)
   191	
   192	func (RowsAffected) LastInsertId() (int64, error) {
   193		return 0, errors.New("no LastInsertId available")
   194	}
   195	
   196	func (v RowsAffected) RowsAffected() (int64, error) {
   197		return int64(v), nil
   198	}
   199	
   200	// ResultNoRows is a pre-defined Result for drivers to return when a DDL
   201	// command (such as a CREATE TABLE) succeeds. It returns an error for both
   202	// LastInsertId and RowsAffected.
   203	var ResultNoRows noRows
   204	
   205	type noRows struct{}
   206	
   207	var _ Result = noRows{}
   208	
   209	func (noRows) LastInsertId() (int64, error) {
   210		return 0, errors.New("no LastInsertId available after DDL statement")
   211	}
   212	
   213	func (noRows) RowsAffected() (int64, error) {
   214		return 0, errors.New("no RowsAffected available after DDL statement")
   215	}