6部 データベース・インタフェイス

すべてのハンドルに共通のメソッド

errerrstrメソッドはよく使われる重要なメソッドです。ほかのメソッドは必要に応じて使っていくようにするとよいでしょう。

全てのハンドルに共通のメソッド

err

$rv = $h->err;

データベースエンジンのエラーコードを返します。このエラー番号は$DBI::errstrから返されたエラーメッセージに対応しています。

errの使用方法
$dbh->execute;
if ( ! $dbh ){
    print "エラー: $dbh->err $dbh->errstr\n";
}

errstr

$str = $h->errstr;

データベースエンジンのエラーメッセージを返します。使い方はerrを参照してください。

state

$str = $h->state;

標準のSQLSTATEの 5文字のフォーマットでエラーコードを返します。特定の正常終了コード 00000 は、FALSEに変換されます。ドライバがSQLSTATEをサポートしていなければ、すべてのエラーについてS1000(一般エラー)を返します。

trace

$h->trace($trace_level);
$h->trace($trace_level, $trace_file);

$trace_levelで指定するトレースレベルを2に設定すると、完全なデバック情報が表示されます。0 に設定すると、トレースは無効になります。

トレースはデフォルトで標準エラー出力(STDERR)に出力されます。引数$trace_fileを指定した場合、ファイルは追加モードで開かれ、すべてのトレース情報が指定のファイルに書き込まれます。それ以降は、$trace_fileを指定しなくても、そのファイルがデフォルトで使用されます。

trace_msg

$h->trace_msg($message_text);
$h->trace_msg($message_text, $min_level);

トレースが$hや全体としてDBIで有効の場合に、トレースファイルに$message_textを書き込みます。さらにDBI->trace_msg($msg)として呼ぶことができます。

引数$min_levelでトレースレベルを指定した場合、トレース・レベルがそのレベル以上である場合だけメッセージが出力されます。$min_levelのデフォルトは1です。

func

$h->func(@func_arguments, $func_name);

funcメソッドは、ドライバが実装しているプライベートな標準でなく、移植できないメソッドを呼び出すことができます。移植性を考えると、funcメソッドを使うより、それに相当するDBI関数を使いましょう。

DBD::mysqlでは次のメソッドを実装しています。

メソッド 解説
_ListDBs ホスト名とポート番号が引数となり、そのサーバで利用可能なデータベースのリストを返す。
_ListTable 現在のデータベースに存在するテーブルのリストを返す。
_CreateDB データベース名が引数となり、サーバ上にデータベースを作成する。成功すると 0、失敗すると 1 を返す。
_DropDB データベース名が引数となり、サーバからデータベースを削除する。成功すると 0、失敗すると 1 を返す。

funcの使用方法
my @tables = $dbh->func->('_ListTable');
PAGE TOP


全てのハンドルに共通の属性

これから紹介する属性は、全てのDBIハンドルで共通のものです。属性によっては、子孫に継承されるものがあり、新しいステートメント・ハンドルで継承される属性の値は、その親となるデータベースハンドルの値と同じです。新しいステートメントハンドルの属性への変更は、親データベースハンドルに影響しません。

属性の使用方法
$h->{AttributeName} = ...; # set/write
... = $h->{AttributeName}; # get/read

Warn (boolean、継承)

警告を有効にします。デフォルトで有効です。

Active(boolean、読み出し専用)

ハンドル・オブジェクトがActiveであればTRUEになります。Activeとは、たとえば、データベース・ハンドルの場合でしたら、そのハンドルがデータベースに接続されていることを意味します。ステートメントハンドルの場合は、SELECTなどの処理の後で、まだ取り出していない行があることを意味します。

Kids (整数、読み出し専用) 

ドライバ・ハンドルの場合、そのドライバ・ハンドルに関連したデータベース・ハンドルの数になります。データベース・ハンドルの場合は、そのデータベース・ハンドルに関連したステートメント・ハンドルの数になります。

ActiveKids(整数、読み出し専用)

Kidsに似ていますが、Activeなものだけを数えます。たとえば、データベースハンドルでは、prepare_cachedメソッドによって作成されたステートメントハンドルのキャッシュへのリファレンスを返します。ドライバハンドルでは、connect_cachedメソッドによって作成されたステートメントハンドルのキャッシュへのリファレンスを返します。

CachedKids (hash ref)

Kidsに似た属性です。データベース・ハンドルの場合、prepare_cachedメソッドにより生成されたステートメント・ハンドルのキャッシュへのリファレンスを返します。ドライバ・ハンドルの場合、connect_cachedメソッドにより生成されたステートメント・ハンドルのキャッシュへのリファレンスを返します。

CompatMode(boolean、継承) oracleコンパチ

Oraperlのような)エミュレーション・レイヤで使われ、このハンドルが元になっているドライバ(つまりDBD::Oracle)での動きと互換性を保つようにするために使われます。通常はアプリケーションコードでセットされません。

InactiveDestroy(boolean)

この属性は、ハンドルを破棄(DESTROY)することによって生じる、データベース・エンジン関連の影響を無効にします。
データベース・ハンドルにとっては、この属性はdisconnectメソッドの明示的な呼び出しを無効にしません。ハンドルの破棄(DESTROY)から暗黙の呼び出しだけを無効にします。

この属性は、特に子プロセスをforkするUNIXアプリケーションでの使用について設計されています。親と子の両方ではなくどちらか片方だけが、共有しているハンドルのすべてにInactiveDestroyを設定するべきです。Oracleを含めて、いくつかのドライバはデータベース接続をforkをまたがって渡すことをサポートしていません。

PrintError(boolean、継承)

この属性は、通常の方法でエラーコードを返すことに加えて、warnを使用して警告を生成するよう強制します。 
$classにはドライバクラス、$methodにはエラーになったメソッドが入ります。

DBD::mysql::db prepare faild: ... (ここにエラーテキストが入ります) ...

警告は、$SIG{__WARN__}ハンドラ、もしくはCGI::ErrorWrapのようなモジュールを使用して処理できます。

RaiseError(boolean、継承)

この属性は例外を発生させるために使います。デフォルトでオフです。オンの状態でメソッドがエラーになると、die("$class $method
failed $DBI::errstr")
が実行されます。$classにはドライバクラス、$methodにはエラーになったメソッドが入ります。

PrintErrorもオンの場合には、_DIE_ハンドラが提供されていれば、RaiseErrorの前に行われます。そうでなければPrintErrorはスキップされます。

一時的にRaiseErrorをオフにするためには、以下のようにします。

{
    local $h->{RaiseError} = 0 if $h->{RaiseError};
    ...
}

ShowErrorStatement(boolean, inherited)

この属性は、関連するステートメント・テキストをRaiseErrorPrintErrorによって生成されるエラーメッセージに追加します。ステートメント・ハンドルでのエラーに加えて、データベース・ハンドル・メソッドpreparedoについてのみ適用されます。(追加されるテキストの正確なフォーマットは変更されるかもしれません)

FetchHashKeyName (string, inherited)

この属性は、fetchrow_hashrefがハッシュキーのためにフィールド名を取り出すさいに使用する属性名を指定するために使われます。歴史的な理由からデフォルトはNAMEですが、好みに合わせて、NAME_lcまたはNAME_ucに設定することをお勧めします。これはドライバとデータベース・ハンドルにのみ設定することができます。ステートメント・ハンドルでは、値はprepareされた時点で凍結されます。

ChopBlanks(ブール、継承される)

固定長文字列(CHAR)フィールドから末尾の空白を取り除きます。他のフィールドタイプでは利用できません。デフォルトはFALSEです。

この属性をサポートしないドライバは、属性値としてundefを返します。

LongReadLen(符号なしの整数、継承された)

この属性は、データ行の読み込みで、自動的にデータベースからドライバが読みこむlongLONGblobmemoなど)フィールドの最大長を設定します。値が 0 であれば、long値はundefです。

LongReadLenprepareを呼び出す前に$dbhに対して設定しないと、効果がありません。

切り詰めについてはLongTruncOkを参照
してください。

LongTruncOk(ブール、継承される)

この属性は、切り詰めたlongフィールド値の取り出しを制御するために使用されます。
デフォルトでは、LongTruncOkFALSEで、切り詰めが必要になる長い値をフェッチすると、フェッチは失敗します。 

LongTruncOkFALSEで、フェッチがlongフィールド欠如により失敗しても、多くのドライバは先の行を取り出すことができます。

Taint (boolean, inherited)

この属性にtrueが設定され、そしてPerlが汚染(taint)モード(例えば-Tオプションで開始されて)で実行されていれば、データベースから取り出されるすべてのデータは汚染されており、DBIメソッド呼び出しの引数は汚染されているとチェックされます。これは変更されるかもしれません。

Perlが汚染モードであっても、この属性のデフォルトはオフです。

信頼できるデータを取り出すとき、ステートメント・ハンドルについて、取り出しループの間はTaint属性をオフに切り替えることが出来ます。

private_*

DBIはプライベート属性として、DBIハンドルでの特別な情報を格納する方法を提供しています。DBIではprivate_で始まる名前の属性を格納、参照することができます。ただしプライベート属性はハッシュのリファレンスを使うなど、1つだけとし、その属性に関連するモジュール名などが入ったユニークな名前にすることを強くお勧めします。

関連記事