...

パッケージ driver

import "database/sql/driver"
概要
目次

概要 ▾

driver パッケージは, sql パッケージで使われるドライバが実装すべきインターフェースを定義します。

ほとんどのコードはパッケージ sql を使うべきです。

変数

Bool は入力値をブール値に変換する ValueConverter です。

変換規則は次のとおりです。

- ブール値は変更されずに返されます
- 整数型の場合, 1 は true , 0 の場合は false ,他の整数はエラーです
- 文字列および []byte の場合, strconv.ParseBool と同じ規則
- その他のすべての型はエラーです。
var Bool boolType

DefaultParameterConverter は, Stmt が ColumnConverter を実装していない場合に使用される ValueConverter のデフォルト実装です。

IsValue(arg) の場合, DefaultParameterConverter は引数を直接返します。 そうでなければ,もし引数が Valuer を実装していれば,その Value メソッドが Value を返すために使われます。 代替として,渡された引数の基本型は Value に変換するために使用されます。 基本の整数型は int64 に変換され, float64 に浮動小数点数, float , bool , string ,および []byte がそれ自体に変換されます。 引数が nil ポインタの場合, ConvertValue は nil Value を返します。 引数が nil 以外のポインタの場合,それは間接参照され, ConvertValue が再帰的に呼び出されます。 他の型はエラーです。

var DefaultParameterConverter defaultConverter

ErrBadConn は, driver.Conn が (サーバーが以前に接続を閉じたなど) 悪い状態にあることを sql パッケージに通知するためにドライバーによって返され, sql パッケージは新しい接続を再試行する必要があります。

重複操作を防ぐために,データベースサーバが操作を実行した可能性がある場合は ErrBadConn を返さないでください。 サーバーがエラーを送り返しても, ErrBadConn は返さないでください。

var ErrBadConn = errors.New("driver: bad connection")

ErrRemoveArgument は NamedValueChecker から返され, sql パッケージに引数をドライバクエリインターフェースに渡さないように指示します。 SQL 照会引数ではない照会固有のオプションまたは構造を受け入れるときに戻ります。

var ErrRemoveArgument = errors.New("driver: remove argument from query")

ErrSkip は,実行時に高速パスが使用不可であり, SQL パッケージはオプションのインターフェースが実装されていないかのように続行する必要があることを示すために,いくつかのオプションのインターフェースのメソッドによって返されることがあります。 ErrSkip は明示的に文書化されている場合にのみサポートされます。

var ErrSkip = errors.New("driver: skip fast-path; continue as if unimplemented")

Int32 は, int32 値の制限を考慮して,入力値を int64 に変換する ValueConverter です。

var Int32 int32Type

ResultNoRows は, DDL コマンド (CREATETABLE など) が成功したときにドライバが返す定義済みの結果です。 LastInsertId と RowsAffected の両方に対してエラーを返します。

var ResultNoRows noRows

String は,入力を文字列に変換する ValueConverter です。 値がすでに文字列または []byte の場合は,変更されません。 値が別の型の場合,文字列への変換は fmt.Sprintf("%v", v) で行われます。

var String stringType

func IsScanValue

func IsScanValue(v interface{}) bool

IsScanValue は IsValue と同等です。 互換性のために存在します。

func IsValue

func IsValue(v interface{}) bool

IsValue は, v が有効な Value パラメータ型かどうかを報告します。

type ColumnConverter

ステートメントが独自の列の型を認識していて,任意の型からドライバの値に変換できる場合は, ColumnConverter を Stmt で実装することもできます。

非推奨 : ドライバーは NamedValueChecker を実装する必要があります。

type ColumnConverter interface {
    // ColumnConverter は,指定された列インデックスの ValueConverter を返します。
    // 特定の列の型がわからない場合や特別に処理する必要がない場合は, DefaultValueConverter を返すことができます。
    ColumnConverter(idx int) ValueConverter
}

type Conn

Conn はデータベースへの接続です。 複数のゴルーチンで平行に使用されることはありません。

Conn はステートフルと見なされます。

type Conn interface {
    // Prepare は,この接続にバインドされているプリペアドステートメントを返します。
    Prepare(query string) (Stmt, error)

    // Close すると,現在の準備済みステートメントとトランザクションが無効になり,潜在的に停止され,この接続はもう使用されていないとマークされます。
    //
    // sql パッケージは空き接続プールを維持し,余ったアイドル接続があるときにだけ Close を呼び出すので,ドライバが独自の接続キャッシュを実行する必要はありません。
    Close() error

    // 開始して新しいトランザクションを返します。
    //
    // 非推奨 : ドライバーは代わりに (または追加で)ConnBeginTx を実装する必要があります。
    Begin() (Tx, error)
}

type ConnBeginTx 1.8

ConnBeginTx は,コンテキストと TxOptions を使用して Conn インターフェースを拡張します。

type ConnBeginTx interface {
    // BeginTx は新しいトランザクションを開始して返します。
    // コンテキストがユーザによってキャンセルされた場合, sql パッケージは接続を破棄して閉じる前に Tx.Rollback を呼び出します。
    //
    // これは opts.Isolation をチェックして,設定された分離レベルがあるかどうかを判断する必要があります。
    // ドライバがデフォルト以外のレベルをサポートしておらず,そのレベルが設定されている場合,またはサポートされていないデフォルト以外の分離レベルがある場合は,エラーを返す必要があります。
    //
    // また, opts.ReadOnly をチェックして,読み取り専用の値が true であるかどうかを判断し,サポートされている場合は読み取り専用のトランザクションプロパティを設定するか,サポートされていない場合はエラーを返します。
    BeginTx(ctx context.Context, opts TxOptions) (Tx, error)
}

type ConnPrepareContext 1.8

ConnPrepareContext は,コンテキストを使用して Conn インターフェースを拡張します。

type ConnPrepareContext interface {
    // PrepareContext は,この接続にバインドされた準備済みステートメントを返します。
    // context は文を準備するためのもので,文を文自体の中に格納してはいけません。
    PrepareContext(ctx context.Context, query string) (Stmt, error)
}

type Connector 1.10

Connector (コネクター) は固定構成のドライバーを表し,複数のゴルーチンで使用するための等価な Conns をいくつでも作成できます。

Connector を sql.OpenDB に渡して,ドライバが独自の sql.DB コンストラクタを実装できるようにすることも, DriverContext の OpenConnector メソッドによって返すこともできます。 これにより,ドライバはコンテキストにアクセスでき,ドライバ設定の解析が繰り返されるのを防ぎます。

type Connector interface {
    // Connect はデータベースへの接続を返します。
    // Connect はキャッシュされた接続 (以前に閉じられたもの) を返しても構いませんが,そうすることは不要です。
    // sql パッケージは効率的な再利用のためにアイドル接続プールを維持します。
    //
    // 渡されている context.Context はダイヤル専用であり (net.DialContext を参照) ,保存したり他の目的に使用したりしないでください。
    //
    // 返された接続は一度に 1 つの goroutine によってのみ使用されます。
    Connect(context.Context) (Conn, error)

    // Driver は,主に sql.DB の Driver メソッドとの互換性を維持するために,コネクタの内部の Driver を返します。
    Driver() Driver
}

type Driver

Driver は,データベースドライバによって実装されなければならないインターフェースです。

データベースドライバは,コンテキストへのアクセスと,接続ごとに 1 回ではなく,接続プールに対して 1 回だけ名前を解析するための DriverContext を実装できます。

type Driver interface {
    // Open はデータベースへの新しい接続を返します。
    // 名前はドライバ固有の形式の文字列です。
    //
    // Open はキャッシュされた接続 (以前に閉じられたもの) を返しても構いませんが,そうすることは不要です。
    // sql パッケージは効率的な再利用のためにアイドル接続プールを維持します。
    //
    // 返された接続は一度に 1 つの goroutine によってのみ使用されます。
    Open(name string) (Conn, error)
}

type DriverContext 1.10

ドライバが DriverContext を実装している場合, sql.DB は OpenConnector を呼び出してコネクタを取得し,次に各コネクタに対して Driver の Open メソッドを呼び出すのではなく,必要な各接続を取得するためにそのコネクタの Conn メソッドを呼び出します。 2 段階のシーケンスにより,ドライバーは一度だけ名前を解析でき, Conn ごとのコンテキストへのアクセスも可能になります。

type DriverContext interface {
    // OpenConnector は, Driver.Open が name パラメーターを解析するのと同じ形式で名前を解析する必要があります。
    OpenConnector(name string) (Connector, error)
}

type Execer

Execer は Conn によって実装されるかもしれないオプションのインターフェースです。

Conn が ExecerContext も Execer も実装していない場合, sql パッケージの DB.Exec は最初にクエリを準備し,文を実行してから文を閉じます。

Exec は ErrSkip を返す可能性があります。

非推奨 : ドライバは代わりに ExecerContext を実装するべきです。

type Execer interface {
    Exec(query string, args []Value) (Result, error)
}

type ExecerContext 1.8

ExecerContext は, Conn によって実装されるかもしれないオプションのインターフェースです。

Conn が ExecerContext を実装していない場合, sql パッケージの DB.Exec は Execer にフォールバックします。 Conn が Execer も実装していない場合, DB.Exec は最初にクエリを準備し,文を実行してから文を閉じます。

ExecerContext は ErrSkip を返すことがあります。

ExecerContext はコンテキストのタイムアウトを守り,コンテキストがキャンセルされたときに返さなければなりません。

type ExecerContext interface {
    ExecContext(ctx context.Context, query string, args []NamedValue) (Result, error)
}

type IsolationLevel 1.8

IsolationLevel は, TxOptions に格納されているトランザクション分離レベルです。

この型は,定義されている値とともに sql.IsolationLevel と同一であると見なす必要があります。

type IsolationLevel int

type NamedValue 1.8

NamedValue は値の名前と値の両方を保持します。

type NamedValue struct {
    // Name が空でない場合は,序数位置ではなくパラメータ識別子に使用する必要があります。
    //
    // Name にはシンボルの接頭辞は付きません。
    Name string

    // Ordinal は,1 から始まるパラメータの序数位置で,常に設定されています。
    Ordinal int

    // Value はパラメータ値です。
    Value Value
}

type NamedValueChecker 1.9

NamedValueChecker は, Conn または Stmt によってオプションで実装される場合があります。 許可されているデフォルトの Values 型を超えて, Go およびデータベース型を処理するためのより多くの制御をドライバーに提供します。

sql パッケージは,最初に見つかった一致で停止して,値チェッカーを次の順序でチェックします。 Stmt.NamedValueChecker , Conn.NamedValueChecker , Stmt.ColumnConverter , DefaultParameterConverter 。

CheckNamedValue が ErrRemoveArgument を返す場合, NamedValue は最後のクエリ引数に含まれません。 これはクエリ自身に特別なオプションを渡すために使われるかもしれません。

ErrSkip が返された場合は,引数に列コンバータのエラーチェックパスが使用されます。 運転手は,自分たちの特別な場合を使い果たした後に ErrSkip を返したいと思うかもしれません。

type NamedValueChecker interface {
    // CheckNamedValue は,引数をドライバに渡す前に呼び出され, ColumnConverter の代わりに呼び出されます。
    // CheckNamedValue は,ドライバに応じて型の検証と変換を行う必要があります。
    CheckNamedValue(*NamedValue) error
}

type NotNull

NotNull は, nil 値を許可しないで ValueConverter を実装する型ですが,それ以外の場合は別の ValueConverter に委任します。

type NotNull struct {
    Converter ValueConverter
}

func (NotNull) ConvertValue

func (n NotNull) ConvertValue(v interface{}) (Value, error)

type Null

Null は, nil 値を許可することで ValueConverter を実装する型ですが,それ以外の場合は別の ValueConverter に委任します。

type Null struct {
    Converter ValueConverter
}

func (Null) ConvertValue

func (n Null) ConvertValue(v interface{}) (Value, error)

type Pinger 1.8

Pinger は, Conn によって実装されるかもしれないオプションのインターフェースです。

Conn が Pinger を実装していない場合, sql パッケージの DB.Ping と DB.PingContext は少なくとも 1 つの Conn が利用可能かどうかをチェックします。

Conn.Ping が ErrBadConn を返した場合, DB.Ping と DB.PingContext はプールから Conn を削除します。

type Pinger interface {
    Ping(ctx context.Context) error
}

type Queryer 1.1

Queryer は Conn によって実装されるかもしれないオプションのインターフェースです。

Conn が QueryerContext も Queryer も実装していない場合, sql パッケージの DB.Query は最初にクエリを準備し,文を実行してから文を閉じます。

Query は ErrSkip を返すことがあります。

非推奨 : ドライバーは代わりに QueryerContext を実装する必要があります。

type Queryer interface {
    Query(query string, args []Value) (Rows, error)
}

type QueryerContext 1.8

QueryerContext は, Conn によって実装されるかもしれないオプションのインターフェースです。

Conn が QueryerContext を実装していない場合, SQL パッケージの DB.Query は Queryer にフォールバックします。 Conn も Queryer を実装していない場合, DB.Query は最初にクエリを準備し,文を実行してから文を閉じます。

QueryerContext は ErrSkip を返すことがあります。

QueryerContext はコンテキストのタイムアウトを守り,コンテキストがキャンセルされたときに返さなければなりません。

type QueryerContext interface {
    QueryContext(ctx context.Context, query string, args []NamedValue) (Rows, error)
}

type Result

Result は,クエリ実行の結果です。

type Result interface {
    // LastInsertId は,主キーを持つテーブルへの INSERT などの後に,データベースの自動生成された ID を返します。
    LastInsertId() (int64, error)

    // RowsAffected は,クエリによって影響を受けた行数を返します。
    RowsAffected() (int64, error)
}

type Rows

Row は,実行されたクエリの結果に対する反復子です。

type Rows interface {
    // Columns は列の名前を返します。
    // 結果の列数は,スライスの長さから推測されます。
    // 特定の列名がわからない場合は,そのエントリに対して空の文字列が返されます。
    Columns() []string

    // Close は行イテレータを閉じます。
    Close() error

    // Next は,渡されたスライスに次のデータ行を移入するために呼び出されます。
    // 渡されたスライスは, Columns() の幅と同じサイズになります。
    //
    // もう行がなくなると, Next は io.EOF を返します。
    //
    // dest は Next の外側に書かれるべきではありません。
    // 行を閉じるとき, dest に保持されているバッファを変更しないように注意する必要があります。
    Next(dest []Value) error
}

type RowsAffected

RowsAffected は,多数の行を変更する INSERT または UPDATE 操作に対して Result を実装します。

type RowsAffected int64

func (RowsAffected) LastInsertId

func (RowsAffected) LastInsertId() (int64, error)

func (RowsAffected) RowsAffected

func (v RowsAffected) RowsAffected() (int64, error)

type RowsColumnTypeDatabaseTypeName 1.8

RowsColumnTypeDatabaseTypeName は Rows によって実装される場合があります。 データベースシステムの型名を長さなしで返します。 型名は大文字にする必要があります。 返される型の例 : "VARCHAR" , "NVARCHAR" , "VARCHAR2" , "CHAR" , "TEXT" , "DECIMAL" , "SMALLINT" , "INT" , "BIGINT" , "BOOL" , "[]BIGINT" , "JSONB" , "XML" , "TIMESTAMP" 。

type RowsColumnTypeDatabaseTypeName interface {
    Rows
    ColumnTypeDatabaseTypeName(index int) string
}

type RowsColumnTypeLength 1.8

RowsColumnTypeLength は Rows によって実装される場合があります。 列が可変長型の場合は,列型の長さを返します。 列が可変長型ではない場合, ok は false を返します。 システムの制限以外に長さが制限されていない場合は, math.MaxInt64 を返します。 さまざまな型の戻り値の例を次に示します。

TEXT          (math.MaxInt64, true)
varchar(10)   (10, true)
nvarchar(10)  (10, true)
decimal       (0, false)
int           (0, false)
bytea(30)     (30, true)
type RowsColumnTypeLength interface {
    Rows
    ColumnTypeLength(index int) (length int64, ok bool)
}

type RowsColumnTypeNullable 1.8

RowsColumnTypeNullable は Rows によって実装されるかもしれません。 列が NULL 値である可能性があることがわかっている場合は NULL 値,列が NULL 値ではないことがわかっている場合は NULL 値を指定します。 列の NULL 入力可否がわからない場合は, false にしてください。

type RowsColumnTypeNullable interface {
    Rows
    ColumnTypeNullable(index int) (nullable, ok bool)
}

type RowsColumnTypePrecisionScale 1.8

RowsColumnTypePrecisionScale は Rows によって実装されるかもしれません。 10 進数型の精度とスケールを返します。 該当しない場合は, ok を false にします。 さまざまな型の戻り値の例を次に示します。

decimal(38, 4)    (38, 4, true)
int               (0, 0, false)
decimal           (math.MaxInt64, math.MaxInt64, true)
type RowsColumnTypePrecisionScale interface {
    Rows
    ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)
}

type RowsColumnTypeScanType 1.8

RowsColumnTypeScanType は Rows によって実装される場合があります。 型のスキャンに使用できる値の型を返す必要があります。 たとえば,データベースの列型が "bigint" の場合, "reflect.TypeOf(int64(0))" が返されます。

type RowsColumnTypeScanType interface {
    Rows
    ColumnTypeScanType(index int) reflect.Type
}

type RowsNextResultSet 1.8

RowsNextResultSet は,ドライバに次の結果セットに進むように通知する方法を提供することによって, Rows インターフェースを拡張します。

type RowsNextResultSet interface {
    Rows

    // HasNextResultSet は現在の結果セットの最後に呼び出され,現在の結果セットの後に別の結果セットがあるかどうかを報告します。
    HasNextResultSet() bool

    // NextResultSet は,現在の結果セットに行が残っている場合でも,ドライバを次の結果セットに進めます。
    //
    // 結果セットがもうない場合, NextResultSet は io.EOF を返します。
    NextResultSet() error
}

type SessionResetter 1.10

SessionResetter は,ドライバが接続に関連するセッション状態をリセットし,悪い接続を通知することを可能にするために Conn によって実装されるかもしれません。

type SessionResetter interface {
    // ResetSession は,接続が接続プールにある間に呼び出されます。
    // このメソッドが戻るまで,この接続に対してクエリは実行されません。
    //
    // 接続が悪い場合は,接続が接続プールに返されないように driver.ErrBadConn を返す必要があります。
    // 他のエラーはすべて破棄されます。
    ResetSession(ctx context.Context) error
}

type Stmt

Stmt はプリペアドステートメントです。 これは Conn にバインドされており,複数の goroutine によって平行に使用されることはありません。

type Stmt interface {
    // Close は文を閉じます。
    //
    // Go 1.1 以降, Stmt は他のクエリで使用されていてもクローズされません。
    Close() error

    // NumInput は,プレースホルダパラメータの数を返します。
    //
    // NumInput が >= 0 を返した場合, sql パッケージは呼び出し元からの引数カウントを確認し,ステートメントの Exec または Query メソッドが呼び出される前に呼び出し元にエラーを返します。
    //
    // ドライバがプレースホルダの数を知らない場合, NumInput は -1 を返すこともあります。
    // その場合, sql パッケージは Exec または Query 引数の数をチェックしません。
    NumInput() int

    // Exec は, INSERT や UPDATE など,行を返さないクエリを実行します。
    //
    // 非推奨 : ドライバは代わりに (または追加で)StmtExecContext を実装する必要があります。
    Exec(args []Value) (Result, error)

    // Query は, SELECT など,行を返すクエリを実行します。
    //
    // 非推奨 : ドライバーは代わりに (または追加で)StmtQueryContext を実装する必要があります。
    Query(args []Value) (Rows, error)
}

type StmtExecContext 1.8

StmtExecContext は Exec にコンテキストを提供することで Stmt インターフェースを強化します。

type StmtExecContext interface {
    // ExecContext は, INSERT や UPDATE など,行を返さないクエリを実行します。
    //
    // ExecContext はコンテキストのタイムアウトを遵守し,キャンセルされたときに返さなければなりません。
    ExecContext(ctx context.Context, args []NamedValue) (Result, error)
}

type StmtQueryContext 1.8

StmtQueryContext は,クエリにコンテキストを提供することで Stmt インターフェースを強化します。

type StmtQueryContext interface {
    // QueryContext は, SELECT など,行を返す可能性のあるクエリを実行します。
    //
    // QueryContext はコンテキストのタイムアウトを尊重し,キャンセルされたときに返さなければなりません。
    QueryContext(ctx context.Context, args []NamedValue) (Rows, error)
}

type Tx

Tx はトランザクションです。

type Tx interface {
    Commit() error
    Rollback() error
}

type TxOptions 1.8

TxOptions はトランザクションオプションを保持します。

この型は sql.TxOptions と同一と見なされるべきです。

type TxOptions struct {
    Isolation IsolationLevel
    ReadOnly  bool
}

type Value

Value は,ドライバーが処理できなければならない値です。 それは nil ,データベースドライバの NamedValueChecker インターフェースによって処理される型,またはこれらの型のうちの 1 つのインスタンスです。

int64
float64
bool
[]byte
string
time.Time

If the driver supports cursors, a returned Value may also implement the Rows interface in this package. This is used, for example, when a user selects a cursor such as "select cursor(select * from my_table) from dual". If the Rows from the select is closed, the cursor Rows will also be closed.

type Value interface{}

type ValueConverter

ValueConverter は, ConvertValue メソッドを提供するインターフェースです。

ドライバ間の変換の一貫した実装を提供するために,ドライバパッケージによってさまざまな ValueConverter の実装が渡されています。 ValueConverters にはいくつかの用途があります。

* sql パッケージで渡されている Value 型からデータベーステーブルの特定のカラム型に変換し,それが収まることを確認します。
  例えば,特定の int64 がテーブルの uint16 カラムに収まるか確認します。

* データベースから与えられた値をドライバの Value 型の一つに変換する。

* sql パッケージでの用途。

ドライバの Value 型からスキャン時のユーザの型への変換用。

type ValueConverter interface {
    // ConvertValue は値をドライバの Value に変換します。
    ConvertValue(v interface{}) (Value, error)
}

type Valuer

Valuer は Value メソッドを提供するインターフェースです。

Valuer インターフェースを実装する型は,自分自身をドライバの Value に変換することができます。

type Valuer interface {
    // Value はドライバの Value を返します。
    // Value must not panic.
    Value() (Value, error)
}