クラスメソッドはDBI
をuse
してすぐに使える関数です。クラスメソッドは、データベースに接続するためのconnect
以外はそれほど必須なメソッドではありません。
DBIクラスメソッド
connect
# %attrはオプションです $dbh = DBI->connect($data_source, $user, $password, \%attr) or die $DBI::errstr;
connect
はデータベース接続するためのメソッドです。connect
が正常終了した場合は、データベース・ハンドルを返すので、そのハンドルを使ってデータベースを操作するメソッドを呼び出します。接続の終了は$dbh->disconnect
を使用します。
$dbh を使ってメソッドを呼び出す
# データベースへ接続 $dbh = DBI->connect($dsn, $user, $password); # データベース・ハンドルから selectrorw_array を呼び出す $ref = $dbh->selectrow_array( "SELECT COUNT(*) FROM db " );
connect
は、接続に失敗すると、$DBI::err
と$DBI::errstr
にエラー情報をセットし、undef
を返します。connect
の返すステータスを確認し、失敗していたら$DBI::errstr
を表示させるとよいでしょう。
$dbh = DBI->connect($dsn, $user, $password); if ( ! $dbh ){ print "エラー: $dbh->err $dbh->errstr\n"; }
引数$data_source
の値にはDBI:ドライバ名を指定します。大文字・小文字は区別されます。さらに データベース名、ホスト名、ポート番号を指定できます。
$data_source
値の例
dbi:DriverName:database_name dbi:DriverName:database_name@hostname:port dbi:DriverName:database=database_name; host=hostname;port=port
引数$user
または$password
が未定義(空ではなく)ならば、環境変数DBI_USER
とDBI_PASS
の値で置き換えられます。ただし、セキュリティを考慮すると、これらの環境変数の値を使うことは推薦されません。
ドライバがまだインストールされていない場合、connect
はドライバを自動的にインストールします。ドライバのインストールは有効なドライバハンドルを返すか、エラーメッセージとともに終了します。
\%attr
パラメータはPrintError
、RaiseError
、AutoCommit
などの属性を変更することができます。AutoCommit
とPrintError
属性はデフォルトでON
ですが、明示的にAutoCommit
を定義したほうが安全です。
引数 \%attr の値を設定
$dbh = DBI->connect($data_source, $user, $pass, { PrintError => 0, AutoCommit => 0 });
$dbh
を使った各セッションは、他のセッションのトランザクションから独立しています。これはオープンしたカーソルをトランザクションをまたがって保持する必要がある場合には便利です。つまり1つのセッションを長い寿命をもつカーソルとして使い、他のセッションで短い更新トランザクションを実行できるということです。
環境変数DBI_AUTOPROXY
が定義されていて、$data_source
に'Proxy'
の指定がなければ、接続の要求は自動的に以下のように変更され、DBD::Proxy
モジュールに渡されます。
DBI_AUTOPROXYの設定
dbi:Proxy:$ENV{DBI_AUTOPROXY};dsn=$data_source
DBI_AUTOPROXY
の書式は、hostname=...;port=...
です。
connect_cached
# %attrはオプションです $dbh = DBI->connect_cached($data_source, $username, $password, \%attr) or die $DBI::errstr;
connect_cached
は、返却値のデータベース・ハンドルが与えられたパラメータと関連付けられ、ハッシュにも格納されるという点を除けばconnect
に似ています。同じパラメータ値でconnect_cached
がもう一度呼ばれると、それがまだ適切であれば、キャッシュされた$dbh
が返されます。すでに切断されている場合などは、新しい接続で置きかえられます。
キャッシュはCachedKids
属性
でアクセス、もしくはクリアすることができます。
キャッシュは、問題の原因になりやすく、このメソッドの動作は変更される可能性が高いので、注意して使いましょう。
available_drivers
@ary = DBI->available_drivers; @ary = DBI->available_drivers($quiet);
@INC
ディレクトリからDBD
関連のモジュールを検索して、使用可能なドライバのリストを返します。MySQL
のドライバ名はmysql
です。
available_drivers
は、同じ名前のドライバがあれば警告します。引数$quiet
をTRUE
にセットすると、警告が出力されなくなります。
data_sources
@ary = DBI->data_sources($driver); @ary = DBI->data_sources($driver, \%attr);
指定されたドライバが利用可能な全てのデータソースのリストを返します。data_sources
が返す値はconnect
メソッドにそのまま渡すことができます。このとき、読み込まれていないドライバは
自動的にロードされます。
$driver
が空文字や未定義の場合、DBI_DRIVER
環境変数の値が使用されます。
多くのドライバが、空文字、もしくは不完全なリストを返すことが多いので、注意しましょう。
trace
DBI->trace($trace_level) DBI->trace($trace_level, $trace_file)
trace
メソッドは、全てのハンドルのDBI
トレース情報を有効にします。特定のハンドルに対するトレース情報を得るには、$h->trace
メソッドを使うと良いでしょう。
トレース・レベル($trace_level
)は以下のとおりです。
レベル | 解説 |
---|---|
0 | トレース不可 |
1 | 何が起こったのかの単純な概要 |
2 | 完全なデバック情報 |
3以上 |
上記と同様。ドライバからのいくつかのハイレベルな情報と DBI からのいくつかの内部情報を追加。 |
トレース出力の多くはneat
関数を使用して整形されるので、トレース出力中の文字列は切り詰められることもあります。
トレースはデフォルトで標準エラー出力(STDERR
)に出力されます。引数$trace_file
を指定した場合、ファイルは追加モードで開かれ、すべてのトレース情報が指定のファイルに書き込まれます。それ以降は、$trace_file
を指定しなくても、そのファイルがデフォルトで使用されます。
traceの一般的な使用方法
# 出力はファイルDBI.traceに送られます $dbh->trace(2, 'DBI.trace');
DBI ユーティリティ関数
DBI
は上記で紹介したメソッドに加え、下記のユーティリティ関数を用意しています。
neat非日本語対応)
$str = DBI::neat($value, $maxlen);
指定された文字列を整形して返します。
整形内容
- 文字列中のクォーテーションをエスケープ
- 文字列全体をクォーテーションで囲む(数値は対象外)
- 出力できない文字はドット( . )で置き換え
また、未定義値(NULL
)はundef
として返されます。
引数$maxlen
を指定して、文字列の長さを切り詰めることができます。変換結果の文字列が$maxlen
よりも長ければ、文字列は$maxlen-4
の長さに切り詰め、... を追加します。$maxlen
が 0
またはundef
の場合、$DBI::neat_maxlen
(デフォルトは400)で切り詰めます。
neatの使用方法
my $str = "1234567890"; $str = DBI::neat($str, 9); print $str, "\n"; # "1234..."と出力される
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 の動的な属性
動的な属性は、常に最後に使用されたハンドルに関係しています。
※ これらの属性は便宜上提供されますが、制限があります。特に、使用される最後のハンドルに関係しているので、それらをセットしたメソッドを呼んだ直後にのみ使用してください。
問題が無ければ、対応するメソッド呼び出しを使うようにしましょう。
属性 | 解説 |
---|---|
$DBI::err |
$h->err と同じ |
$DBI::errstr |
$h->errstr と同じ |
$DBI::state |
$h->state と同じ |
$DBI::rows |
$h->rows と同じ |
$DBI::lasth | 最後のDBI メソッド呼び出しに使われたDBI オブジェクト・ハンドルを返します。最後のDBI メソッド呼び出しがDESTROY であれば、あれば破壊されたハンドルの親のハンドルを返します。 |