NAME

TL::DB - DBI (ja)

NAME (ja)

TL::DB::JA - DBIのラッパ

SYNOPSIS

$TL->startCgi(
    -DB      => 'DB',
    -main        => \&main,
);

sub main {
  my $DB = $TL->getDB('DB');

  $DB->setDefaultSet('R_Trans');
  $DB->begin;

  my $sth = $DB->execute(q{SELECT a, b FROM foo WHERE a = ?}, 999);
  while (my $hash = $sth->fetchHash) {
      print $hash->{a};
  }
  $DB->commit;

  $DB->begin('W_Trans');
  $DB->execute(q{UPDATE counter SET counter = counter + 1 WHERE id = ?}, 1);
  $DB->commit;
}

DESCRIPTION

接続/切断は自動で行われる。

手動で接続/切断する場合は、connect/disconnectを使う。

実行クエリの処理時間・実行計画・結果を記録するデバッグモード。

prepare/executeを分けない。fetchは分ける。

拡張プレースホルダ機能

$db->execute(q{select * from a where mode in (??)}, ['a', 'b'])

と記述すると、

$db->execute(q{select * from a where mode in (?, ?)}, 'a', 'b')

のように解釈される。

プレースホルダの値渡しの際に型指定が可能

$db->execute(q{select * from a limit ??}, ['a', \'SQL_INTEGER'])

リクエスト処理完了後のトランザクション未完了やunlock未完了を自動検出

DBグループ・DBセット・DBコネクション

TL::DBでは、レプリケーションを利用してロードバランスすることを支援するため、１つのDBグループの中に、複数のDBセットを定義することが可能となっている。 DBセットの中には、複数のDBコネクションを定義できる。

更新用DBセット、参照用DBセット、などの形で定義しておき、プログラム中でトランザクション単位でどのDBセットを使用するか指定することで、更新用クエリはマスタDB、参照用クエリはスレーブDB、といった使い分けをすることが可能となる。

DBセットには複数のDBコネクションを定義でき、複数定義した場合はプロセス単位でプロセスIDを元に1つのコネクションが選択される。（プロセスIDを定義数で割り、その余りを使用して決定する。）

同じDBグループの中の複数のDBセットで同じDBコネクション名が使用された場合は、実際にDBに接続されるコネクション数は1つとなる。このため、縮退運転時に参照用DBセットのDBコネクションを更新用のものに差し替えたり、予め将来を想定して多くのDBセットに分散させておくことが可能となっている。

DBセットの名称はSET_XXXX(XXXXは任意の文字列)でなければならない。 DBコネクションの名称はCNT_XXXX(XXXXは任意の文字列)でなければならない。

拡張プレースホルダ詳細

"execute" に渡されるSQL文には、通常のプレースホルダの他に、拡張プレースホルダ "??" を埋め込む事が出来る。拡張プレースホルダの置かれた場所には、パラメータとして通常のスカラー値でなく、配列へのリファレンスを与えなければならない。配列が複数の値を持っている場合には、それらが通常のプレースホルダをカンマで繋げたものに展開される。

例: 以下の二文は等価

$DB->execute(
    q{SELECT * FROM a WHERE a IN (??) AND b = ?},
    ['AAA', 'BBB', 'CCC'], 800);
$DB->execute(
    q{SELECT * FROM a WHERE a IN (?, ?, ?) AND b = ?},
    'AAA', 'BBB', 'CCC', 800);

パラメータとしての配列の最後の項目が文字列へのリファレンスである時、その文字列は SQL型名として扱われる。配列が複数の値を持つ時には、その全ての要素に対して型指定が適用される。型名はDBI.pmで定義される。

例:

$DB->execute(q{SELECT * FROM a LIMIT ??}, [20, \'SQL_INTEGER']);
==> SELECT * FROM a LIMIT 20

$DB->execute(q{SELECT * FROM a LIMIT ??}, [20, 5, \'SQL_INTEGER']);
==> SELECT * FROM a LIMIT 20, 5

配列内の要素を更に2要素の配列とし、二番目の要素を文字列へのリファレンスとする事で、要素の型を個別に指定出来る。

例:

$DB->execute(
    q{SELECT * FROM a WHERE a IN (??) AND b = ?},
    [[100, \'SQL_INTEGER'], 'foo', \'SQL_VARCHAR'], 800);
==> SELECT * FROM a WHERE a IN (100, 'foo') AND b = '800'

METHODS

`TL::DB` メソッド

$TL->getDB

$DB = $TL->getDB
$DB = $TL->getDB($inigroup)

TL::DB オブジェクトを取得。引数にはIniで設定したグループ名を渡す。引数省略時は 'DB' グループが使用される。

$TL->startCgi / $TL->errorTrap の関数内でDBオブジェクトを取得する場合に使用する。

$TL->newDB

$DB = $TL->newDB
$DB = $TL->newDB($inigroup)

新しく TL::DB オブジェクト作成。引数にはIniで設定したグループ名を渡す。引数省略時は 'DB' グループが使用される。

動的にコネクションを作成したい場合などに使用する。この方法で TL::DB オブジェクトを取得した場合、"connect" / "disconnect" を呼び出し、接続の制御を行う必要がある。

connect

DBに接続する。

$TL->startCgi / $TL->errorTrap の関数内でDBオブジェクトを取得する場合には自動的に接続が管理されるため、このメソッドを呼び出してはならない。

$TL->newDB で作成した TL::DB オブジェクトに関しては、このメソッドを呼び出し、DBへ接続する必要がある。

disconnect

DBから切断する。

$TL->startCgi / $TL->errorTrap の関数内でDBオブジェクトを取得する場合には自動的に接続が管理されるため、このメソッドを呼び出してはならない。

$TL->newDB で作成した TL::DB オブジェクトに関しては、このメソッドを呼び出し、DBへの接続を切断する必要がある。

begin

$DB->begin
$DB->begin('SET_W_Trans')

指定されたDBセット名でトランザクションを開始する。トランザクション名 (DBセット名) はiniで定義されていなければならない。名前を省略した場合は、デフォルトのDBセットが使われるが、 setDefaultSetによってデフォルトが選ばれていない場合にはエラーとなる。

CGIの中でトランザクションを開始し、終了せずにMain関数を抜けた場合は、自動的に rollbackされる。

トランザクション実行中にこのメソッドを呼んだ場合には、エラーとなる。 1度に開始出来るトランザクションは、1つのDBグループにつき1つだけとなる。

rollback

$DB->rollback

現在実行中のトランザクションを取り消す。

commit

$DB->commit

現在実行中のトランザクションを確定する。

setDefaultSet

$DB->setDefaultSet('SET_W_Trans')

デフォルトのDBセットを選択する。ここで設定されたDBセットは、引数無しのbegin() や、beginせずに行ったexecuteの際に使われる。このメソッドは Main関数の先頭で呼ばれる事を想定している。

execute

$DB->execute($sql, $param...)
$DB->execute(\'SET_W_Trans' => $sql, $param...)

SELECT/UPDATE/DELETEなどのSQL文を実行する。第1引数にSQL、第2引数以降にプレースホルダの引数を渡す。ただし、第1引数にリファレンスでDBセットを渡すことにより、トランザクション外での実行時にDBセットを指定することが可能。

第2引数以降の引数では、拡張プレースホルダが使用できる。 "拡張プレースホルダ詳細" を参照。

既にトランザクションが実行されていれば、そのトランザクションの DBセットでSQLが実行される。

トランザクションが開始されておらず、かつ "lock" によりテーブルがロックされていれば、ロックをかけているDBセットでSQLが実行される。

いずれの場合でもない場合は、"setDefaultSet" で指定されたトランザクションが使用される。 "setDefaultSet" による設定がされていない場合は、エラーとなる。

このメソッドを使用して、LOCK/UNLOCK/BEGIN/COMMITといったSQL文を実行してはならない。実行しようとした場合はエラーになる。代わりに専用のメソッドを使用する事。

selectAllHash

$DB->selectAllHash($sql, $param...)
$DB->selectAllHash(\'SET_W_Trans' => $sql, $param...)

SELECT結果をハッシュの配列へのリファレンスで返す。

my $arrayofhash = $DB->selectAllHash($sql, $param...);
foreach my $key (@$arrayofhash){
   $TL->log(DBDATA => $arrayofhash->{$key});
}

selectAllArray

$DB->selectAllArray($sql, $param...)
$DB->selectAllArray(\'SET_W_Trans' => $sql, $param...)

SELECT結果を配列の配列へのリファレンスで返す。

my $arrayofarray = $DB->selectAllArray($sql, $param...);
foreach my $array (@$arrayofarray){
   $TL->log(DBDATA => $array->[0]);
}

lock

$DB->lock(set => 'SET_W_Trans', read => ['A', 'B'], write => 'C')

指定されたDBセットに対してLOCK TABLESを実行する。setが省略された場合はデフォルトのDBセットが選ばれる。CGIの中でロックした場合は、 Main関数を抜けた時点で自動的にunlockされる。

ロック実行中にこのメソッドを呼んだ場合には、エラーとなる。 1度に開始出来るロックは、1つのDBグループにつき1つだけとなる。

unlock

$DB->unlock

UNLOCK TABLES を実行する。ロックがかかっていない場合はエラーとなる。

setBufferSize

$DB->setBufferSize($kbytes)

バッファサイズをKB単位でセットする。行を１行読み込んだ結果このサイズを上回る場合、dieする。 0 または undef をセットすると、制限が解除される。

symquote

$DB->symquote($sym)

文字列を識別子としてクォートする。

mysqlの場合は `a b c` となり、それ以外の場合は "a b c" となる。

getType

$DB->getType;

DBのタイプを返す。(mysql, pgsql, ...)

getDbh

$dbh = $DB->getDbh
$dbh = $DB->getDbh('SET_W_Trans')

DBセット内のDBハンドルを返す。返されるオブジェクトは DBI ネイティブのdbhである。

ネイティブのDBハンドルを使用してクエリを発行した場合、デバッグ機能（プロファイリング等）の機能は使用できません。また、トランザクションやロック状態の管理もフレームワークで行えなくなるため、注意して使用する必要があります。

`TL::DB::STH` メソッド

fetchHash

$sth->fetchHash

ハッシュへのリファレンスで１行取り出す。

fetchArray

$sth->fetchArray

配列へのリファレンスで１行取り出す。

rows

$sth->rows

DBIと同様。

finish

$sth->finish

DBIと同様。

nameArray

$sth->nameArray

$sth->{NAME_lc} を返す。

nameHash

$sth->nameHash

$sth->{NAME_lc_hash} を返す。

Ini パラメータ

DBセット・DBコネクション

DBグループのパラメータのうち、半角小文字英数字のみで構成されたパラメータは予約済みで、DBグループの動作設定に使用する。 DBセットは、予約済みではない名前であれば任意の名称が使用でき、値としてDBコネクションのINIグループ名をカンマ区切りで指定する。

例:

[DB]
namequery=1
type=mysql
defaultset=SET_R_Trans
SET_W_Trans=CNT_DBW1
SET_R_Trans=CNT_DBR1,CNT_DBR2

[CNT_DBW1]
dbname=test
user=daemon
host=192.168.0.100

[CNT_DBR1]
dbname=test
user=daemon
host=192.168.0.110

[CNT_DBR2]
dbname=test
user=daemon
host=192.168.0.111

以下は特別なパラメータ:

namequery

namequery = 1

これを1にすると、実行しようとしたクエリのコマンド名の直後に /* foo.pl:111 [DB.R_Transaction1.DBR1] */ のようなコメントを挿入する。デフォルトは0。

type

type = mysql

DBの種類を選択する。 mysql, pgsql, oracleが使用可能。必須項目。

defaultset

defaultset = SET_W_Trans

デフォルトのDBセットを設定する。ここで設定されたDBセットは、引数無しのbegin()や、beginせずに行ったexecuteの際に使われる。

DB定義

dbname

dbname = test

DB名を設定する。

host

host = localhost

DBのアドレスを設定する。デフォルトはlocalhost。

user

user = www

DBに接続する際のユーザー名を設定する。

password

password = PASS

DBに接続する際のパスワードを設定する。省略可能。

AUTHOR INFORMATION

This framework is free software; you can redistribute it and/or modify it under the same terms as Perl itself

このフレームワークはフリーソフトウェアです。あなたは Perl と同じライセンスの元で再配布及び変更を行うことが出来ます。

Address bug reports and comments to: tl@tripletail.jp

HP : http://tripletail.jp/

To install TL, copy and paste the appropriate command in to your terminal.

cpanm

cpanm TL

CPAN shell

perl -MCPAN -e shell
install TL

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)