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 27type Value interface{} 28 29// NamedValue holds both the value name and value. 30type NamedValue struct { 31 // If the Name is not empty it should be used for the parameter identifier and 32 // not the ordinal position. 33 // 34 // Name will not have a symbol prefix. 35 Name string 36 37 // Ordinal position of the parameter starting from one and is always set. 38 Ordinal int 39 40 // Value is the parameter value. 41 Value Value 42} 43 44// Driver is the interface that must be implemented by a database 45// driver. 46// 47// Database drivers may implement DriverContext for access 48// to contexts and to parse the name only once for a pool of connections, 49// instead of once per connection. 50type Driver interface { 51 // Open returns a new connection to the database. 52 // The name is a string in a driver-specific format. 53 // 54 // Open may return a cached connection (one previously 55 // closed), but doing so is unnecessary; the sql package 56 // maintains a pool of idle connections for efficient re-use. 57 // 58 // The returned connection is only used by one goroutine at a 59 // time. 60 Open(name string) (Conn, error) 61} 62 63// If a Driver implements DriverContext, then sql.DB will call 64// OpenConnector to obtain a Connector and then invoke 65// that Connector's Conn method to obtain each needed connection, 66// instead of invoking the Driver's Open method for each connection. 67// The two-step sequence allows drivers to parse the name just once 68// and also provides access to per-Conn contexts. 69type DriverContext interface { 70 // OpenConnector must parse the name in the same format that Driver.Open 71 // parses the name parameter. 72 OpenConnector(name string) (Connector, error) 73} 74 75// A Connector represents a driver in a fixed configuration 76// and can create any number of equivalent Conns for use 77// by multiple goroutines. 78// 79// A Connector can be passed to sql.OpenDB, to allow drivers 80// to implement their own sql.DB constructors, or returned by 81// DriverContext's OpenConnector method, to allow drivers 82// access to context and to avoid repeated parsing of driver 83// configuration. 84type Connector interface { 85 // Connect returns a connection to the database. 86 // Connect may return a cached connection (one previously 87 // closed), but doing so is unnecessary; the sql package 88 // maintains a pool of idle connections for efficient re-use. 89 // 90 // The provided context.Context is for dialing purposes only 91 // (see net.DialContext) and should not be stored or used for 92 // other purposes. 93 // 94 // The returned connection is only used by one goroutine at a 95 // time. 96 Connect(context.Context) (Conn, error) 97 98 // Driver returns the underlying Driver of the Connector, 99 // mainly to maintain compatibility with the Driver method 100 // on sql.DB. 101 Driver() Driver 102} 103 104// ErrSkip may be returned by some optional interfaces' methods to 105// indicate at runtime that the fast path is unavailable and the sql 106// package should continue as if the optional interface was not 107// implemented. ErrSkip is only supported where explicitly 108// documented. 109var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented") 110 111// ErrBadConn should be returned by a driver to signal to the sql 112// package that a driver.Conn is in a bad state (such as the server 113// having earlier closed the connection) and the sql package should 114// retry on a new connection. 115// 116// To prevent duplicate operations, ErrBadConn should NOT be returned 117// if there's a possibility that the database server might have 118// performed the operation. Even if the server sends back an error, 119// you shouldn't return ErrBadConn. 120var ErrBadConn = errors.New("driver: bad connection") 121 122// Pinger is an optional interface that may be implemented by a Conn. 123// 124// If a Conn does not implement Pinger, the sql package's DB.Ping and 125// DB.PingContext will check if there is at least one Conn available. 126// 127// If Conn.Ping returns ErrBadConn, DB.Ping and DB.PingContext will remove 128// the Conn from pool. 129type Pinger interface { 130 Ping(ctx context.Context) error 131} 132 133// Execer is an optional interface that may be implemented by a Conn. 134// 135// If a Conn implements neither ExecerContext nor Execer Execer, 136// the sql package's DB.Exec will first prepare a query, execute the statement, 137// and then close the statement. 138// 139// Exec may return ErrSkip. 140// 141// Deprecated: Drivers should implement ExecerContext instead. 142type Execer interface { 143 Exec(query string, args []Value) (Result, error) 144} 145 146// ExecerContext is an optional interface that may be implemented by a Conn. 147// 148// If a Conn does not implement ExecerContext, the sql package's DB.Exec 149// will fall back to Execer; if the Conn does not implement Execer either, 150// DB.Exec will first prepare a query, execute the statement, and then 151// close the statement. 152// 153// ExecerContext may return ErrSkip. 154// 155// ExecerContext must honor the context timeout and return when the context is canceled. 156type ExecerContext interface { 157 ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error) 158} 159 160// Queryer is an optional interface that may be implemented by a Conn. 161// 162// If a Conn implements neither QueryerContext nor Queryer, 163// the sql package's DB.Query will first prepare a query, execute the statement, 164// and then close the statement. 165// 166// Query may return ErrSkip. 167// 168// Deprecated: Drivers should implement QueryerContext instead. 169type Queryer interface { 170 Query(query string, args []Value) (Rows, error) 171} 172 173// QueryerContext is an optional interface that may be implemented by a Conn. 174// 175// If a Conn does not implement QueryerContext, the sql package's DB.Query 176// will fall back to Queryer; if the Conn does not implement Queryer either, 177// DB.Query will first prepare a query, execute the statement, and then 178// close the statement. 179// 180// QueryerContext may return ErrSkip. 181// 182// QueryerContext must honor the context timeout and return when the context is canceled. 183type QueryerContext interface { 184 QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error) 185} 186 187// Conn is a connection to a database. It is not used concurrently 188// by multiple goroutines. 189// 190// Conn is assumed to be stateful. 191type Conn interface { 192 // Prepare returns a prepared statement, bound to this connection. 193 Prepare(query string) (Stmt, error) 194 195 // Close invalidates and potentially stops any current 196 // prepared statements and transactions, marking this 197 // connection as no longer in use. 198 // 199 // Because the sql package maintains a free pool of 200 // connections and only calls Close when there's a surplus of 201 // idle connections, it shouldn't be necessary for drivers to 202 // do their own connection caching. 203 Close() error 204 205 // Begin starts and returns a new transaction. 206 // 207 // Deprecated: Drivers should implement ConnBeginTx instead (or additionally). 208 Begin() (Tx, error) 209} 210 211// ConnPrepareContext enhances the Conn interface with context. 212type ConnPrepareContext interface { 213 // PrepareContext returns a prepared statement, bound to this connection. 214 // context is for the preparation of the statement, 215 // it must not store the context within the statement itself. 216 PrepareContext(ctx context.Context, query string) (Stmt, error) 217} 218 219// IsolationLevel is the transaction isolation level stored in TxOptions. 220// 221// This type should be considered identical to sql.IsolationLevel along 222// with any values defined on it. 223type IsolationLevel int 224 225// TxOptions holds the transaction options. 226// 227// This type should be considered identical to sql.TxOptions. 228type TxOptions struct { 229 Isolation IsolationLevel 230 ReadOnly bool 231} 232 233// ConnBeginTx enhances the Conn interface with context and TxOptions. 234type ConnBeginTx interface { 235 // BeginTx starts and returns a new transaction. 236 // If the context is canceled by the user the sql package will 237 // call Tx.Rollback before discarding and closing the connection. 238 // 239 // This must check opts.Isolation to determine if there is a set 240 // isolation level. If the driver does not support a non-default 241 // level and one is set or if there is a non-default isolation level 242 // that is not supported, an error must be returned. 243 // 244 // This must also check opts.ReadOnly to determine if the read-only 245 // value is true to either set the read-only transaction property if supported 246 // or return an error if it is not supported. 247 BeginTx(ctx context.Context, opts TxOptions) (Tx, error) 248} 249 250// SessionResetter may be implemented by Conn to allow drivers to reset the 251// session state associated with the connection and to signal a bad connection. 252type SessionResetter interface { 253 // ResetSession is called while a connection is in the connection 254 // pool. No queries will run on this connection until this method returns. 255 // 256 // If the connection is bad this should return driver.ErrBadConn to prevent 257 // the connection from being returned to the connection pool. Any other 258 // error will be discarded. 259 ResetSession(ctx context.Context) error 260} 261 262// Result is the result of a query execution. 263type Result interface { 264 // LastInsertId returns the database's auto-generated ID 265 // after, for example, an INSERT into a table with primary 266 // key. 267 LastInsertId() (int64, error) 268 269 // RowsAffected returns the number of rows affected by the 270 // query. 271 RowsAffected() (int64, error) 272} 273 274// Stmt is a prepared statement. It is bound to a Conn and not 275// used by multiple goroutines concurrently. 276type Stmt interface { 277 // Close closes the statement. 278 // 279 // As of Go 1.1, a Stmt will not be closed if it's in use 280 // by any queries. 281 Close() error 282 283 // NumInput returns the number of placeholder parameters. 284 // 285 // If NumInput returns >= 0, the sql package will sanity check 286 // argument counts from callers and return errors to the caller 287 // before the statement's Exec or Query methods are called. 288 // 289 // NumInput may also return -1, if the driver doesn't know 290 // its number of placeholders. In that case, the sql package 291 // will not sanity check Exec or Query argument counts. 292 NumInput() int 293 294 // Exec executes a query that doesn't return rows, such 295 // as an INSERT or UPDATE. 296 // 297 // Deprecated: Drivers should implement StmtExecContext instead (or additionally). 298 Exec(args []Value) (Result, error) 299 300 // Query executes a query that may return rows, such as a 301 // SELECT. 302 // 303 // Deprecated: Drivers should implement StmtQueryContext instead (or additionally). 304 Query(args []Value) (Rows, error) 305} 306 307// StmtExecContext enhances the Stmt interface by providing Exec with context. 308type StmtExecContext interface { 309 // ExecContext executes a query that doesn't return rows, such 310 // as an INSERT or UPDATE. 311 // 312 // ExecContext must honor the context timeout and return when it is canceled. 313 ExecContext(ctx context.Context, args []NamedValue) (Result, error) 314} 315 316// StmtQueryContext enhances the Stmt interface by providing Query with context. 317type StmtQueryContext interface { 318 // QueryContext executes a query that may return rows, such as a 319 // SELECT. 320 // 321 // QueryContext must honor the context timeout and return when it is canceled. 322 QueryContext(ctx context.Context, args []NamedValue) (Rows, error) 323} 324 325// ErrRemoveArgument may be returned from NamedValueChecker to instruct the 326// sql package to not pass the argument to the driver query interface. 327// Return when accepting query specific options or structures that aren't 328// SQL query arguments. 329var ErrRemoveArgument = errors.New("driver: remove argument from query") 330 331// NamedValueChecker may be optionally implemented by Conn or Stmt. It provides 332// the driver more control to handle Go and database types beyond the default 333// Values types allowed. 334// 335// The sql package checks for value checkers in the following order, 336// stopping at the first found match: Stmt.NamedValueChecker, Conn.NamedValueChecker, 337// Stmt.ColumnConverter, DefaultParameterConverter. 338// 339// If CheckNamedValue returns ErrRemoveArgument, the NamedValue will not be included in 340// the final query arguments. This may be used to pass special options to 341// the query itself. 342// 343// If ErrSkip is returned the column converter error checking 344// path is used for the argument. Drivers may wish to return ErrSkip after 345// they have exhausted their own special cases. 346type NamedValueChecker interface { 347 // CheckNamedValue is called before passing arguments to the driver 348 // and is called in place of any ColumnConverter. CheckNamedValue must do type 349 // validation and conversion as appropriate for the driver. 350 CheckNamedValue(*NamedValue) error 351} 352 353// ColumnConverter may be optionally implemented by Stmt if the 354// statement is aware of its own columns' types and can convert from 355// any type to a driver Value. 356// 357// Deprecated: Drivers should implement NamedValueChecker. 358type ColumnConverter interface { 359 // ColumnConverter returns a ValueConverter for the provided 360 // column index. If the type of a specific column isn't known 361 // or shouldn't be handled specially, DefaultValueConverter 362 // can be returned. 363 ColumnConverter(idx int) ValueConverter 364} 365 366// Rows is an iterator over an executed query's results. 367type Rows interface { 368 // Columns returns the names of the columns. The number of 369 // columns of the result is inferred from the length of the 370 // slice. If a particular column name isn't known, an empty 371 // string should be returned for that entry. 372 Columns() []string 373 374 // Close closes the rows iterator. 375 Close() error 376 377 // Next is called to populate the next row of data into 378 // the provided slice. The provided slice will be the same 379 // size as the Columns() are wide. 380 // 381 // Next should return io.EOF when there are no more rows. 382 // 383 // The dest should not be written to outside of Next. Care 384 // should be taken when closing Rows not to modify 385 // a buffer held in dest. 386 Next(dest []Value) error 387} 388 389// RowsNextResultSet extends the Rows interface by providing a way to signal 390// the driver to advance to the next result set. 391type RowsNextResultSet interface { 392 Rows 393 394 // HasNextResultSet is called at the end of the current result set and 395 // reports whether there is another result set after the current one. 396 HasNextResultSet() bool 397 398 // NextResultSet advances the driver to the next result set even 399 // if there are remaining rows in the current result set. 400 // 401 // NextResultSet should return io.EOF when there are no more result sets. 402 NextResultSet() error 403} 404 405// RowsColumnTypeScanType may be implemented by Rows. It should return 406// the value type that can be used to scan types into. For example, the database 407// column type "bigint" this should return "reflect.TypeOf(int64(0))". 408type RowsColumnTypeScanType interface { 409 Rows 410 ColumnTypeScanType(index int) reflect.Type 411} 412 413// RowsColumnTypeDatabaseTypeName may be implemented by Rows. It should return the 414// database system type name without the length. Type names should be uppercase. 415// Examples of returned types: "VARCHAR", "NVARCHAR", "VARCHAR2", "CHAR", "TEXT", 416// "DECIMAL", "SMALLINT", "INT", "BIGINT", "BOOL", "[]BIGINT", "JSONB", "XML", 417// "TIMESTAMP". 418type RowsColumnTypeDatabaseTypeName interface { 419 Rows 420 ColumnTypeDatabaseTypeName(index int) string 421} 422 423// RowsColumnTypeLength may be implemented by Rows. It should return the length 424// of the column type if the column is a variable length type. If the column is 425// not a variable length type ok should return false. 426// If length is not limited other than system limits, it should return math.MaxInt64. 427// The following are examples of returned values for various types: 428// TEXT (math.MaxInt64, true) 429// varchar(10) (10, true) 430// nvarchar(10) (10, true) 431// decimal (0, false) 432// int (0, false) 433// bytea(30) (30, true) 434type RowsColumnTypeLength interface { 435 Rows 436 ColumnTypeLength(index int) (length int64, ok bool) 437} 438 439// RowsColumnTypeNullable may be implemented by Rows. The nullable value should 440// be true if it is known the column may be null, or false if the column is known 441// to be not nullable. 442// If the column nullability is unknown, ok should be false. 443type RowsColumnTypeNullable interface { 444 Rows 445 ColumnTypeNullable(index int) (nullable, ok bool) 446} 447 448// RowsColumnTypePrecisionScale may be implemented by Rows. It should return 449// the precision and scale for decimal types. If not applicable, ok should be false. 450// The following are examples of returned values for various types: 451// decimal(38, 4) (38, 4, true) 452// int (0, 0, false) 453// decimal (math.MaxInt64, math.MaxInt64, true) 454type RowsColumnTypePrecisionScale interface { 455 Rows 456 ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool) 457} 458 459// Tx is a transaction. 460type Tx interface { 461 Commit() error 462 Rollback() error 463} 464 465// RowsAffected implements Result for an INSERT or UPDATE operation 466// which mutates a number of rows. 467type RowsAffected int64 468 469var _ Result = RowsAffected(0) 470 471func (RowsAffected) LastInsertId() (int64, error) { 472 return 0, errors.New("no LastInsertId available") 473} 474 475func (v RowsAffected) RowsAffected() (int64, error) { 476 return int64(v), nil 477} 478 479// ResultNoRows is a pre-defined Result for drivers to return when a DDL 480// command (such as a CREATE TABLE) succeeds. It returns an error for both 481// LastInsertId and RowsAffected. 482var ResultNoRows noRows 483 484type noRows struct{} 485 486var _ Result = noRows{} 487 488func (noRows) LastInsertId() (int64, error) { 489 return 0, errors.New("no LastInsertId available after DDL statement") 490} 491 492func (noRows) RowsAffected() (int64, error) { 493 return 0, errors.New("no RowsAffected available after DDL statement") 494} 495