by Hippo2000(2001/8/2)
(2001/9/13) 原田＠T.N.Lifesystemsさんからの指摘を受けて、誤字を２箇所修正しました。
日本語チョウ訳シリーズ DBIモジュールなのです。前回のチョウ訳（1.14）からみると、ちょっとずつパワーアップしています。
いつものことですが、わかりにくい（あやしい）説明は本物を見てください。(^^;原本の著作権はTim Bunce氏がお持ちです（詳しくは著作権情報を見てください）。Tim Bunce氏にはメールで了解をいただきました。
内容等が間違っていたら修正します。
質問なども含めて、できるだけDBI日本語メーリングリストにご連絡ください。
アドレスは探せばすぐに見つかるはず(^^)
DBI - Ｐｅｒｌ用データベース独立インターフェース
use DBI;
@driver_names = DBI->available_drivers; @data_sources = DBI->data_sources($driver_name, \%attr);
$dbh = DBI->connect($data_source, $username, $auth, \%attr);
$rv = $dbh->do($statement); $rv = $dbh->do($statement, \%attr); $rv = $dbh->do($statement, \%attr, @bind_values);
$ary_ref = $dbh->selectall_arrayref($statement); $ary_ref = $dbh->selectall_hashref($statement);
$ary_ref = $dbh->selectcol_arrayref($statement);
$ary_ref = $dbh->selectrow_arrayref($statement); @row_ary = $dbh->selectrow_array($statement);
$sth = $dbh->prepare($statement); $sth = $dbh->prepare_cached($statement);
$rv = $sth->bind_param($p_num, $bind_value); $rv = $sth->bind_param($p_num, $bind_value, $bind_type); $rv = $sth->bind_param($p_num, $bind_value, \%attr);
$rv = $sth->execute; $rv = $sth->execute(@bind_values);
$rc = $sth->bind_col($col_num, \$col_variable); $rc = $sth->bind_columns(@list_of_refs_to_vars_to_bind);
@row_ary = $sth->fetchrow_array; $ary_ref = $sth->fetchrow_arrayref; $hash_ref = $sth->fetchrow_hashref;
$ary_ref = $sth->fetchall_arrayref;
$ary_ref = $sth->fetchall_arrayref( { ... } );
$ary_ref = $sth->fetchall_arrayref( [ ... ] );
$rv = $sth->rows;
$rc = $dbh->commit; $rc = $dbh->rollback;
$sql = $dbh->quote($string);
$rc = $h->err; $str = $h->errstr; $rv = $h->state;
$rc = $dbh->disconnect;
上記の概略は主なメソッドだけをリストにしています。
DBIについて疑問をもったならば、 dbi-users@perl.org メーリング・リストから助けを得ることができます。そのリストへは以下の以下のアドレスにメールを送ることにより参加することができます：
dbi-users-help@perl.org
またDBIホームページも訪れる価値があります：
http://dbi.perl.org/
質問をする前に、このドキュメントを読み返し、アーカイブをあたり、DBI FAQを読んでください。アーカイブはこのリストの最後に一覧があります。FAQはDBI::FAQモジュールとしてインストールされます。そのためperldoc DBI::FAQを実行すると読むことができます。
Tim Bunceがそのメーリング・リストやWebページを管理しているわけではないことに注意してください（通常はボランティアがやっています）。そのため彼に直接メールを送らないで下さい；彼には個人的に質問に答える時間がないだけです。 dbi-usersメーリング・リストは経験豊富な人たちがたくさんいて、必要であればあなたを助けてくれるでしょう。
これはDBIバージョン1.19($Date: 2001/07/20 22:28:28
$).に対応したDBIの仕様です。
DBIの仕様は、現在、確実なペースで更新されています。最新のものを持っているかをチェックしてください。「最近の変更点」というセクションで、ユーザーからわかるDBIの変更の概要をまとめてあります。またDBIと一緒に提供されるChangesファイルにより詳細な情報を記述しています。
DBの変更にドライバが追いつくまでには多少時間がかかることに注意してください。DBIの最近のバージョンでは、新しい機能をたくさん追加しています(文中では NEW で表わしています)。お使いのドライバではまだサポートされていないかもしれません。必要な機能であれば、ドライバの作者にお伝えください。
DBIおよび他のDBI関連の拡張はDBIx::*という名前空間を使います。 命名規約と名前空間と以下のサイトをご覧ください：
http://www.perl.com/CPAN/modules/by-module/DBIx/
最近のバージョンでのユーザにもわかる大きな変更についてまとめたものを以下に示します。（もし最近のバージョンで書かれていないものがあれば、そのバージョンではユーザにわかるような変更はなかったということを示します）
DBIはPerlプログラミング言語のためのデータベース・アクセルモジュールです。それはセットになったメソッド、変数そして規約を定義し、実際の使われているデータベースに依存しない一貫性のあるデータベース・インターフェースを提供します。
DBIが単なるインターフェースであることを忘れないことは重要です。DBIはアプリケーションと１つまたは複数のデータベース・ドライバとを結び付ける薄い「糊」の層なのです。実際に動くのはドライバ・モジュールです。DBIは標準のインターフェースとドライバを操作するための枠組みを提供します。
|<- DBIのスコープ ->| .-. .--------------. .-------------. .−−−−−. | |---| XYZドライバ |---| XYZ エンジン | | ＤＢＩ | | | `--------------' `-------------' | ＡＰＩ | |A| |D| .--------------. .-------------. |メソッド |--|P|--|B|---|Oracleドライバ |---|Oracleエンジン| |を使った | |I| |I| `--------------' `-------------' |Ｐｅｒｌ | | |... |スクリプト| | |... その他のドライバ `−−−−−' | |... -
API、またはアプリケーション・プログラミング・インターフェースPerlスクリプトが使うための呼び出しインタフェースと変数を定義します。AIPはPerl DBI拡張によって実装されます。
DBIは適切なドライバへ実際の実行のためにメソッド呼び出しを"発行（dispatch)"します。DBIはドライバの動的なロード、エラーのチェック／操作、メソッドのためのデフォルトの実装の提供、その他たくさんのデータベース特有なこと以外にも責任を持ちます。
各ドライバは対応するデータベース・エンジンのプライベートなインターフェス関数を使い、DBIメソッドの実装を持ちます。高度なあるいは、複数のデータベースに対応するアプリーケーションや汎用ライブラリ関数の作成者だけが、このドライバに関心をもつ必要があります。
このドキュメントでは以下の表記法を使用します：
$dbh データベース・ハンドル・オブジェクト $sth ステートメント・ハンドル・オブジェクト $drh ドライバハンドル・オブジェクト(アプリケーションで目にしたり、使ったりすることはまずありません) $h 上記のハンドルのどれか $rc 一般的な戻り値（コード）（ブール値: true=ok, false=error) $rv 一般的な戻り値（値） (通常はinteger) @ary データベースから返される値のリスト。通常はデータの行 $rows 処理された行の数 (もしあれば。なければ -1) $fh ファイルハンドル undef PerlではNULL値は未定義値で表現される \%attr メソッドに渡される属性値のハッシュのリファレンス
注意：そこへの参照がすべて削除されると、Perlは、自動的にデータベースとステートメントオブジェクトを破壊します。
DBIを使うためには、まずDBIモジュールをロードする必要があります：
use DBI; use strict;
(use strict;
は必須ではありませんが、強く推奨します。)
そしてデータソースに接続（ connect ）し、その接続のためのハンドルを取得します：
$dbh = DBI->connect($dsn, $user, $password,
{ RaiseError => 1, AutoCommit => 0 });
接続にはコストがかかるので、一般的にはプログラムの開始した時点で接続し、終わりで切断します：
要求されるAutoCommitの動きを明示的に定義することは強く推奨されます。将来のバージョンでは必須になるかもしれません。これは実行したときに変更を自動的にデータベースにコミットするか、後から明示的にコミットされる必要があるかを決定します。
DBIでは、アプリケーションはSQL文を後で実行するための"prepare(=準備）"をしておくことができます。prepareされたステートメントはPerl変数に入ったステートメント・ハンドルにより識別されます。この例ではそのPerl変数を$sthとします。
SELECTステートメントのための典型的なメソッドの順番は以下のようになります：
prepare,
execute, fetch, fetch, ...
execute, fetch, fetch, ...
execute, fetch, fetch, ...
例：
$sth = $dbh->prepare("SELECT foo, bar FROM table WHERE baz=?");
$sth->execute( $baz );
while ( @row = $sth->fetchrow_array ) {
print "@row\n";
}
SELECTステートメント以外のための典型的なメソッドの順番は以下のようになります：
prepare,
execute,
execute,
execute.
例：
$sth = $dbh->prepare("INSERT INTO table(foo,bar,baz) VALUES (?,?,?)");
while(<CSV>) {
chomp;
my ($foo,$bar,$baz) = split /,/;
$sth->execute( $foo, $bar, $baz );
}
do() メソッドは繰り返されないSELECT以外のステートメントのために（またはプレースホルダをサポートしないドライバで）使うことができます：
$rows_affected = $dbh->do("UPDATE your_table SET foo = foo + 1");
データベースへの変更をコミットするためには（AutoCommit がオフの時）：
$dbh->commit; # 変更を無効にするためには $dbh->rollback;
最後に、データソースでの作業を終了するときにはそこから切断（disconnect ）しなければいけません ：
$dbh->disconnect;
DBIには「現在のセッション」という考えはありません。各セッションはconnectメソッドから返されるハンドル・オブジェクト（つまり$dbh）を持ちます。そのハンドル・オブジェクトがデータベース関連のメソッドを呼び出すために使われます。
ほとんどのデータは文字列(string)としてPerlスクリプトに返されます（Null値はundefとして返されます）。これにより任意の桁数の数値データを精度を落とすことなく扱うことができます。文字列を数値として扱う際に、Perlが同じ精度を保たないかもしれないということに注意してください。
日付(Date)、時刻(Time)は、対応するデータベース・エンジンのネイティブなフォーマットの文字列として返されます。時間帯の影響はデータベース／ドライバに存します。
Perlスクリプトは文字列のなかにあるバイナリ・データをサポートします。DBIはバイナリデータを変更することなく、ドライバとやりとりします。そのようなバイナリデータをどのように扱いたいのかを決めることはドライバの実装者次第です。
複数の文字セットを理解する多くのデータベースはデフォルトのグローバル文字セットを持ちます。データベースに格納されるテキストは、その文字セットで格納される、あるいは格納されなければなりません；もしそうでなければ、そのデータを挿入したデータベースまたはアプリケーションでの間違いでしょう。テキストが取り出されるとき、それは自動的におそらくは地域に合わせてクライアントの文字セットに、変換されるべきです。ドライバは、その動きを得るためにフラグを設定する必要があれば、そうしなければなりません；アプリケーションがそうするように要求するべきではありません。
データベース、ドライバによってはそれをサポートしているとしても（特にSybaseとSQL Server）、複数のSQL文は１つのステートメントハンドル（$sth）に結び付けられないかもしれません。
このバージョンのDBIでは順序通りでないレコードの読み込みはできません。いいかえればレコードは、データベースが返してきた順序にしか取り出すことはできませんし、一度取り出されると忘れ去られてしまいます。
位置づけての更新、削除をDBIは直接サポートしていません。その代わりとしてCursorName属性の説明をご覧ください。
各ドライバを実装する開発者は、使いやすいと思えば、プライベートな関数や属性を自由に提供することができます。プライベートなドライバ関数はDBIのfunc() メソッドを使って呼び出すことができます。プライベートなドライバ属性は標準の属性とまったく同じようにアクセスすることができます。
多くのメソッドはオプションとして\%attrパラメータを受け取ります。これを使ってドライバが実装しているメソッドに情報を渡すことができます。特に記述されていなければ、\%attrパラメータは特定のヒントを渡す場合にのみ使用されます。普通は\%attrパラメータを無視するかundefを渡すことができます。
DBIパッケージとその下のパッケージ(DBI::*) は、DBI拡張によって予約されてます。そして関連するモジュールはDBIx::名前空間(http://www.perl.com/CPAN/modules/by-module/DBIx/をご覧下さい）を使います。DBD::で始まるパッケージ名はDBIデータベースドライバによって使うように予約されています。DBIまたは各DBDによって使われるすべての環境変数は"DBI_"または"DBD_"で始まります。
属性の名前に使われる文字の大文字／小文字の区別は、DBIスクリプトの移植性(portability)において重要で大きな役割を果たしています。属性の名前が大文字か小文字かによって、名前と値を誰が決めたのかを示すのに使われています。
名前の大文字／小文字 |
説 明 |
|---|---|
| 大文字のみ(UPPER_CASE) | 標準。 つまりX/Open, SQL92 など(移植性あり） |
| 混合（MixedCase) | DBI API(移植性性あり） アンダースコア(_)は使わない |
| 小文字のみ(lower_case) | ドライバもしくはエンジンに特有 （移植性なし） |
最も重要なのはドライバ開発者はプライベートな属性を定義するとき、小文字の属性しか使ってはいけないといことです。プライベートな属性の名前は、ドライバ名もしくは適切な略語からはじならなければなりません。(例えば ora_ はOracle, ing_ はIngresなど).
ドライバ識別接頭辞の登録：
ad_ DBD::AnyData ado_ DBD::ADO best_ DBD::BestWins csv_ DBD::CSV db2_ DBD::DB2 f_ DBD::File file_ DBD::TextFile ib_ DBD::InterBase ing_ DBD::Ingres ix_ DBD::Informix msql_ DBD::mSQL mysql_ DBD::mysql odbc_ DBD::ODBC ora_ DBD::Oracle pg_ DBD::Pg proxy_ DBD::Proxy rdb_ DBD::RDB sapdb_ DBD::SAP_DB solid_ DBD::Solid syb_ DBD::Sybase tdat_ DBD::Teradata tuber_ DBD::Tuber uni_ DBD::Unify xbase_ DBD::XBase
大半のDBIドライバではデータベース・エンジンとのやりとりに、それぞれのSQL（構造化問い合せ言語）を使うことが要求とします。 以下のリンクではSQLについての役立つ情報や他のリンクを提供しています。:
http://www.altavista.com/query?q=sql+tutorial http://www.jcc.com/sql_stnd.html http://www.contrib.andrew.cmu.edu/~shadow/sql.html
DBI自身は特定の言語を使うことを必須とも必要ともしていません；言語から独立しています。ODBC の用語でいうとDBI は"パススルー"モード（='pass-thru' mode）にあたります。各ドライバはそうでないかもしれません。 唯一必要なことは、prepare または do メソッドへの最初の引数として渡される問い合せまたはその他の文は、文字による１つの文字列として表現されなければならないことです。
RDBMSとSQLの本当の歴史についての興味深いこぼれ話が、実際にそれをやった人達からだされています：
http://ftp.digital.com/pub/DEC/SRC/technical-notes/SRC-1997-018-html/sqlr95.html
をご覧下さい。SQLの歴史については"And the rest"と"Intergalactic dataspeak"リンクを追ってみてください。
ある種のドライバはプレースホルダとバインド値をサポートしています。プレースホルダはパラメータ・マーカーとも呼ばれ、データベース・ステートメントの中の値が後で、準備(prepare)されたステートメントが実行される前に与えられることを示すために使われます。例えば、以下のようにして、SALESテーブルに行を挿入することができます。
INSERT INTO sales (product_code, qty, price) VALUES (?, ?, ?)
あるいはPRODUCTSテーブルから製品の説明(description)を取得できます
SELECT description FROM products WHERE product_code = ?
?という文字がプレースホルダです。実際の値とプレースホルダとの結びつけがバインドで、値はバインド値として呼ばれます。
プレースホルダをSQLのLIKE修飾子と使うばあいには、プレースホルダは文字列全体を置き換えることを忘れてはいけません。そのため「... LIKE ? ...」を使い、プレースホルダにバインドする値にワイルドカードとなる文字をすべて入れなければなりません。
Null値
NULL値を示すために未定義の値またはundefが使われます。しかしSELECT文を修飾するためにNULL値を使う場合には特に注意が必要です。以下のような場合について考えてみましょう：
SELECT description FROM products WHERE product_code = ?
undef (NULL) をプレースホルダにバインドしても、NULLのproduct_codeを持つ行は何も選択されません！この理由については、使用しているデータベース・エンジンのSQLのマニュアルまたはSQLの解説書をご覧ください。明示的にNULLをSELECTするためには"where product_code is NULL"とする必要があります。汎用的にするには：
... WHERE (product_code = ? OR (? IS NULL AND product_code IS NULL))
とし両方のプレースホルダに同じ値をバインドします。
パフォーマンス
プレースホルダを使わなければ、上記のINSERT文は挿入する値をリテラルで入れなければなりませんし、各行毎に再準備(re-prepare)し、再実行(re-execute)しなければいけません。プレースホルダを使うと、INSERT文を準備(prepare)する必要があるのは１回だけです。各行のバインド値はexecuteメソッドを呼び出すときに与えることができます。各行毎に再準備(re-prepare)する必要がなくなるので、アプリーケーションは通常、何倍も速くなります。 以下に例を示します：
my $sth = $dbh->prepare(q{
INSERT INTO sales (product_code, qty, price) VALUES (?, ?, ?)
}) or die $dbh->errstr;
while (<>) {
chomp;
my ($product_code, $qty, $price) = split /,/;
$sth->execute($product_code, $qty, $price) or die $dbh->errstr;
}
$dbh->commit or die $dbh->errstr;
詳細は execute および bind_param をご覧ください。
この例では、SQL文のなかで使われるかもしれないクォートの対応が崩れないよう、q{...} スタイルのクォートを使っています。 文字列に解釈して欲しい変数がある場合には、qq{...} のようなダブル・クォートを使うことができます。詳細については perlop "Quote and Quote-like Operators" （＝クォートおよびクォートのような演算子）をご覧ください。
Perlの変数をSELECT文の出力カラムに結びつけるために使われる bind_column メソッドもご覧ください。
このセクションでは、DBIクラス・メソッド、ユーティリティ関数そして一般的なDBIハンドルに関連する動的属性についてカバーします。
以下のSQL標準型定数は個別にインポートしたり、特殊な :sql_types タグですべてをインポートすることができます：
SQL_CHAR SQL_NUMERIC SQL_DECIMAL SQL_INTEGER SQL_SMALLINT SQL_FLOAT SQL_REAL SQL_DOUBLE SQL_VARCHAR SQL_DATE SQL_TIME SQL_TIMESTAMP SQL_LONGVARCHAR SQL_BINARY SQL_VARBINARY SQL_LONGVARBINARY SQL_BIGINT SQL_TINYINT SQL_WCHAR SQL_WVARCHAR SQL_WLONGVARCHAR SQL_BIT SQL_ALL_TYPES
可能な使い方についてはtype_info, type_info_all, そして bind_param をご覧ください。
DBIクラスによって以下のメソッドが提供されています：
connect
$dbh = DBI->connect($data_source, $username, $password)
or die $DBI::errstr;
$dbh = DBI->connect($data_source, $username, $password, \%attr)
or die $DBI::errstr;
要求された$data_sourceへの接続またはセッションを確立します。接続が成功するとデータベース・ハンドル・オブジェクトを返します。接続を終わらせるためには $dbh->disconnectを使います。
connectが失敗したら（下記をご覧下さい）undefを返し、 $DBI::err、$DBI::errstrを設定します ($! 等は設定しません)。一般的にはconnectの戻りステータスを確認し、失敗していたら$DBI::errstrを表示します。
DBI経由で、複数のデータベースに対しての複数のドライバを使って、同時に複数接続することができます。単純に各データベース毎にconnect を呼び出し、返されたデータベース・ハンドルのコピーをとっておいてください。
$data_sourceの値は'dbi:ドライバ名:'で始まらなければなりません。ドライバ名が接続ために使われるドライバを示します。
(大文字、小文字は区別されます).
便宜上、$data_source
フィールドが未定義あるは空だった場合、DBIはこの値を環境変数DBI_DSNの値で置換します。
ドライバ名の部分だけが空だった場合(つまり$data_sourceの始まりが
'dbi::') 、環境変数DBI_DRIVERが使われます。もし変数も設定されていなければconnectは死にます(die)。
$data_source 値の例:
dbi:DriverName:database_name dbi:DriverName:database_name@hostname:port dbi:DriverName:database=database_name;host=hostname;port=port
ドライバ名の後ろにつく文字列については標準はありません。各ドライバは欲しい書き方をどんなものでも自由に使うことができます。 DBIが要求するのは、すべての情報が１つの文字列として与えられることだけです。使っているドライバが要求している書き方の説明の説明については、そのドキュメントを調べなければなりません。（ドライバの作者が$data_sourceの書き方を定義する必要がある場所では、上記の最後の例で示したようなODBC形式に従うことが推奨されています。）
環境変数DBI_AUTOPROXYが定義されていれば（そして
$data_source のデータソースが
'Proxy'でなければ)、接続要求は自動的に以下のように変更されます：
dbi:Proxy:$ENV{DBI_AUTOPROXY};dsn=$data_source
そしてDBD::Proxyモジュールに渡されます。DBI_AUTOPROXYは、通常"hostname=...;port=..."となります。詳細については DBD::Proxyドキュメント をご覧ください。
$username または $password
が未定義（あるいは単に空）ならば、DBIはそれぞれ環境変数
DBI_USER と DBI_PASS
の値で置き換えます。その環境変数が定義されてなければ、DBIは警告(warn)します。しかしながら、これらの環境変数を毎日使うことは、セキュリティ上の理由からお勧めしません。この機能は基本的にテストを簡単にすることを目的としています。
DBI->connect は、まだインストールされていないドライバを自動的にインストールします。ドライバのインストールは適切なドライバ・ハンドルを返すか、"install_driver"という文字列と基になった問題が入ったエラーメッセージとともに死んで(die)しまうかのどちらかです。そのためDBI->connect はドライバ・インストールの障害のときには死んで(die)、接続の障害のときにはundefを返すだけです。そのときには$DBI::errstrにエラーの情報が入っています。
$data_source 引数 ( 'dbi:...:'
という接頭辞をとったもの）と$username
、$password
の引数は、処理のためドライバに渡されます。DBI
はこれらのフィールドの内容の解釈について何も定義していません。ドライバは$data_source,
$username, $password
のフィールドを、どんなふうにも自由に解析することができます。そしてアクセスされるエンジンに合わせて、いかなるデフォルトも設定することができます。
(例えばOracleでは、データソースが指定されていなければ、環境変数
ORACLE_SID と TWO_TASKを使います)。
各コネクションのAutoCommit
と PrintError
属性のデフォルトは"on" です。(詳細は
AutoCommit と PrintError をご覧ください)。
しかしながら、デフォルトにまかませるよりも明示的にAutoCommitを定義することが強く推奨されます。DBIの将来のバージョンではAutoCommitが明示的に定義されていなければ警告を発するかもしれません。
\%attr パラメータを使って、 PrintError, RaiseError, AutoCommit などの属性のデフォルト値を変更することができます。例:
$dbh = DBI->connect($data_source, $user, $pass, {
PrintError => 0,
AutoCommit => 0
});
$data_sourceパラメータの中で接続属性の値を定義することもできます。例：
dbi:DriverName(PrintError=>0,Taint=>1):...
この方法で指定される各属性値は、connectへの\%attrパラメータを介して指定された値とぶつかっても優先されます。
dbi_connect_method属性は接続を確立するさいにどちらのドライバ・メソッドが呼ばれるべきかを指定するために使われます。これには'connect'、'connect_cached'、あるいは'Apache::DBI::connect'（これはApacheで実行されたときには自動的にデフォルトになります）のようなある特別なケースが使えます。
古いDBIスクリプトとの移植のために、ドライバの名前をconnectの４番目の引数として(\%attrの代わりに）、ドライバに指定することができます:
$dbh = DBI->connect($data_source, $user, $pass, $driver);
このconnectの"旧スタイル"形式では、$data_sourceは"dbi:ドライバ名:"で始まってはいけません。（もしそうであれば、埋め込まれたドライバ名は無視されます）。この古い形式のconnectでは、$dbh->{AutoCommit} 属性は未定義、$dbh->{PrintError}はオフ、そしてDBI_DSNが定義されていなければ、古いDBI_DBNAME環境変数がチェックされます。この"旧スタイル"のconnectはDBIの将来のバージョンで撤廃されるであろうということに用心してください。
connect_cached
NEW $dbh = DBI->connect_cached($data_source, $username, $password)
or die $DBI::errstr;
$dbh = DBI->connect_cached($data_source, $username, $password, \%attr)
or die $DBI::errstr;
connect_cachedは返されるデータベース・ハンドルが与えられたパラメータと関連付けられてハッシュにも格納されるという点を除けば、connectに似ています。同じパラメータ値でconnect_cachedがもう一度呼ばれると、それがまだ適切であれば、キャッシュされた対応する$dbhが返されます。すでに切断されていたり、pingメソッドが失敗したら、キャッシュされたデータベース・ハンドルは新しい接続で置きかえられます。
このメソッドの動きは、Apache::DBIによって実装されている永続接続の動きとは多くの点で異なることに注意してください。
キャッシュは、あるアプリケーションによっては便利かもしれませんが、問題もおこすかもしれませんし、注意して使わなければなりません。このメソッドの正確な動きは変更される可能性が高いので、なんらかの製品アプリケーションで使うつもりであれば、 dbi-usersメーリング・リストであなたの必要性を議論するべきです。
キャッシュはCachedKids属性を介してアクセス（そしてクリア）することができます。
available_drivers@ary = DBI->available_drivers; @ary = DBI->available_drivers($quiet);
@INCのディレクトリからDBD::*モジュールを検索して、使用可能なドライバのリストを返します。デフォルトでは、先に見つかったディレクトリにある同じ名前のものにより、隠されてしまうドライバがあれば警告します。警告を抑止するには$quietをTRUEにします。
data_sources@ary = DBI->data_sources($driver); @ary = DBI->data_sources($driver, \%attr);
指定された名前のドライバで使うことができるデータソース（データベース）のリストを返します。$driverが空もしくはundefであれば、環境変数DBI_DRIVERの値が使われます。
まだロードされていなければ、ドライバはロードされます。もしドライバのローディングが失敗したら、"install_driver"という文字列とそこにある問題が入ったエラーメッセージでdieすることに注意してください。
データソースはconnect メソッドに渡すのに適したな形式で返されます。（つまり接頭辞"dbi:$driver:"が入ります。）
多くのドライバが利用できるデータソースを調べる方法を持っていないということに注意してください。これらのドライバは空もしくは不完全なリストが返したり、あるいは接続されたデータベース・ハンドルのようなドライバ特有の属性が与えられることを必要とするかもしれません。
traceDBI->trace($trace_level) DBI->trace($trace_level, $trace_filename)
trace DBIクラス・メソッドを使えば、すべてのハンドルについてのDBI トレース情報を取得できるようになります。特定のハンドルについてのトレース情報を取得するには、別の場所で説明される同様の $h->trace メソッドを使ってください。
トレース・レベル($trace_level)は以下のようになります：
0 - トレースを不可
1 - DBIメソッド呼び出しの戻りを結果またはエラーと一緒にトレース
2 - メソッドのエントリをパラメータと一緒に、戻りを結果と一緒にトレース
3 - 上記と同様。ドライバからのいくつかのハイレベルな情報と
DBIからのいくつかの内部情報を追加。
4 - 上記と同様。ドライバからのさらに詳細な情報を追加。
スレッド化されたPerlを使っているときにはDBI mutex情報も含む。
5 以上 - 上記と同様。しかし値にしたがってさらに目に付かない情報。
最初にトレース出力は標準エラー出力(STDERR)に書き出されます。
$trace_filename が指定されたら、ファイルが追記(append)モードでオープンされ、（他のハンドルからものも含めて）すべてのトレース出力がそのファイルに出力されます。それ以降、$trece_filenameが指定せずにtraceを呼び出しても、出力が送られるファイルは変わりません。$trece_filenameが未定義であれば、トレース出力は標準エラー出力(STDERR)に送られ、それまでのトレース・ファイルは閉じられます。traceメソッドは前のトレースレベルを返します。
環境変数DBI_TRACEについての情報は、$h->traceと$h->trace_msg メソッドや デバッグ方法セクションもご覧ください。
前のセクションで一覧ししたメソッドに加えて、DBIパッケージはこれらのユーティリティ関数も提供しています：
neat$str = DBI::neat($value, $maxlen);
与えられた文字列を整然と（そしてきれいに）整えられた文字列を返します。
文字列はクォーテーションで囲まれます、しかし文字列の中のクォーテーションはエスケープされません。数値であるとわかっている値はクォーテーションで囲まれません。未定義（NULL)値は（クォートなしで） undef で表されます。表示できない文字は点(.)で置き換えられます。
変換結果の文字列が$masxlenよりも長ければ、文字列は$maxlen-4の長さに切り詰め、"...'"が後ろにつけられます。$maxlenが0またはundefであれば、$DBI_neat_maxlen（デフォルトは400）が代りにデフォルトになります。
この関数は人の目にわかりやすいように値の形式を整えるように考えられています。これはDBI内部で trace 出力に使われています。通常データベースが利用するよう、値の形を整えるために使ってはいけません( quote もご覧ください)。
neat_list$str = DBI::neat_list(\@listref, $maxlen, $field_sep);
リストの各要素に DBI::neat を呼び出し、その結果を$field_sepでつなげた結果の文字列を返します。$field_sepのデフォルトは","です。
looks_like_number@bool = DBI::looks_like_number(@array);
リストの各要素について数値に見えばTRUEを返します。各要素が数値に見えなければFalseを返します。各要素が未定義あるいは空であれば、undefもしくは空を返します。
属性がメソッド呼び出しと同様のところでは、すべての関連するドキュメンテーションでそのメソッド呼び出しを参照してください。
警告: 便宜上、これらの属性を用意していますが、限界があります。特にこれらの有効な時間は長くありません：最後に使われたハンドルに関連付けられているために、それらを「設定した」メソッドを呼び出したすぐ後にしか使うことができません。少しでも疑問があれば、対応するメソッド呼び出しを使ってください。
$DBI::err$h->err と同じ
$DBI::errstr$h->errstr
と同じ $DBI::state$h->state
と同じ $DBI::rows$h->rows
と同じ。 どうかrowsメソッドのドキュメントをご覧ください。
$DBI::lasth以下のメソッドはDBIハンドルのすべてのタイプに使うことができます。
err$rv = $h->err;
最後のドライバ関数呼び出しについてネィティブなデータベース・エンジン・エラーコードを返します。コードは典型的には整数ですが、それを想定するべきではありません。
DBI はほとんどのDBIメソッドを呼び出す前に $h->errをundefにリセットするので、この値は短い間だけ有効です。またほとんどのドライバはすべてのハンドルにまたがって同じエラーコードを共有するので、あるハンドルに対してメソッドを呼び出すと、典型的には、そのドライバの子供である他のすべてのドライバについてのエラーコードをリセットするでしょう。
個々のエラーについてテストする必要があり、そして、あなたのプログラムが他のデータベース・エンジンに対して移植可能にする必要があれば、それらすべてのエンジンについて対応するエラーコードが何かを判定し、それらのすべてについてテストする必要があります。
errstr$str = $h->errstr;
最後のドライバ関数呼び出しについて、ネイティブなデータベース・エンジン・エラーメッセージを返します。上記で説明したerrメソッドと同じ有効期間の問題を持っています。
state$str = $h->state;
エラーコードを標準のSQLSTATE5文字形式で返します。ある正常コード00000は、0(false)に変換されてしまうことに注意してください。もしドライバがSQLSTATEをサポートしていなければ（ほとんどがサポートしていないのですが）、stateはすべてのエラーについてS1000（一般エラー）を返します。
ドライバはstateでどのような値を返すことも自由です。例えば警告コード。上記のerrメソッドを介してtrueを返すことにより宣言されるエラーでなかったとしても。
trace$h->trace($trace_level); $h->trace($trace_level, $trace_filename);
トレース・レベルをtrace メソッドを使って設定すると、そのハンドルについて(そして、その後そのハンドルから作られるハンドルついても）DBIトレース情報を取得できます。
トレース・レベル１が何が起こったのかの単純な概要のために最も向いています。トレース・レベル２はトレースの一般的な目的にはよい選択です。レベル３そしてそれ以上（最大９まで）は、DBIとドライバの"内部"を見る必要があるとき、特定の問題を調べるために予約されています。そして$trace_levelを0に設定するとトレースは止まります。
トレース出力はとても詳細で、普通とても役に立ちます。トレース出力の多くが neat 関数を使って形式を整えています。このためトレース出力での文字列は編集され、切り捨てられているかもしれません。
トレース出力は最初に標準エラー出力(STDERR)に書き出されます。
$trace_filename が指定されたら、ファイルが追記(append)モードでオープンされ、（他のハンドルからものも含めて）すべてのトレース出力がそのファイルに出力されます。それ以降、$trece_filenameが指定せずにtraceを呼び出しても、出力が送られるファイルは変わりません。$trece_filenameが未定義であれば、トレース出力は標準エラー出力(STDERR)に送られ、それまでのトレース・ファイルは閉じられます。
trace_msg$h->trace_msg($message_text); $h->trace_msg($message_text, $min_level);
$h またはDBI全体でトレースが有効となっているならば、
$message_text をトレース・ファイルに書き出します。DBI->trace_msg($msg) と呼び出すこともできます。
traceをご覧ください。
もし$min_levelが定義されていれば、トレース・レベルがそのレベル以上である場合だけメッセージが出力されます。$min_levelのデフォルトは1です。
func$h->func(@func_arguments, $func_name);
func メソッドにより、ドライバが実装しているプライベートな標準でなく、移植できないメソッドを呼び出すことができます。関数名が最後の引数で与えられることに注意してください。
このメソッドはストアド・プロシージャの呼び出しに、直接は関係していません。 ストアド・プロシージャ呼び出しは、いまのところDBIによって定義されていません。DBD::Oracleのようにいくつかのドライバが移植できない形でサポートしています。詳細についてはドライバのドキュメントをご覧ください。
これらの属性はDBIの全種類のハンドルについて共通です。
属性によっては、子供に継承されるものもあります。つまり新しく作られるステートメント・ハンドルでの継承される属性の値は、その親となるデータベース・ハンドルでの値と同じになります。新しいステートメント・ハンドルでの属性を変更しても親のデータベース・ハンドルには影響を与えませんし、データベース・ハンドルの属性を変更しても、既存のステートメント・ハンドルには影響を与えません。新しく作られるものだけです。
ドライバ特有のプライベートな属性（これらの名前は小文字ではじまります）を除いては、決められていない属性を設定あるいは取得しようとすると致命的なエラーになります。
例：
$h->{AttributeName} = ...; # 設定/書込
... = $h->{AttributeName}; # 取得/読込
Warn
(boolean, 継承される)Active
(boolean, read-only)Kids
(integer, read-only)ActiveKids
(integer, read-only)CachedKids
(hash ref)CompatMode
(boolean, inherited)InactiveDestroy
(boolean)データベース・ハンドルにとっては、この属性はdisconnectメソッドの明示的な呼び出しを不可能にしません、破壊(DESTROY)から暗黙の呼び出しだけを不可能にします。
PrintError
(boolean, inherited)warn("$class $method failed: $DBI::errstr")を実行させます。
$class にはドライバ・クラス、 $method
には失敗したメソッドが入ります。例えば
DBD::Oracle::db prepare failed: ... ここにエラーテキスト ...
デフォルトでは、DBI->connect はPrintError を"on"に設定します。
そうしたいのであれば、$SIG{__WARN__}ハンドラやCGI::Carp、CGI::ErrorWrapのようなモジュールを使って、警告を捕らえ処理することができます。
RaiseError
(boolean, inherited)die("$class $method failed: $DBI::errstr")を実行させます。$class
にはドライバ・クラス、 $method
には失敗したメソッドが入ります。例えばDBD::Oracle::db prepare failed: ... ここにエラーテキスト ...
もしRaiseError
をonにしたら、通常は PrintError
をoffにしたいでしょう。もし PrintError もonであれば、最初に
PrintError
が行われます（自然に）。
典型的には RaiseError
は、例外を捕らえるために、捕らえた例外を取り扱うためのif($@)
{ ... } ブロックが後ろについた、eval { ... }と一緒に使われます。そのevalブロックでは、解析しレポートするのに$DBI::lasth変数が便利です。例えば$DBI::lasth->{Type}や$DBI::lasth->{Statement}のように。
一時的にRaiseErrorをoffに切り替えたいのであれば（例えば障害が発生しやすいライブラリ関数の内部など）、以下のようにすることをお勧めします：
{
local $h->{RaiseError}; # ローカル化し、このブロックのためにoffに切り替え
...
}
そのブロックからどのように抜けたのかは関係なく、元の値は自動的に、信頼性を持ってPerlにより保存されます。PrintErrorも含めて、他の属性についても同じロジックが適用されます。
残念ながら5.004_04までのPerlでは、これを使うことはできません。過去のものとの互換性を保つためには代わりに eval { ... } を使います。
ShowErrorStatement
(boolean, inherited) NEWRaiseError
と PrintErroによって生成されるエラーメッセージに追加させます。ステートメント・ハンドルでのエラーに加えて、データベース・ハンドル・メソッド prepare() とdo() についてのみ適用されます。（追加されるテキストの正確なフォーマットは変更されるかもしれません）
FetchHashKeyName
(string, inherited) NEWfetchrow_hashref()
がハッシュキーのためにフィールド名を取り出すさいに使用する属性名を指定するために使われます。歴史的な理由からデフォルトは'NAME'ですが、あなたの好みに合わせて、'NAME_lc' または
'NAME_uc' に設定することをお勧めします。これはドライバとデータベース・ハンドル（原文ではtable）にのみ設定することができます。ステートメント・ハンドルでは、値はprepare()
された時点で凍結されます。 ChopBlanks
(boolean, inherited)デフォルトはfalseです。（しかしデフォルトが変更される可能性があります）。特定の動きが必要なアプリケーションは、この属性を必要な値に設定します。エミュレーション・インターフェースではエミュレートしているインターフェースの動きに合わせて、この属性を設定しなければなりません。
ドライバはこの属性をサポートしなければならないわけではありません。しかしサポートしていないドライバはこの属性の値としてundefを返すようにしなければなりません。
LongReadLen
(unsigned integer, inherited)値が０は、"長い"データは自動的に取り出されないことを意味します。(LongReadLenが0のとき、"長い"フィールドの値はundefになります).
デフォルトは通常０(ゼロ）バイトですが、ドライバによって違うかもしれません。"長い"フィールドを取り出すアプリケーションは、取り出される「長い」フィールドの最大長よりもちょっとだけ大きい値を、この値に設定しなければなりません。
ある種のデータベースは"長い"タイプを16進のペアでエンコードして返すも場合があります。これらのタイプについては、LongReadLenはエンコードされた文字列の2倍になった長さではなく、基になっているデータ長に関係します。
既にprepareされた後に、ステートメント・ハンドルのLongReadLenを変更しても、通常、何も影響を与えません。そのため普通、prepareを呼び出す前に、$dbhに対してLongReadLenを設定します。
ここに使われる値がアプリケーションによって使われるメモリに対して直接的な影響を与えることに注意してください。そのため、あまり気前よくならないようにしてください。
切捨ての動きについては LongTruncOk をご覧ください。
LongTruncOk
(boolean, inherited)デフォルトでは LongTruncOk はfalseです。そのため切り捨てられる必要がある"長い"値を取り出すと取り出し失敗となります。 (アプリケーションは、エラーの場合、取り出しループの後で、エラーを常に確実にチェックしなければなりません。０除算、"長い"フィールドの切り捨てなどによって取り出しが早く終わってしまうことがあります）
LongTruncOkがfalseのとき、"長い"フィールドにより取り出しが失敗しても、多くのドライバでは先の行を取り出すことができます。
LongReadLen. もご覧ください。
Taint
(boolean, inherited)現在は取り出されたデータだけが汚染されているとしています。将来のバージョンでは他のDBIメソッド呼び出しの結果そして取り出された属性の値も同様に汚染されているとするかもしれません。今のうちに細心の注意を払わない限り、その変更はアプリケーションを壊しかねません。もしDBIをTaintモードで使うのであれば、変更のためにあなたの経験と提案を報告してください。
private_*このセクションはデータベース・ハンドルに関連するメソッドと属性についてカバーします。
以下のメソッドがDBIデータベース・ハンドルに指定されています：
do$rc = $dbh->do($statement) or die $dbh->errstr; $rc = $dbh->do($statement, \%attr) or die $dbh->errstr; $rv = $dbh->do($statement, \%attr, @bind_values) or ...
１つのステートメントをprepareし、executeします。影響を受けた行の数を、またエラーであればundefを返します。-1は行の数が分からないか使用できないことを意味します。
このメソッドは典型的には、（ドライバの制限により）前もってprepareされることがなかったり、繰り返し実行しないSELECT以外の文でとても有効です。ステートメント・ハンドルを返さない（そのために何もデータを取り出せない）ので、 SELECT文では使うべきではありません。
デフォルトのdoメソッドは、論理的には以下のものと同じです：
sub do {
my($dbh, $statement, $attr, @bind_values) = @_;
my $sth = $dbh->prepare($statement, $attr) or return undef;
$sth->execute(@bind_values) or return undef;
my $rows = $sth->rows;
($rows == 0) ? "0E0" : $rows; # エラーでなければ常にTRUEを返す
}
例:
my $rows_deleted = $dbh->do(q{
DELETE FROM table
WHERE status = ?
}, undef, 'DONE') or die $dbh->errstr;
プレースホルダとバインド変数（@bind_values）
を do
メソッドでつかうと、 $statementの中の変数を正しくクォートしなくてもよくなるためにとても便利です。しかしもしステートメントを何度も実行するのであれば、代わりに一度prepare し、何度もexecuteするほうがより効率的です。
この例で使われているq{ ...} 形式のクォートは、ステートメントで使われているかもしれないクォートの対応を壊されないように使われています。 文字列に入っている変数を解釈したい場合には、ダブル・クオートのようなqq{...} 演算子を使います。詳細はperlop "Quote and Quote-like Operators'をご覧ください。
selectrow_array@row_ary = $dbh->selectrow_array($statement); @row_ary = $dbh->selectrow_array($statement, \%attr); @row_ary = $dbh->selectrow_array($statement, \%attr, @bind_values);
このユーティリティー・メソッドは、prepare, execute fetchrow_array を一回にまとめておこないます。リスト・コンテキストで呼ばれれば、そのステートメントによって返される最初の行を返します。スカラ・コンテキストでは、最初の行の最初のフィールドを返します。 $statementパラメータはすでにprepareされているステートメント・ハンドルにすることができます。その場合、prepareは飛ばされます。
いずれかのメソッドがエラーとなり、RaiseError が設定されていなければ、selectrow_arrayは空のリストを返します。
スカラ・コンテキストでは、selectrow_arrayは最初の行の最初のフィールドを返します。対応する行がないかエラーが発生したたならば、undefが返されます。このundefは最初にフィールドの値がNULLであったために返されるundefと区別することができないので、selectrow_arrayをスカラ・コンテキストで呼び出すときには注意が必要です。
selectall_arrayref$ary_ref = $dbh->selectall_arrayref($statement); $ary_ref = $dbh->selectall_arrayref($statement, \%attr); $ary_ref = $dbh->selectall_arrayref($statement, \%attr, @bind_values);
このユーティリティー・メソッドは、prepare, execute fetchall_arrayref を一回にまとめておこないます。取り出されたデータの各行の配列へのリファレンスが入った配列へのリファレンスを返します。
$statementパラメータを既にprepareされているステートメント・ハンドルにすることができます。その場合、prepareは飛ばされます。これは何回もステートメントが実行する予定であればお勧めです。
fetch以外のいずれかのメソッドがエラーとなり、RaiseError が設定されていなければ、selectall_arrayrefはundefを返します。もしfetchが失敗し、RaiseErrorが設定されていなければ、それまでに取り出したデータをなるべく多く返します。それを捕らえるために$DBI::errをチェックすべきです。
selectall_hashref$ary_ref = $dbh->selectall_hashref($statement); $ary_ref = $dbh->selectall_hashref($statement, \%attr); $ary_ref = $dbh->selectall_hashref($statement, \%attr, @bind_values);
このユーティリティー・メソッドは、prepare, execute fetchrow_hashref を一回にまとめておこないます。取り出されたデータの各行のためのフィールド名と値のペアが入ったハッシュへのリファレンスを返します。
$statementパラメータを既にprepareされているステートメント・ハンドルにすることができます。その場合、prepareは飛ばされます。これは何回もステートメントが実行する予定であればお勧めです。
fetchrow_hashref
以外のいずれかのメソッドがエラーとなり、RaiseError が設定されていなければ、selectall_hashrefはundefを返します。もし
fetchrow_hashref
が失敗し、RaiseErrorが設定されていなければ、それまでに取り出したデータをなるべく多く返します。それを捕らえるために$DBI::errをチェックすべきです。
selectcol_arrayref$ary_ref = $dbh->selectcol_arrayref($statement); $ary_ref = $dbh->selectcol_arrayref($statement, \%attr); $ary_ref = $dbh->selectcol_arrayref($statement, \%attr, @bind_values);
このユーティリティー・メソッドは、一回にprepare, execute,をまとめておこない、すべての行から１つのカラムからを取り出します。各行からの最初のカラムの値が入った配列へのリファレンスを返します。
$statementパラメータを既にprepareされているステートメント・ハンドルにすることができます。その場合、prepareは飛ばされます。これは何回もステートメントが実行する予定であればお勧めです。
fetch以外のいずれかのメソッドがエラーとなり、RaiseError が設定されていなければ、selectcol_arrayrefはundefを返します。もしfetchが失敗し、RaiseErrorが設定されていなければ、それまでに取り出したデータをなるべく多く返します。
prepare$sth = $dbh->prepare($statement) or die $dbh->errstr; $sth = $dbh->prepare($statement, \%attr) or die $dbh->errstr;
１つのステートメントを後でデータベースエンジンによって実行できるように準備し、ステートメント・ハンドル・オブジェクトへのリファレンスを返します。
返されるステートメント・ハンドルはステートメントの属性を取得したり、 execute メソッドの呼び出しに使われます。ステートメント・ハンドル メソッドをご覧ください。
準備されたステートメントという考えが無いドライバでは、通常、返されるハンドルにステートメントを保存し、executeが呼ばれたらそれを処理します。そのようなドライバは$sth->{NUM_OF_FIELDS}のようなステートメントについて有効な情報を$sth->execute が呼ばれるまでは、取得できることはまずありません。 移植可能なアプリケーションはこの点を注意する必要があります。
通常、DBIドライバはステートメントを解析しません (そうでなければ単純にプレースホルダを数えます)。ステートメントはデータベース・エンジンに直接渡されます、いわゆるパススルーモードです。 これは長所でも短所でもあります。よく言えば、使われているエンジンのすべての機能にアクセスすることができます。悪く言えば、簡単なエンジンを使っていれば制限されますし、エンジンをまたがって移植可能なアプリケーションを書こうとすれば、非常に注意する必要があります。
移植可能なアプリケーションは、まだ前のステートメントから結果を取り出している間に、新しいステートメントがprepareでき、そして／あるいは実行できると想定するべきではありません。
いくつかのコマンド・ライン型SQLツールは、セミコロンなどのステータスの終わりを示すために、ステートメント末尾文字（statement terminator)を使っています。通常そうした末尾文字をDBIで使われません。
prepare_cached$sth = $dbh->prepare_cached($statement) $sth = $dbh->prepare_cached($statement, \%attr) $sth = $dbh->prepare_cached($statement, \%attr, $allow_active)
$dbhに関連付けられたハッシュに保存されることを除いて
prepare と同様です。もし同じ$statementと%attrの値ででもう一度prepare_cachedが呼び出されると、データベース・サーバにコンタクトすることなく、対応する$sth
が返されます。
このキャッシングはある種のアプリケーションでは有効ですが、問題を起こしかねませんし、注意が必要です。現在、返されたキャッシュされている$sthがActiveであれば (つまりSELECT中で、まだ取り出すべきデータが残っている場合）、警告が出され、あなたに替わってfinishが行われます。警告は$allow_activeをtrueにすることにより抑止することができます。キャッシュにはCachedKids属性でアクセス（そしてクリア）することができます。
以下に可能なprepare_cachedの使用例を示します：
sub insert_hash {
my ($table, $field_values) = @_;
my @fields = sort keys %$field_values; # sortが必要
my @values = @{$field_values}{@fields};
my $sql = sprintf "insert into %s (%s) values (%s)",
$table, join(",", @fields), join(",", ("?")x@fields);
my $sth = $dbh->prepare_cached($sql);
return $sth->execute(@values);
}
sub search_hash {
my ($table, $field_values) = @_;
my @fields = sort keys %$field_values; # sortが必要
my @values = @{$field_values}{@fields};
my $qualifier = "";
$qualifier = "where ".join(" and ", map { "$_=?" } @fields) if @fields;
$sth = $dbh->prepare_cached("SELECT * FROM table $qualifier");
return $dbh->selectall_arrayref($sth, @values);
}
commit$rc = $dbh->commit or die $dbh->errstr;
データベースがトランザクションをサポートしていてAutoCommitがoffであれば、データベースに対する直近の一連の変更をコミット（永続化）します。
AutoCommitがonであれば、"commit ineffective with AutoCommit （AutoCommitによりcommitは無効）"という警告を起こします。
rollback$rc = $dbh->rollback or die $dbh->errstr;
データベースがトランザクションをサポートしていて、AutoCommitがoffであれば、データベースに対する直近の一連の変更をロールバックします（元に戻します）。
AutoCommitがonであれば、"rollback ineffective with AutoCommit （AutoCommitによりrollbackは無効）"という警告を起こします。
disconnect$rc = $dbh->disconnect or warn $dbh->errstr;
データベース・ハンドルをデータベースから切断します。disconnect は普通プログラムを終了するときにだけ使います。切断した後、ハンドルほとんど役に立ちません。
残念ながらdisconnectメソッドにより、トランザクションがどうなるかは決まっていません。ある種のデータベース・システム（Oracle、Ingressなど）は自動的に変更をコミットしますが、（Infromixなど）変更をロールバックするものもあります。AutoCommitを使わないアプリケーションはdisconnectを呼び出す前に、明確にcommitまたはrollbackをするべきです。
まだ接続していて、ハンドルへの参照がまったくなくなった場合、DESTROYメソッドによりデータベースは自動的に切断されます。各ドライバへのDESTROYメソッドはコミットされていない変更を元に戻すため、暗黙のうちにrollbackを呼び出します。これは 終了する前にPerlが単に各オブジェクトにDESTROYを呼び出すことによって、不完全なトランザクションがコミットされないということをことを保証するためにきわめて重要です。 同様に"グローバルな破壊"でのオブジェクトの破壊の順序は信頼できません。これは未定義です。
一般的に、切断する前に変更をコミットまたはロールバックしたいのであれば、切断する前に明示的にcommitまたはrollbackを呼び出すべきです。
Activeなステートメント・ハンドルがあるのにデータベースから切断すると警告を受けます。ステートメント・ハンドルは切断の前にクリア（破壊）されるか、そｌれぞれについてfinishメソッドが呼ばれるべきです。
ping$rc = $dbh->ping;
合理的で効率的な方法で、データベースサーバーが稼動しているか、接続が動いているかを判定しようとします。各ドライバはこの関数をそれぞれのデータベースに最も適切な方法で実装するべきです。
現在のデフォルトの実装は、実際には何もせず常にTRUEを返します。実際には、それは"0 but true"を返します、これはtrueですがゼロです。これにより返された値が本物なのか単なるデフォルトなのかがわかります。。ドライバはこのメソッドをデータベースのタイプにあったものでこのメソッドを上書きしなければなりません。
アプリケーションでこのメソッドを使うことはあまりないでしょう。使用例としては専門的なApache::DBIモジュールをご覧ください。
table_info
NEW$sth = $dbh->table_info( $catalog, $schema, $table, $type ); $sth = $dbh->table_info( $catalog, $schema, $table, $type, \%attr ); $sth = $dbh->table_info( \%attr ); # 古いスタイル
データベースに存在するテーブルやビューの情報を取得するために使われるActiveなステートメント・ハンドルを返します。
古いスタイルのインターフェースは、すべてのパラメータを以下の属性のいくつかあるいはすべてを持った属性ハッシュへのリファレンスで渡していました。
%attr = (
TABLE_CAT => $catalog # カタログ名の文字列値
, TABLE_SCHEM => $schema # スキーマ名の文字列値
, TABLE_NAME => $table # テーブル名の文字列値
, TABLE_TYPE => $type # テーブルタイプの文字列値
);
注意：選択条件のサポートはドライバによります。ドライバがこれらのうちの１つまたは複数をサポートしていなければ、あなたが尋ねた以上に受け取り、それを自分自身でフィルタリングしなければならないかもしれません。
引数$table、$schemaそして$table（訳者注：１つは$catalogか？）はデータベース／ドライバによって検索パターンを受け取るかもしれません。例えば：$table = '%FOO%';
$typeの値はテ結果セットで返されるーブルの１つまたは複数のデータ型のカンマ区切りのリストです。それぞれの値はオプションでクォートされるかもしれません。例えば：
$type = "TABLE"; $type = "'TABLE','VIEW'";
さらにドライバによっては以下の特殊なケースもサポートされているかもしれません。
$sth = $dbh->table_info('%', '', '');
データベースに存在するテーブルやビューの情報を取得するために使われるActiveなステートメント・ハンドルを返します。ハンドルは少なくとも以下のフィールドをこの順番で持っています。この後に他のフィールドが存在するかもしれません。
TABLE_CAT: テーブル・カタログ識別子。通常そうなのですが、データソースに適用できなければ、このフィールドがNULL（undef)です。テーブルに適用できなければ、このフィールドは空です。
TABLE_SCHEM: TABLE_NAME値が入っているスキーマの名前です。データソースに適用できなければ、このフィールドがNULL（undef)です。テーブルに適用できなければ、このフィールドは空です。
TABLE_NAME: テーブル（またはビュー、シノニムなど）の名前
TABLE_TYPE:「TABLE」「VIEW」「SYSTEM TABLE」「GLOBAL TEMPORARY」「LOCAL TEMPORARY」「ALIAS」「SYNONYM」、もしくはそのデータソース独自の型識別子のいずれか。
REMARKS: テーブルの説明。NULL（undef）かもしれません。
table_infoがすべてのテーブルについてレコードを返さないかもしれないことに注意してください。table_infoにより返されたかどうかに関係無く、アプリケーションではすべての適正なテーブルを扱うことができます。 tablesもご覧ください。
フィールドとその意味についての詳しい情報は以下のサイトをご覧ください：
http://msdn.microsoft.com/library/psdk/dasdk/odch6wqb.htm
そのURLが動いていなかったら、以下のMSDNサーチ機能を使ってください：
http://search.microsoft.com/us/dev/
そしてexact phraseオプションを使ってSQLTablesを検索してください。あなたが欲しいリンクはおそらくSQLTablesというものか、Data Access SDKの一部でしょう。
（非常に大きい）SQL/CLI 仕様の306ページもご覧ください：
http://www.jtc1sc32.org/sc32/jtc1sc32.nsf/Attachments/DF86E81BE70151D58525699800643F56/$FILE/32N0595T.PDF
primary_key_info
NEW$sth = $dbh->primary_key_info( $catalog, $schema, $table );
テーブルのためのプライマリキーとして設定されているカラムについての情報を取り出すために使われるActiveなステートメント・ハンドルを返します。引数に検索パターンは受け取りません（table_info()とは違って）
例：
$sth = $dbh->primary_key_info( undef, $user, 'foo' ); $data = $sth->fetchall_arrayref;
注意：$catalogのような、選択条件のサポートはドライバによります。もしドライバがカタログ そして／または スキーマをサポートしていなければ、これらの条件は無視されるかもしれません。
ステートメント・ハンドルは少なくとも以下のフィールドをこの順番で持っています。この後に他のフィールドが存在するかもしれません。
TABLE_CAT: カタログ識別子。よくあることですが、データソースに適用できなければ、このフィールドがNULL（undef)です。テーブルに適用できなければ、このフィールドは空です。
TABLE_SCHEM: スキーマ識別子。データソースに適用できなければ、このフィールドがNULL（undef)です。テーブルに適用できなければ、このフィールドは空です。
TABLE_NAME: テーブル識別子
COLUMN_NAME: カラム識別子.
KEY_SEQ: カラム順序番号（１始まり）注意：SQL/CLI.ではこのフィールドは ORDINAL_POSITION と名づけられています）.
PK_NAME: プライマリ・キー制約識別子。データソースに適用できなければNULL(undef)です。
フィールドとその意味についての詳細な情報については以下のサイトをご覧ください：
http://msdn.microsoft.com/library/psdk/dasdk/odch6fn7.htm
そのURLが動いていなかったら、以下のMSDNサーチ機能を使ってください：
http://search.microsoft.com/us/dev/
そしてexact phraseオプションを使ってSQLPrimaryKeysを検索してください。あなたが欲しいリンクはおそらくSQLPrimaryKeysというものか、Data Access SDKの一部でしょう。
現在のSQL/CLIワーキング・ドラフトの266ページもご覧ください：
http://www.jtc1sc32.org/sc32/jtc1sc32.nsf/Attachments/DF86E81BE70151D58525699800643F56/$FILE/32N0595T.PDF
primary_key
NEW@key_column_names = $dbh->primary_key( $catalog, $schema, $table );
primary_key_info()メソッドへの単純なインターフェースです。指定されたテーブルのプライマリ・キーを含むカラム目のリストを返します。このリストはプライマリキー・カラム順番号順に入ります。
tables
NEW@names = $dbh->tables; @names = $dbh->tables( $catalog, $schema, $table, $type ); @names = $dbh->tables( \%attr );
table_info()への単純なインターフェースです。テーブル、ビューの名前の単純なリストを返します。おそらく頭にスキーマがついてきます。このリストには何も修飾なしにSELECTステートメントで利用することができるすべてのテーブルが含まれます。
tablesがすべてのテーブルについてレコードを返さないかもしれないことに注意してください。tablesにより返されたかどうかに関係無く、アプリケーションではすべての適正なテーブルを扱うことができます。 table_info もご覧ください。
type_info_all
NEW$type_info_all = $dbh->type_info_all;
データベースあるいはドライバによりサポートされるデータ型についての情報が入った配列へのリファレンスを返します。配列及びその内容はリード・オンリーとして扱われなければなりません。
最初の要素は「名前=>インデックス」というペアのハッシュへのリファレンスです。その後の要素は、配列へのリファレンスで、１つずつがサポートされているデータ型になります。最初のハッシュが後に続く配列要素のフィールドの名前と順序を定義しています。例:
$type_info_all = [
{ TYPE_NAME => 0,
DATA_TYPE => 1,
COLUMN_SIZE => 2, # was PRECISION originally
LITERAL_PREFIX => 3,
LITERAL_SUFFIX => 4,
CREATE_PARAMS => 5,
NULLABLE => 6,
CASE_SENSITIVE => 7,
SEARCHABLE => 8,
UNSIGNED_ATTRIBUTE=> 9,
FIXED_PREC_SCALE => 10, # was MONEY originally
AUTO_UNIQUE_VALUE => 11, # was AUTO_INCREMENT originally
LOCAL_TYPE_NAME => 12,
MINIMUM_SCALE => 13,
MAXIMUM_SCALE => 14,
NUM_PREC_RADIX => 15,
},
[ 'VARCHAR', SQL_VARCHAR,
undef, "'","'", undef,0, 1,1,0,0,0,undef,1,255, undef
],
[ 'INTEGER', SQL_INTEGER,
undef, "", "", undef,0, 0,1,0,0,0,undef,0, 0, 10
],
];
もしその型の名前に違った書き方があったり、そして／または属性の違いで型のバリエーションがあったり（例えばAUTO_UNIQUE_VALUEがあったりなかったり、UNSIGNED_ATTRIBUTEあったりなかったりなど）すれば、1つ以上のフィールドがDATA_TYPEフィールドに同じ値をもつこともあることに注意してください。
行はまずDATA_TYPEで順に、そしてODBC SQLデータ型にどらくらい近く対応しているかによって近いほど先に順に並びます。
各フィールドの意味はtype_info
メソッドで説明しています。上記で示されているインデックスの値（例えばNULLABLE
=> 6）はここでの記述のためだけです。ドライバは違った順番で定義しているかも知れません。
このメソッドは通常、直接使われません。type_info メソッドがより使いやすいインターフェースを提供します。
'index'ハッシュが提供されていても、上記で定義されたインデックス・ハッシュでのすべてのフィールド名は常に上記で定義されたインデックス値を持ちます。これはインデックスハッシュを信頼する必要がないように、決められた動きです。これはキーの大文字小文字が決められていないので便利です。それは通常、ここで見てきたように大文字ですが、ドライバは名前を大文字、小文字のどちらで返しても自由です。ドライバは特別なドライバ専用の情報のカラムを返すのも自由です−しかしDBI/ODBC仕様の拡張のための空間をあけておくためにカラム・インデックス50から始めることをお勧めします。
type_info
NEW@type_info = $dbh->type_info($data_type);
１つあるいは複数の$data_typeの変形についての情報が入ったハッシュへのリファレンスのリストが返されます。リストはまずDATA_TYPEによって並べられ、そして各型がODBC SQLデータ型にどらくらい近く対応しているかによって近いほど先に順に並びます。スカラ・コンテキストで呼ばれれば、最初の（もっともよい）要素だけが返されます。
$data_type が未定義かSQL_ALL_TYPES
であれば、リストにはデータベースとドライバによってサポートされているすべてのデータ型が入ります。
もし$data_typeが配列リファレンスであれば、type_infoはその配列のいずれかが対応する最初の型のための情報を返します。
以下のハッシュのキーはDBIの他の部分と同じようにすべて大文字もしくは小文字で表わされます。( 命名規約と名前空間 をご覧ください）。以下に示す要素は間違い無く存在します：
文字列型であれば、これは文字列の最大サイズをバイトで表したもの。
日付(date)および期間(interval)型であれば、その値を表示するために必要な文字の最大数です。
0 - WHERE節で使うことはできません 1 - LIKEと一緒になら使えます。 2 - LIKEを除いてすべての比較演算子が使えます 3 - WHERE節においてすべての比較演算子が使えます
SQL_INTERVALもしくはSQL_DATETIMEを返し、以下のSQL_DATETIME_SUBは特定の期間(interval)または日時（datetime）型のためのサブコードを返します。もしこのフィールドがNULLであれば、ドライバは期間(interval)または日時（datetime）型をサポートしていないか、報告しません。
SQL_INTERVALもしくはSQL_DATETIMEを返し、このフィールドは特定の期間(interval)または日時（datetime）型のためのサブコードを返します。そうでなければNULL(undef)になります。
例えばselectステートメントでのフィールドのためのデータ型名を見つけるには以下のようにすることができます：
@names = map { scalar $dbh->type_info($_)->{TYPE_NAME} } @{ $sth->{TYPE} }
DBIとODBCドライバとは型をISO標準型にどのようにマッピングするのかが異なっているため、1つ以上の型を探さなければならないかもしれません。以下に日付を格納するのに使えるデータ型を探す例を示します：
$my_date_type = $dbh->type_info( [ SQL_DATE, SQL_TIMESTAMP ] );
同じように、小さな整数を格納するための型の検索を信頼できるようにするため、SQL_SMALLINT,
SQL_INTEGER, SQL_DECIMALなどから始まるリストを使うこともできます。
これらのフィールドとその意味についてのさらに詳しい情報については以下のサイトをご覧ください：
http://msdn.microsoft.com/library/psdk/dasdk/odch6yy7.htm
そのURLが動いていなかったら、以下のMSDN検索機能を使ってみてください：
http://search.microsoft.com/us/dev/
MSDNライブラリからexact phraseオプションでSQLGetTypeInfo
returnsを検索してください。あなたが欲しいリンクはおそらくSQLGetTypeInfoと呼ばれるものでしょう（複数あるかも知れません）。
個々のデータ型は現在、以下のサイトで説明されています：
http://msdn.microsoft.com/library/psdk/dasdk/odap8fcj.htm
もしそのURLが動いていなければ、あるいはもっと一般的な情報を取得するには、上記で説明したMSDN検索機能を使ってSQL Data Typesを検索してください。
quote$sql = $dbh->quote($value); $sql = $dbh->quote($value, $data_type);
文字列の中の（クォーテーション・マークのような）特殊な文字をエスケープし、必要とされるタイプの外側のクォーテーション・マークを加えることにより、文字列リテラルをSQL文で使うリテラル値として使えるようにクォートします。
$sql = sprintf "SELECT foo FROM bar WHERE baz = %s",
$dbh->quote("Don't");
ほとんどのデータベースでは、quoteは'Don"t'
とします。(外側のクォーテーション・マークを含みます）
未定義の$valueの値はSQLでNULLを表すことに対応するよう、文字列NULL (クォーテション・マークなし)になります。.
$data_type が与えられると、type_info
から返される情報を元にして要求されたクォートの処理を決めます。特殊な場合として、標準の数値型はtype_infoを呼ばずに、$valueを返すように最適化されています。
quoteは（バイナリデータや改行が入っているデータのように）すべての入力に対応できるわけではありません。そしてシェルのエスケープやメタ文字にはまったく関連してはいません。 プレースホルダとバインド値で使われる値についてはquoteする必要はありません。
このセクションではデータベース・ハンドルに特有の属性について記述します。
これらのデータベース・ハンドル属性を変更しても、既存の他のデータベース・ハンドルあるいはこの後、生成されるデータベース・ハンドルには影響を与えません。
ドライバ毎のプライベートな属性（属性は名前が小文字ではじまります）を除いては、決められていない属性を設定あるいは取得しようとすると致命的なエラーになります。
例:
$h->{AutoCommit} = ...; # 設定/書込
... = $h->{AutoCommit}; # 取得/読込
AutoCommit
(boolean)ドライバはデフォルトをAutoCommitモードにしなければいけません。 (ODBCとJDBCの決まりにより、残念ながらDBIはこうせざるをえません）
AutoCommitをサポートされていない値に設定しようとすると、致命的なエラーになります。これはDBIの重要な機能です。完全なトランザクションを必要とするアプリケーションは、代入される値がいいかどうかをチェックすることなく $dbh->{AutoCommit}=0 とする(またはconnectメソッドでのAutoCommitを0に設定する）ことができます。
この点から、データベースを３つのカテゴリに分けることができます。
全くトランザクションをサポートしていないデータベース
いつでもトランザクションが有効なデータベース
明示的にトランザクションを開始('BEGIN WORK'などにより)しなければいけないデータベース
* 全くトランザクションをサポートしていないデータベース
これらのデータベースで、AutoCommitをオフにしようとすると致命的なエラーになります。commit 、rollback はAutoCommitが有効な間は無効であるという警告を起こします。
* いつでもトランザクションが有効なデータベース
「ANSI標準」トランザクション機能を持った商用リレーショナル・データベースでは、これが主流です。AutoCommitがオフであると、データベースへの変更はcommit されるまで有効になりません ( disconnect もご覧ください)。もし rollback が呼ばれると、最後のcommit以降のいかなる変更も元に戻されます。
AutoCommitがオンであると、DBIはまるで正常終了したデータベース操作の後、自動的にcommitを呼んでいるのと同じように振る舞います。反対に、AutoCommitがオンの間にcommit、rollbackを明示的に呼び出しても、すでにコミットされてしまっているので、何も効果がありません。
AutoCommitをオフからオンに変えると、大抵のドライバは commit します。
AutoCommitをオンからオフに変えても、すぐになにか効果があるというわけではありません。
自動コミットモードを特にサポートしていないデータベースでは、ドライバは各ステートメントが正常終了したら、明示的にCOMMITすることにより、自動的にコミットしなければいけません。（失敗したら明示的にROLLBACKして元に戻さなければいけません）。アプリケーションに伝えられるエラー情報は、ステートメントが正常終了した後、コミットやロールバックが失敗しない限りは、実行されたステートメントに対応しなければいけません。
* トランザクションが明示的に開始されなければならないデータベース
これらのデータベースでは、トランザクションは（上記のような）いつでも有効になるデータベースと同じようにします。
こうするためDBIドライバは、AutoCommitが（デフォルトのオンの状態から）オフになると、自動的にトランザクションを開始します。そして commit や rollback. の後、自動的に新しいトランザクションを開始します。こうして、アプリケーションはこれらのデータベースを特別なケースとして扱わなくてもよくなるのです。
トランザクションについてのほかの重要な情報については commit, disconnect そしてTransactions をご覧ください。
Driver
(handle)
$dbh->{Driver}->{Name}
Name
(string)Statement
(string, read-only)RaiseError
が有効になっていて、例外ハンドラが$@をチェックし、'prepare'メソッドが失敗したかもしれないと思われるときには特に便利でしょう。
RowCacheSize
(integer)RowCacheSize の値には以下のような意味があります：
0 - 自動的に各SELECTに適切なキャッシュサイズを決めます 1 - ローカル行キャッシュを使用しません >1 - この数だけ行をキャッシュします <0 - 各SELECTのためにメモリの量に合わせてできるだけ多くの行をキャッシュします
キャッシュの大きさを大きくすると大量のメモリが必要になること (キャッシュされる行の数×行の最大サイズ）、そして大きなキャッシュをとるとそれだけ最初の取得あるいは次のキャッシュ分を取得のさいに時間がかかるようになることに注意してください。
RowsInCache ステートメント・ハンドル属性もご覧ください。
このセクションではDBIステートメント・ハンドルに関連するメソッドと属性を一覧にします。
BIはDBIステートメント・ハンドルのために以下のメソッドを定義しています：
bind_param$rc = $sth->bind_param($p_num, $bind_value) or die $sth->errstr; $rv = $sth->bind_param($p_num, $bind_value, \%attr) or ... $rv = $sth->bind_param($p_num, $bind_value, $bind_type) or ...
bind_paramメソッドは、変数とprepareされたステートメントに埋め込まれたプレースホルダをと結びつけるために使われます。プレースホルダはクェスチョン・マーク(?)により示されます。例えば：
$dbh->{RaiseError} = 1; # 各メソッド呼び出しをチェックするようにする
$sth = $dbh->prepare("select name, age from people where name like ?");
$sth->bind_param(1, "John%"); # プレースホルダは１から順番
$sth->execute;
DBI::dump_results($sth);
プレースホルダが文字列を表わしているとしても、?
がクォーテーション・マークで囲まれていないことに注意してください。ドライバによっては、?だけでなく、:名前や:番号（例えば、:1,:2など）といった形式のプレースホルダを許しているものもありますが、それは移植可能ではありません。未定義のバインド値またはundefはNULL値を示すために使うことができます。
ドライバによってはプレースホルダをサポートしていないものもあります。
データベースサーバでのステートメントの評価ができず、そのため問い合わせ計画を作成できなくなるために、多くのドライバではプレースホルダをすべてのステートメントの要素として使えるということではありません。例えば：
"SELECT name, age FROM ?" # 誤（多分、失敗でしょう） "SELECT name, ? FROM people" # 誤（しかし失敗はしないでしょう）
またプレースホルダは１つのスカラ値だけを表わします。例えば以下のステートメントは複数の値を期待してもうまくいかいないでしょう：
"SELECT name, age FROM people WHERE name IN (?)" # 誤
プレースホルダのデータ型
\%attr
パラメータはプレースホルダが持つべきデータ型を指定するために使われます。通常、ドライバはプレースホルダが結びつけられるのが数値としてなのか、文字列としてなのかを知ることだけに関心があります。
$sth->bind_param(1, $value, { TYPE => SQL_INTEGER });
よくあるケースのための短縮形として、データ型を直接attrハッシュ・リファレンスの場所に直接、渡すことができます。この例は、上記のものと同じです。
$sth->bind_param(1, $value, SQL_INTEGER);
TYPEの値はこのパラメータでは（ドライバに特有でない）標準の型を示します。ドライバ特有の型を指定するために、ドライバは { ora_type => 97 }といったドライバ特有の型をサポートしていることがあります。プレースホルダのデータ型は一度bind_paramを呼び出ししてしまったら変更できません。しかし前の値にデフォルトが設定されている場合、指定されていないままにであるかもしれません。
SQL_INTEGERや他の関連する定数は以下のようにしてインポートすることができます：
use DBI qw(:sql_types);
詳細は DBI定数 をご覧ください。.
Perlは文字または数値のスカラ・データ型だけを持っています。数値でないすべてのデータベース型は文字列に結び付けられ、データベースが理解できる形式に変換されなければなりません。
データ型をbind_param呼び出しのさいに指定する代りに、ドライバにデータをデフォルトの型（VARCHAR）として渡すこともできます。そしてSQL関数でステートメントの中で変換することができます。例えば：
INSERT INTO price(code, price) VALUES (?, CONVERT(MONEY,?))
CONVERT関数は単なる例として使われています。
実際の関数と書き方はデータベースによって大きく違いますし、移植性もありません。
詳しい情報についてはプレースホルダとバインド値 もご覧下さい。
bind_param_inout$rc = $sth->bind_param_inout($p_num, \$bind_value, $max_len) or die $sth->errstr; $rv = $sth->bind_param_inout($p_num, \$bind_value, $max_len, \%attr) or ... $rv = $sth->bind_param_inout($p_num, \$bind_value, $max_len, $bind_type) or ...
このメソッドはbind_param
と似ています。しかしステートメントからの更新も可能としています。ステートメントは通常、ストアド・プロシージャと呼ばれます。
$bind_value
は実際に使われる変数へのリファレンスとして渡されます。
bind_paramとは違い、$bind_value
変数はbind_param_inoutが呼ばれたときには読みこまれないことに注意してください。変数の値は
execute が呼ばれたときに読みこまれます。
追加された $max_len
パラメータは、$bin_valueの新しい値のために確保される最小限のメモリ量を指定します。もし実際の値が大きすぎて収まらなければ、executeは失敗します。使用する量がわからなければ、大きな長さを惜しみなく、つまり返されるかもしれない一番長い値より長く値を指定しましょう。必要よりも大きな値を使うために犠牲になるのは、メモリの浪費だけです。
このメソッドはほとんどのドライバはサポートされていないでしょう。今のところ、わかっているのはDBD::Oracleだけです。（DBD::ODBCは将来のリリースでサポートするかもしれません）。ですからデータベースに依存しないアプリケーションでは使うべきではありません。
未定義の値あるいはundef はNULL値を示すのに使われます。さらに詳しい情報はプレースホルダとバインド値 もご覧下さい。
execute$rv = $sth->execute or die $sth->errstr; $rv = $sth->execute(@bind_values) or die $sth->errstr;
prepareされたステートメントを実行するために必要な処理をすべて行います。エラーが発生したら、undefが返されます。正常なexecuteは、影響を受けた行の数に関係無く、例えそれが0であっても（下記を参照）trueを返します。execute（そして他のほとんどのDBIメソッド）の戻りステータスをエラーでないか、チェックすることは常に重要です。
SELECT文でなければ、executeは、もしわかれば影響を受けた行の数を返します。 影響を受けた行が無い場合には、executeは0E0を返します。Perlはこれを0として扱いますが、trueと判定します。影響を受けた行が無いこと自体はエラーではないことに注意してください。影響を受けた行の数がわからなければ、executeは-1を返します。
SELECT文ではexecuteは問い合わせを単にエンジンで"開始"するだけです。executeを呼び出した後は、fetchメソッドのどれかを使ってデータを取り出してください。、 executeメソッドは問い合わせによって返される行の数を返しません。（というのもほとんどのエンジンは前もって教えてくれないからです）、それは単にtrueを返します。
何か引数が与えられると、executeは、そのステートメントを実行する前に、それぞれについて効率よくbind_paramを呼び出します。このようにして結び付けられた値は、ドライバが正しい型を判定できるか（判定できることはまれです）、既にbind_param（またはbind_param_inout)が型を特定するために使われていなければ、通常SQL_VARCHARタイプとして扱われます。
fetchrow_arrayref$ary_ref = $sth->fetchrow_arrayref; $ary_ref = $sth->fetch; # alias
次のデータの行を取り出し、フィールドの値をもった配列へのリファレンスを返します。Nullのフィールドはundefで返されます。特に$sth->bind_columnsを使っているならば、これがデータを取り出す最も速い方法です。
もう行が無いか、エラーが発生すると、fetchrow_arrayref はundefを返します。後で返されたundefがエラーによるものかどうかを見るために、$sth->errをチェックするべきです（あるいはRaiseErrorを使うか)。
現状では、データを取り出すたびに同じ配列リファレンスが返されることがあることに注意してください。そのためリファレンスを取っておいて、データの取り出しを進めた後で、使わないでください。同様に配列の要素も各行で再使用されます。要素のリファレンスを取得したいならば、注意してください。bind_columns もご覧ください。
fetchrow_array@ary = $sth->fetchrow_array;
fetchrow_arrayrefの代用品です。次のデータ行を取り出し、フィールドの値を持った配列を返します。Nullのフィールドはリストの中のundef値として返されます。
もう行が無いか、エラーが発生すると、fetchrow_array はundefを返します。後で返されたundefがエラーによるものかどうかを見るために、$sth->errをチェックするべきです（あるいはRaiseErrorを使うか)。
スカラ・コンテキストではfetchrow_arrayは最初のフィールドの値を返します。もう行がないか、エラーが発生するとundfeが返されます。そのundefを最初のフィールドの値がNULLのために返されるundefとは区別することは出来ないので、fetchrow_arrayをスカラ・コンテキストで使うならば注意を払う必要があります。
fetchrow_hashref$hash_ref = $sth->fetchrow_hashref; $hash_ref = $sth->fetchrow_hashref($name);
fetchrow_arrayref.の代用品です。次のデータ行を取り出し、フィールドの名前と値のペアを持ったハッシュへのリファレンスを返します。NULLフィールドはハッシュのなかのundefとして返されます。
もう行が無いか、エラーが発生すると、fetchrow_hashref はundefを返します。後で返されたundefがエラーによるものかどうかを見るために、$sth->errをチェックするべきです（あるいはRaiseErrorを使うか)。
オプションの $name パラメータには、ステートメント・ハンドル属性の名前を指定します。移植性の面からは"NAME_lc"や"NAME_uc"を使うことが勧められるのですが、 歴史的な理由から、デフォルトは"NAME'"になります。
ハッシュのキーは $sth->{$name} によって返される名前と同じです。複数のフィールドが同じ名前であった場合、返されたハッシュの中のそれらのフィールドためのエントリはただ１つになります。
fetchrow_hashrefは特別な動きをし、さらにPerlが動かなければならないので、fetchrow_arrayref やfetchrow_array ほど効率よくありません。
現在はデータを取り出すたびに、新しいハッシュ・リファレンスが返されます。これは将来、それぞれの場合に同じハッシュを返すように変更するつもりです。ですから現在の動きを信頼しないでください。
fetchall_arrayref$tbl_ary_ref = $sth->fetchall_arrayref; $tbl_ary_ref = $sth->fetchall_arrayref( $slice_array_ref ); $tbl_ary_ref = $sth->fetchall_arrayref( $slice_hash_ref );
fetchall_arrayref メソッドはprepareされ、executeされたステートメント・ハンドルから、返されるべきすべてのデータを取り出すために使います。1行につき１つのリファレンスが入っている配列へのリファレンスを返します。
もう行が無いかエラーが発生すると、fetchall_arrayref は空の配列を返します。 エラーが発生したら、fetchall_arrayrefはデータを取り出せたところまで返します、これは空であるかもしれません。データが完全であるか、エラーにより切り捨てられたかを見るために、後で$sth->errをチェックするべきです（あるいはRaiseErrorを使うか)。
配列リファレンスをfetchall_arrayrefに渡すと、fetchrow_arrayrefを使って配列のリファレンスで各行を取り出します。もしパラメータの配列が空でなければ、インデックス番号によってそれぞれの列を選択し切り出すために使われます。
パラメータがなければ、fetchall_arrayrefは空の配列リファレンスが渡されたように動きます。
ハッシュのリファレンスが渡されると、fetchall_arrayref はfetchrow_hashref を使って、各行をハッシュのリファレンスで取り出します。もしそのパラメータ・ハッシュがからであれば、fetchrow_hashrefは単にきついループで呼ばれるだけで、ハッシュのキーはfetchrow_hashrefからのデフォルトで返されるすべての小文字の名前を持つだけです。（FetchHashKeyName属性をご覧ください）
もしパラメータのハッシュが空でなければ、 名前によってそれぞれの列を選択し切り出すために使われます。$sth->{NAME}での大文字、小文字に関係無く、名前は小文字でなければなりません。ハッシュの値は１に設定しなければなりません。
例えば、各行の先頭のカラムだけを取り出したい場合, 以下のようにします:
$tbl_ary_ref = $sth->fetchall_arrayref([0]);
各行の一番後ろ、その直前の列を取り出すためには以下のようにします:
$tbl_ary_ref = $sth->fetchall_arrayref([-2,-1]);
各行をハッシュ・リファレンスとして取り出すためには以下のようにします：
$tbl_ary_ref = $sth->fetchall_arrayref({});
各行のfooとbarというフィールドだけを取り出すためには以下のようにします:
$tbl_ary_ref = $sth->fetchall_arrayref({ foo=>1, bar=>1 });
最初の２つの例では、配列リファレンスの配列へのリファレンスを返します。最後の例はハッシュ・リファレンスの配列へのリファレンスを返します。
finish$rc = $sth->finish;
もう一度executeされるか、破壊されるまで、このステートメント・ハンドルからは、もうデータが取り出されないことを示します。finishメソッドはあまり必要になることはありませんが、サーバーが現在保持している（ソートバッファのような）リソースを解放させることができるためにとても限られた状況では役に立ちます。
ドライバはすべてのデータがSELECTステートメントから取り出されるたら、自動的にあなたに代ってfinishしなければいけません。そのため通常は、これを明示的に呼び出す必要はありません。
以下のような問い合わせを考えてみてください：
SELECT foo FROM table WHERE bar=? ORDER BY foo
大きなテーブルから、最初の（最も小さい）fooの値をSELECTしたいとします。実行されるとデータベース・サーバは一時的なバッファ領域をソートされた行を格納するために使わなければなりません。もし実行し、１行セレクトした後で、ときどきハンドルが再実行されなかったり、破壊されないならば、finishメソッドによってサーバーにバッファ領域を解放することができることを教えることができます。
finishを呼び出すと、 そのステートメントのActive 属性はリセットされます。（NAMEやTYPEのような）他のステートメント・ハンドル属性いくつかも、既にアクセスされて（そしてキャッシュされて）いるのでなければ、使用できなくなるかもしれません。
finishメソッドはデータベース接続のトランザクションの状態にはなにも影響を与えません。トランザクションには何もしません。これはほとんど内部の「家事的(='housekeeping')」メソッドで、あまり必要なことはありません。 すぐにステートメント・ハンドルを破壊または再実行するのであれば、finishを呼ぶ必要はありません。disconnect と Active 属性もご覧ください。
finish method
should have been called cancel_select.
rows$rv = $sth->rows;
通常、rowsはdo またはSELECT以外(UPDATEやDELETEのようなある種の操作）のexecute または、SELECTステートメントのすべての行を取り出した後にしか、信用できません。
SELECTステートメントでは、通常、何行返ってくるのかは、すべてを取り出すまではわかりません。ドライバによってはそれまでに取得した行数を返すものもありますが、
すべての行が取り出されるまでは−１を返すものもあります。そのためSELECTステートメントにrowsメソッドや$DBI::rowsを使うことはお勧めできません。
bind_col$rc = $sth->bind_col($column_number, \$var_to_bind);
SELECTステートメントの出力カラム（フィールド）にperlの変数を結び付けます。例として下記のbind_columnsをご覧下さい。カラム番号は1から数えます。
データベースから行が取り出されると、対応するPerl変数が自動的に更新されます。手動で値を取り出し、代入する必要がありません。このバインディングはPerlエイリアスを使い、とても下位のレベルで実行されます。そのため余分なコピーは一切行われません。これはバインドされた変数を非常に効率よく使います。
ドライバ間の移植性を最大限に高めるためには、 bind_col はexecuteの後に呼び出さなければなりません。この制限はDBIの今後のバージョンでは削除されるかもしれません。
データを取り出すためには、出力カラムをバインドする必要はありませんが、最大限のパフォーマンスやコードの明確性が必要なアプリケーションによってはとても有効でしょう。bind_param メソッドは同じようなことをしますが、入力変数のための反対の関数です。
bind_columns$rc = $sth->bind_columns(@list_of_refs_to_vars_to_bind);
SELECTステートメントの各カラムにbind_col を呼び出します。リファレンスの数がフィールドの数と合っていないと、bind_columnsメソッドは死にます(die)。
ドライバ間の移植性を最大限に高めるためには、bind_columns はexecuteの後に呼び出さなければなりません
例：
$dbh->{RaiseError} = 1; # こうするか、呼び出しのたびにエラーをチェックしてください
$sth = $dbh->prepare(q{ SELECT region, sales FROM sales_by_region });
$st