Documentation
¶
Overview ¶
Package sql provides a generic interface around SQL (or SQL-like) databases.
The sql package must be used in conjunction with a database driver. See http://golang.org/s/sqldrivers for a list of drivers.
Index ¶
- Variables
- func Register(name string, driver driver.Driver)
- type DB
- func (db *DB) Begin() (*Tx, error)
- func (db *DB) Close() error
- func (db *DB) Driver() driver.Driver
- func (db *DB) Exec(query string, args ...interface{}) (Result, error)
- func (db *DB) Ping() error
- func (db *DB) Prepare(query string) (*Stmt, error)
- func (db *DB) Query(query string, args ...interface{}) (*Rows, error)
- func (db *DB) QueryRow(query string, args ...interface{}) *Row
- func (db *DB) SetMaxIdleConns(n int)
- type NullBool
- type NullFloat64
- type NullInt64
- type NullString
- type RawBytes
- type Result
- type Row
- type Rows
- type Scanner
- type Stmt
- type Tx
- func (tx *Tx) Commit() error
- func (tx *Tx) Exec(query string, args ...interface{}) (Result, error)
- func (tx *Tx) Prepare(query string) (*Stmt, error)
- func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error)
- func (tx *Tx) QueryRow(query string, args ...interface{}) *Row
- func (tx *Tx) Rollback() error
- func (tx *Tx) Stmt(stmt *Stmt) *Stmt
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoRows = errors.New("sql: no rows in result set")
ErrNoRows is returned by Scan when QueryRow doesn't return a row. In such a case, QueryRow returns a placeholder *Row value that defers this error until a Scan.
var ErrTxDone = errors.New("sql: Transaction has already been committed or rolled back")
Functions ¶
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is a database handle. It's safe for concurrent use by multiple goroutines.
The sql package creates and frees connections automatically; it also maintains a free pool of idle connections. If the database has a concept of per-connection state, such state can only be reliably observed within a transaction. Once DB.Begin is called, the returned Tx is bound to a single connection. Once Commit or Rollback is called on the transaction, that transaction's connection is returned to DB's idle connection pool. The pool size can be controlled with SetMaxIdleConns.
func Open ¶
Open opens a database specified by its database driver name and a driver-specific data source name, usually consisting of at least a database name and connection information.
Most users will open a database via a driver-specific connection helper function that returns a *DB. No database drivers are included in the Go standard library. See http://golang.org/s/sqldrivers for a list of third-party drivers.
Open may just validate its arguments without creating a connection to the database. To verify that the data source name is valid, call Ping.
func (*DB) Exec ¶
Exec executes a query without returning any rows. The args are for any placeholder parameters in the query.
func (*DB) Ping ¶ added in go1.1
Ping verifies a connection to the database is still alive, establishing a connection if necessary.
func (*DB) Prepare ¶
Prepare creates a prepared statement for later queries or executions. Multiple queries or executions may be run concurrently from the returned statement.
func (*DB) Query ¶
Query executes a query that returns rows, typically a SELECT. The args are for any placeholder parameters in the query.
Example ¶
package main
import (
"database/sql"
"fmt"
"log"
)
var db *sql.DB
func main() {
age := 27
rows, err := db.Query("SELECT name FROM users WHERE age=?", age)
if err != nil {
log.Fatal(err)
}
for rows.Next() {
var name string
if err := rows.Scan(&name); err != nil {
log.Fatal(err)
}
fmt.Printf("%s is %d\n", name, age)
}
if err := rows.Err(); err != nil {
log.Fatal(err)
}
}
Output:
func (*DB) QueryRow ¶
QueryRow executes a query that is expected to return at most one row. QueryRow always return a non-nil value. Errors are deferred until Row's Scan method is called.
Example ¶
package main
import (
"database/sql"
"fmt"
"log"
)
var db *sql.DB
func main() {
id := 123
var username string
err := db.QueryRow("SELECT username FROM users WHERE id=?", id).Scan(&username)
switch {
case err == sql.ErrNoRows:
log.Printf("No user with that ID.")
case err != nil:
log.Fatal(err)
default:
fmt.Printf("Username is %s\n", username)
}
}
Output:
func (*DB) SetMaxIdleConns ¶ added in go1.1
SetMaxIdleConns sets the maximum number of connections in the idle connection pool.
If n <= 0, no idle connections are retained.
type NullBool ¶
NullBool represents a bool that may be null. NullBool implements the Scanner interface so it can be used as a scan destination, similar to NullString.
type NullFloat64 ¶
NullFloat64 represents a float64 that may be null. NullFloat64 implements the Scanner interface so it can be used as a scan destination, similar to NullString.
func (*NullFloat64) Scan ¶
func (n *NullFloat64) Scan(value interface{}) error
Scan implements the Scanner interface.
type NullInt64 ¶
NullInt64 represents an int64 that may be null. NullInt64 implements the Scanner interface so it can be used as a scan destination, similar to NullString.
type NullString ¶
NullString represents a string that may be null. NullString implements the Scanner interface so it can be used as a scan destination:
var s NullString
err := db.QueryRow("SELECT name FROM foo WHERE id=?", id).Scan(&s)
...
if s.Valid {
// use s.String
} else {
// NULL value
}
func (*NullString) Scan ¶
func (ns *NullString) Scan(value interface{}) error
Scan implements the Scanner interface.
type RawBytes ¶
type RawBytes []byte
RawBytes is a byte slice that holds a reference to memory owned by the database itself. After a Scan into a RawBytes, the slice is only valid until the next call to Next, Scan, or Close.
type Row ¶
type Row struct {
// contains filtered or unexported fields
}
Row is the result of calling QueryRow to select a single row.
type Rows ¶
type Rows struct {
// contains filtered or unexported fields
}
Rows is the result of a query. Its cursor starts before the first row of the result set. Use Next to advance through the rows:
rows, err := db.Query("SELECT ...")
...
for rows.Next() {
var id int
var name string
err = rows.Scan(&id, &name)
...
}
err = rows.Err() // get any error encountered during iteration
...
func (*Rows) Close ¶
Close closes the Rows, preventing further enumeration. If the end is encountered, the Rows are closed automatically. Close is idempotent.
func (*Rows) Columns ¶
Columns returns the column names. Columns returns an error if the rows are closed, or if the rows are from QueryRow and there was a deferred error.
func (*Rows) Next ¶
Next prepares the next result row for reading with the Scan method. It returns true on success, false if there is no next result row. Every call to Scan, even the first one, must be preceded by a call to Next.
func (*Rows) Scan ¶
Scan copies the columns in the current row into the values pointed at by dest.
If an argument has type *[]byte, Scan saves in that argument a copy of the corresponding data. The copy is owned by the caller and can be modified and held indefinitely. The copy can be avoided by using an argument of type *RawBytes instead; see the documentation for RawBytes for restrictions on its use.
If an argument has type *interface{}, Scan copies the value provided by the underlying driver without conversion. If the value is of type []byte, a copy is made and the caller owns the result.
type Scanner ¶
type Scanner interface {
// Scan assigns a value from a database driver.
//
// The src value will be of one of the following restricted
// set of types:
//
// int64
// float64
// bool
// []byte
// string
// time.Time
// nil - for NULL values
//
// An error should be returned if the value can not be stored
// without loss of information.
Scan(src interface{}) error
}
Scanner is an interface used by Scan.
type Stmt ¶
type Stmt struct {
// contains filtered or unexported fields
}
Stmt is a prepared statement. Stmt is safe for concurrent use by multiple goroutines.
func (*Stmt) Exec ¶
Exec executes a prepared statement with the given arguments and returns a Result summarizing the effect of the statement.
func (*Stmt) Query ¶
Query executes a prepared query statement with the given arguments and returns the query results as a *Rows.
func (*Stmt) QueryRow ¶
QueryRow executes a prepared query statement with the given arguments. If an error occurs during the execution of the statement, that error will be returned by a call to Scan on the returned *Row, which is always non-nil. If the query selects no rows, the *Row's Scan will return ErrNoRows. Otherwise, the *Row's Scan scans the first selected row and discards the rest.
Example usage:
var name string err := nameByUseridStmt.QueryRow(id).Scan(&name)
type Tx ¶
type Tx struct {
// contains filtered or unexported fields
}
Tx is an in-progress database transaction.
A transaction must end with a call to Commit or Rollback.
After a call to Commit or Rollback, all operations on the transaction fail with ErrTxDone.
func (*Tx) Exec ¶
Exec executes a query that doesn't return rows. For example: an INSERT and UPDATE.
func (*Tx) Prepare ¶
Prepare creates a prepared statement for use within a transaction.
The returned statement operates within the transaction and can no longer be used once the transaction has been committed or rolled back.
To use an existing prepared statement on this transaction, see Tx.Stmt.
func (*Tx) QueryRow ¶
QueryRow executes a query that is expected to return at most one row. QueryRow always return a non-nil value. Errors are deferred until Row's Scan method is called.
Source Files
Directories