...
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 "errors"
    12	
    13	// Value is a value that drivers must be able to handle.
    14	// It is either nil or an instance of one of these types:
    15	//
    16	//   int64
    17	//   float64
    18	//   bool
    19	//   []byte
    20	//   string
    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 sql 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	// Queryer is an optional interface that may be implemented by a Conn.
    69	//
    70	// If a Conn does not implement Queryer, the sql package's DB.Query will
    71	// first prepare a query, execute the statement, and then close the
    72	// statement.
    73	//
    74	// Query may return ErrSkip.
    75	type Queryer interface {
    76		Query(query string, args []Value) (Rows, error)
    77	}
    78	
    79	// Conn is a connection to a database. It is not used concurrently
    80	// by multiple goroutines.
    81	//
    82	// Conn is assumed to be stateful.
    83	type Conn interface {
    84		// Prepare returns a prepared statement, bound to this connection.
    85		Prepare(query string) (Stmt, error)
    86	
    87		// Close invalidates and potentially stops any current
    88		// prepared statements and transactions, marking this
    89		// connection as no longer in use.
    90		//
    91		// Because the sql package maintains a free pool of
    92		// connections and only calls Close when there's a surplus of
    93		// idle connections, it shouldn't be necessary for drivers to
    94		// do their own connection caching.
    95		Close() error
    96	
    97		// Begin starts and returns a new transaction.
    98		Begin() (Tx, error)
    99	}
   100	
   101	// Result is the result of a query execution.
   102	type Result interface {
   103		// LastInsertId returns the database's auto-generated ID
   104		// after, for example, an INSERT into a table with primary
   105		// key.
   106		LastInsertId() (int64, error)
   107	
   108		// RowsAffected returns the number of rows affected by the
   109		// query.
   110		RowsAffected() (int64, error)
   111	}
   112	
   113	// Stmt is a prepared statement. It is bound to a Conn and not
   114	// used by multiple goroutines concurrently.
   115	type Stmt interface {
   116		// Close closes the statement.
   117		//
   118		// As of Go 1.1, a Stmt will not be closed if it's in use
   119		// by any queries.
   120		Close() error
   121	
   122		// NumInput returns the number of placeholder parameters.
   123		//
   124		// If NumInput returns >= 0, the sql package will sanity check
   125		// argument counts from callers and return errors to the caller
   126		// before the statement's Exec or Query methods are called.
   127		//
   128		// NumInput may also return -1, if the driver doesn't know
   129		// its number of placeholders. In that case, the sql package
   130		// will not sanity check Exec or Query argument counts.
   131		NumInput() int
   132	
   133		// Exec executes a query that doesn't return rows, such
   134		// as an INSERT or UPDATE.
   135		Exec(args []Value) (Result, error)
   136	
   137		// Query executes a query that may return rows, such as a
   138		// SELECT.
   139		Query(args []Value) (Rows, error)
   140	}
   141	
   142	// ColumnConverter may be optionally implemented by Stmt if the
   143	// statement is aware of its own columns' types and can convert from
   144	// any type to a driver Value.
   145	type ColumnConverter interface {
   146		// ColumnConverter returns a ValueConverter for the provided
   147		// column index. If the type of a specific column isn't known
   148		// or shouldn't be handled specially, DefaultValueConverter
   149		// can be returned.
   150		ColumnConverter(idx int) ValueConverter
   151	}
   152	
   153	// Rows is an iterator over an executed query's results.
   154	type Rows interface {
   155		// Columns returns the names of the columns. The number of
   156		// columns of the result is inferred from the length of the
   157		// slice. If a particular column name isn't known, an empty
   158		// string should be returned for that entry.
   159		Columns() []string
   160	
   161		// Close closes the rows iterator.
   162		Close() error
   163	
   164		// Next is called to populate the next row of data into
   165		// the provided slice. The provided slice will be the same
   166		// size as the Columns() are wide.
   167		//
   168		// Next should return io.EOF when there are no more rows.
   169		Next(dest []Value) error
   170	}
   171	
   172	// Tx is a transaction.
   173	type Tx interface {
   174		Commit() error
   175		Rollback() error
   176	}
   177	
   178	// RowsAffected implements Result for an INSERT or UPDATE operation
   179	// which mutates a number of rows.
   180	type RowsAffected int64
   181	
   182	var _ Result = RowsAffected(0)
   183	
   184	func (RowsAffected) LastInsertId() (int64, error) {
   185		return 0, errors.New("no LastInsertId available")
   186	}
   187	
   188	func (v RowsAffected) RowsAffected() (int64, error) {
   189		return int64(v), nil
   190	}
   191	
   192	// ResultNoRows is a pre-defined Result for drivers to return when a DDL
   193	// command (such as a CREATE TABLE) succeeds. It returns an error for both
   194	// LastInsertId and RowsAffected.
   195	var ResultNoRows noRows
   196	
   197	type noRows struct{}
   198	
   199	var _ Result = noRows{}
   200	
   201	func (noRows) LastInsertId() (int64, error) {
   202		return 0, errors.New("no LastInsertId available after DDL statement")
   203	}
   204	
   205	func (noRows) RowsAffected() (int64, error) {
   206		return 0, errors.New("no RowsAffected available after DDL statement")
   207	}
   208	

View as plain text