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. 9package driver 10 11import ( 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. 32type Value interface{} 33 34// NamedValue holds both the value name and value. 35type 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. 55type 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. 74type 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. 89type 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. 114var 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. 125var 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. 134type 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. 147type 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. 161type 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. 174type 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. 188type 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. 196type 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. 217type 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. 228type IsolationLevel int 229 230// TxOptions holds the transaction options. 231// 232// This type should be considered identical to sql.TxOptions. 233type TxOptions struct { 234 Isolation IsolationLevel 235 ReadOnly bool 236} 237 238// ConnBeginTx enhances the Conn interface with context and TxOptions. 239type 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. 257type 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. 268type 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. 281type 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. 313type 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. 322type 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. 334var 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. 351type 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. 363type 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. 372type 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. 396type 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))". 413type 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". 423type 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) 439type 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. 448type 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) 459type RowsColumnTypePrecisionScale interface { 460 Rows 461 ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool) 462} 463 464// Tx is a transaction. 465type 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. 472type RowsAffected int64 473 474var _ Result = RowsAffected(0) 475 476func (RowsAffected) LastInsertId() (int64, error) { 477 return 0, errors.New("LastInsertId is not supported by this driver") 478} 479 480func (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. 487var ResultNoRows noRows 488 489type noRows struct{} 490 491var _ Result = noRows{} 492 493func (noRows) LastInsertId() (int64, error) { 494 return 0, errors.New("no LastInsertId available after DDL statement") 495} 496 497func (noRows) RowsAffected() (int64, error) { 498 return 0, errors.New("no RowsAffected available after DDL statement") 499} 500