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.
5 // Package driver defines interfaces to be implemented by database
6 // drivers as used by package sql.
8 // Most code should use package sql.
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:
20 // string [*] everywhere except from Rows.Next.
22 type Value
interface{}
24 // Driver is the interface that must be implemented by a database
26 type Driver
interface {
27 // Open returns a new connection to the database.
28 // The name is a string in a driver-specific format.
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.
34 // The returned connection is only used by one goroutine at a
36 Open(name
string) (Conn
, error
)
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
44 var ErrSkip
= errors
.New("driver: skip fast-path; continue as if unimplemented")
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.
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")
57 // Execer is an optional interface that may be implemented by a Conn.
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
63 // Exec may return ErrSkip.
64 type Execer
interface {
65 Exec(query
string, args
[]Value
) (Result
, error
)
68 // Queryer is an optional interface that may be implemented by a Conn.
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
74 // Query may return ErrSkip.
75 type Queryer
interface {
76 Query(query
string, args
[]Value
) (Rows
, error
)
79 // Conn is a connection to a database. It is not used concurrently
80 // by multiple goroutines.
82 // Conn is assumed to be stateful.
84 // Prepare returns a prepared statement, bound to this connection.
85 Prepare(query
string) (Stmt
, error
)
87 // Close invalidates and potentially stops any current
88 // prepared statements and transactions, marking this
89 // connection as no longer in use.
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.
97 // Begin starts and returns a new transaction.
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
106 LastInsertId() (int64, error
)
108 // RowsAffected returns the number of rows affected by the
110 RowsAffected() (int64, error
)
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.
118 // As of Go 1.1, a Stmt will not be closed if it's in use
122 // NumInput returns the number of placeholder parameters.
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.
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.
133 // Exec executes a query that doesn't return rows, such
134 // as an INSERT or UPDATE.
135 Exec(args
[]Value
) (Result
, error
)
137 // Query executes a query that may return rows, such as a
139 Query(args
[]Value
) (Rows
, error
)
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
150 ColumnConverter(idx
int) ValueConverter
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.
161 // Close closes the rows iterator.
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.
168 // The dest slice may be populated only with
169 // a driver Value type, but excluding string.
170 // All string values must be converted to []byte.
172 // Next should return io.EOF when there are no more rows.
173 Next(dest
[]Value
) error
176 // Tx is a transaction.
182 // RowsAffected implements Result for an INSERT or UPDATE operation
183 // which mutates a number of rows.
184 type RowsAffected
int64
186 var _ Result
= RowsAffected(0)
188 func (RowsAffected
) LastInsertId() (int64, error
) {
189 return 0, errors
.New("no LastInsertId available")
192 func (v RowsAffected
) RowsAffected() (int64, error
) {
196 // ResultNoRows is a pre-defined Result for drivers to return when a DDL
197 // command (such as a CREATE TABLE) succeeds. It returns an error for both
198 // LastInsertId and RowsAffected.
199 var ResultNoRows noRows
203 var _ Result
= noRows
{}
205 func (noRows
) LastInsertId() (int64, error
) {
206 return 0, errors
.New("no LastInsertId available after DDL statement")
209 func (noRows
) RowsAffected() (int64, error
) {
210 return 0, errors
.New("no RowsAffected available after DDL statement")