# package driver
`import "database/sql/driver"`
driver包定義了應被數據庫驅動實現的接口,這些接口會被sql包使用。
絕大多數代碼應使用sql包。
## Index
* [Variables](#pkg-variables)
* [type Value](#Value)
* [type Valuer](#Valuer)
* [func IsValue(v interface{}) bool](#IsValue)
* [func IsScanValue(v interface{}) bool](#IsScanValue)
* [type ValueConverter](#ValueConverter)
* [type ColumnConverter](#ColumnConverter)
* [type NotNull](#NotNull)
* [func (n NotNull) ConvertValue(v interface{}) (Value, error)](#NotNull.ConvertValue)
* [type Null](#Null)
* [func (n Null) ConvertValue(v interface{}) (Value, error)](#Null.ConvertValue)
* [type Driver](#Driver)
* [type Conn](#Conn)
* [type Execer](#Execer)
* [type Queryer](#Queryer)
* [type Stmt](#Stmt)
* [type Tx](#Tx)
* [type Result](#Result)
* [type RowsAffected](#RowsAffected)
* [func (RowsAffected) LastInsertId() (int64, error)](#RowsAffected.LastInsertId)
* [func (v RowsAffected) RowsAffected() (int64, error)](#RowsAffected.RowsAffected)
* [type Rows](#Rows)
## Variables
```
var Bool boolType
```
Bool是ValueConverter接口值,用于將輸入的值轉換為布爾類型。
轉換規則如下:
```
- 布爾類型:不做修改
- 整數類型:
1 為真
0 為假
其余整數會導致錯誤
- 字符串和[]byte:與strconv.ParseBool的規則相同
- 所有其他類型都會導致錯誤
```
```
var Int32 int32Type
```
Int32是一個ValueConverter接口值,用于將值轉換為int64類型,會尊重int32類型的限制。
```
var String stringType
```
String是一個ValueConverter接口值,用于將值轉換為字符串。如果值v是字符串或者[]byte類型,不會做修改,如果值v是其它類型,會轉換為fmt.Sprintf("%v", v)。
```
var DefaultParameterConverter defaultConverter
```
DefaultParameterConverter是ValueConverter接口的默認實現,當一個Stmt沒有實現ColumnConverter時,就會使用它。
如果值value滿足函數IsValue(value)為真,DefaultParameterConverter直接返回 value。否則,整數類型會被轉換為int64,浮點數轉換為float64,字符串轉換為[]byte。其它類型會導致錯誤。
```
var ResultNoRows noRows
```
ResultNoRows是預定義的Result類型值,用于當一個DDL命令(如create table)成功時被驅動返回。它的LastInsertId和RowsAffected方法都返回錯誤。
```
var ErrBadConn = errors.New("driver: bad connection")
```
ErrBadConn應被驅動返回,以通知sql包一個driver.Conn處于損壞狀態(如服務端之前關閉了連接),sql包會重啟一個新的連接。
為了避免重復的操作,如果數據庫服務端執行了操作,就不應返回ErrBadConn。即使服務端返回了一個錯誤。
```
var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")
```
ErrSkip可能會被某些可選接口的方法返回,用于在運行時表明快速方法不可用,sql包應像未實現該接口的情況一樣執行。ErrSkip只有文檔顯式說明的地方才支持。
## type [Value](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#22 "View Source")
```
type Value interface{}
```
Value是驅動必須能處理的值。它要么是nil,要么是如下類型的實例:
```
int64
float64
bool
[]byte
string [*] Rows.Next不會返回該類型值
time.Time
```
## type [Valuer](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#39 "View Source")
```
type Valuer interface {
// Value返回一個驅動支持的Value類型值
Value() (Value, error)
}
```
Valuer是提供Value方法的接口。實現了Valuer接口的類型可以將自身轉換為驅動支持的Value類型值。
## func [IsValue](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#176 "View Source")
```
func IsValue(v interface{}) bool
```
IsValue報告v是否是合法的Value類型參數。和IsScanValue不同,IsValue接受字符串類型。
## func [IsScanValue](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#188 "View Source")
```
func IsScanValue(v interface{}) bool
```
IsScanValue報告v是否是合法的Value掃描類型參數。和IsValue不同,IsScanValue不接受字符串類型。
## type [ValueConverter](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#30 "View Source")
```
type ValueConverter interface {
// ConvertValue將一個值轉換為驅動支持的Value類型
ConvertValue(v interface{}) (Value, error)
}
```
ValueConverter接口提供了ConvertValue方法。
driver包提供了各種ValueConverter接口的實現,以保證不同驅動之間的實現和轉換的一致性。ValueConverter接口有如下用途:
```
* 轉換sql包提供的Value類型值到數據庫指定列的類型,并保證它的匹配,
例如保證某個int64值滿足一個表的uint16列。
* 轉換數據庫提供的值到驅動的Value類型。
* 在掃描時被sql包用于將驅動的Value類型轉換為用戶的類型。
```
## type [ColumnConverter](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#145 "View Source")
```
type ColumnConverter interface {
// ColumnConverter返回指定列的ValueConverter
// 如果該列未指定類型,或不應特殊處理,應返回DefaultValueConverter
ColumnConverter(idx int) ValueConverter
}
```
如果Stmt有自己的列類型,可以實現ColumnConverter接口,返回值可以將任意類型轉換為驅動的Value類型。
## type [NotNull](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#163 "View Source")
```
type NotNull struct {
Converter ValueConverter
}
```
NotNull實現了ValueConverter接口,不允許nil值,否則會將值交給Converter字段處理。
### func (NotNull) [ConvertValue](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#167 "View Source")
```
func (n NotNull) ConvertValue(v interface{}) (Value, error)
```
## type [Null](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#150 "View Source")
```
type Null struct {
Converter ValueConverter
}
```
Null實現了ValueConverter接口,允許nil值,否則會將值交給Converter字段處理。
### func (Null) [ConvertValue](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/types.go?name=release#154 "View Source")
```
func (n Null) ConvertValue(v interface{}) (Value, error)
```
## type [Driver](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#26 "View Source")
```
type Driver interface {
// Open返回一個新的與數據庫的連接,參數name的格式是驅動特定的。
//
// Open可能返回一個緩存的連接(之前關閉的連接),但這么做是不必要的;
// sql包會維護閑置連接池以便有效的重用連接。
//
// 返回的連接同一時間只會被一個go程使用。
Open(name string) (Conn, error)
}
```
Driver接口必須被數據庫驅動實現。
## type [Conn](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#83 "View Source")
```
type Conn interface {
// Prepare返回一個準備好的、綁定到該連接的狀態。
Prepare(query string) (Stmt, error)
// Close作廢并停止任何現在準備好的狀態和事務,將該連接標注為不再使用。
//
// 因為sql包維護著一個連接池,只有當閑置連接過剩時才會調用Close方法,
// 驅動的實現中不需要添加自己的連接緩存池。
Close() error
// Begin開始并返回一個新的事務。
Begin() (Tx, error)
}
```
Conn是與數據庫的連接。該連接不會被多線程并行使用。連接被假定為具有狀態的。
## type [Execer](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#64 "View Source")
```
type Execer interface {
Exec(query string, args []Value) (Result, error)
}
```
Execer是一個可選的、可能被Conn接口實現的接口。
如果一個Conn未實現Execer接口,sql包的DB.Exec會首先準備一個查詢,執行狀態,然后關閉狀態。Exec可能會返回ErrSkip。
## type [Queryer](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#75 "View Source")
```
type Queryer interface {
Query(query string, args []Value) (Rows, error)
}
```
Queryer是一個可選的、可能被Conn接口實現的接口。
如果一個Conn未實現Queryer接口,sql包的DB.Query會首先準備一個查詢,執行狀態,然后關閉狀態。Query可能會返回ErrSkip。
## type [Stmt](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#115 "View Source")
```
type Stmt interface {
// Close關閉Stmt。
//
// 和Go1.1一樣,如果Stmt被任何查詢使用中的話,將不會被關閉。
Close() error
// NumInput返回占位參數的個數。
//
// 如果NumInput返回值 >= 0,sql包會提前檢查調用者提供的參數個數,
// 并且會在調用Exec或Query方法前返回數目不對的錯誤。
//
// NumInput可以返回-1,如果驅動占位參數的數量。
// 此時sql包不會提前檢查參數個數。
NumInput() int
// Exec執行查詢,而不會返回結果,如insert或update。
Exec(args []Value) (Result, error)
// Query執行查詢并返回結果,如select。
Query(args []Value) (Rows, error)
}
```
Stmt是準備好的狀態。它會綁定到一個連接,不應被多go程同時使用。
## type [Tx](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#177 "View Source")
```
type Tx interface {
Commit() error
Rollback() error
}
```
Tx是一次事務。
## type [Result](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#102 "View Source")
```
type Result interface {
// LastInsertId返回insert等命令后數據庫自動生成的ID
LastInsertId() (int64, error)
// RowsAffected返回被查詢影響的行數
RowsAffected() (int64, error)
}
```
Result是查詢執行的結果。
## type [RowsAffected](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#184 "View Source")
```
type RowsAffected int64
```
RowsAffected實現了Result接口,用于insert或update操作,這些操作會修改零到多行數據。
### func (RowsAffected) [LastInsertId](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#188 "View Source")
```
func (RowsAffected) LastInsertId() (int64, error)
```
### func (RowsAffected) [RowsAffected](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#192 "View Source")
```
func (v RowsAffected) RowsAffected() (int64, error)
```
## type [Rows](http://code.google.com/p/go/source/browse/src/pkg/database/sql/driver/driver.go?name=release#154 "View Source")
```
type Rows interface {
// Columns返回各列的名稱,列的數量可以從切片長度確定。
// 如果某個列的名稱未知,對應的條目應為空字符串。
Columns() []string
// Close關閉Rows。
Close() error
// 調用Next方法以將下一行數據填充進提供的切片中。
// 提供的切片必須和Columns返回的切片長度相同。
//
// 切片dest可能被填充同一種驅動Value類型,但字符串除外。
// 所有string值都必須轉換為[]byte。
//
// 當沒有更多行時,Next應返回io.EOF。
Next(dest []Value) error
}
```
Rows是執行查詢得到的結果的迭代器。
- 庫
- package achive
- package tar
- package zip
- package bufio
- package builtin
- package bytes
- package compress
- package bzip2
- package flate
- package gzip
- package lzw
- package zlib
- package container
- package heap
- package list
- package ring
- package crypto
- package aes
- package cipher
- package des
- package dsa
- package ecdsa
- package elliptic
- package hmac
- package md5
- package rand
- package rc4
- package rsa
- package sha1
- package sha256
- package sha512
- package subtle
- package tls
- package x509
- package pkix
- package database
- package sql
- package driver
- package encoding
- package ascii85
- package asn1
- package base32
- package base64
- package binary
- package csv
- package gob
- package hex
- package json
- package pem
- package xml
- package errors
- package expvar
- package flag
- package fmt
- package go
- package doc
- package format
- package parser
- package printer
- package hash
- package adler32
- package crc32
- package crc64
- package fnv
- package html
- package template
- package image
- package color
- package palette
- package draw
- package gif
- package jpeg
- package png
- package index
- package suffixarray
- package io
- package ioutil
- package log
- package syslog
- package math
- package big
- package cmplx
- package rand
- package mime
- package multipart
- package net
- package http
- package cgi
- package cookiejar
- package fcgi
- package httptest
- package httputil
- package pprof
- package mail
- package rpc
- package jsonrpc
- package smtp
- package textproto
- package url
- package os
- package exec
- package signal
- package user
- package path
- package filepath
- package reflect
- package regexp
- package runtime
- package cgo
- package debug
- package pprof
- package race
- package sort
- package strconv
- package strings
- package sync
- package atomic
- package text
- package scanner
- package tabwriter
- package template
- package time
- package unicode
- package utf16
- package utf8
- package unsafe