=encoding euc-jp =pod =head1 名前 DBD::mysql - Perl5 データベース・インターフェース(DBI)のためのMySQLドライバ =head1 概要 use DBI; $dsn = "DBI:mysql:database=$database;host=$hostname;port=$port"; $dbh = DBI->connect($dsn, $user, $password); $drh = DBI->install_driver("mysql"); @databases = DBI->data_sources("mysql"); または @databases = DBI->data_sources("mysql", {"host" => $host, "port" => $port}); $sth = $dbh->prepare("SELECT * FROM foo WHERE bla"); または $sth = $dbh->prepare("LISTFIELDS $table"); または $sth = $dbh->prepare("LISTINDEX $table $index"); $sth->execute; $numRows = $sth->rows; $numFields = $sth->{'NUM_OF_FIELDS'}; $sth->finish; $rc = $drh->func('createdb', $database, $host, $user, $password, 'admin'); $rc = $drh->func('dropdb', $database, $host, $user, $password, 'admin'); $rc = $drh->func('shutdown', $host, $user, $password, 'admin'); $rc = $drh->func('reload', $host, $user, $password, 'admin'); $rc = $dbh->func('createdb', $database, 'admin'); $rc = $dbh->func('dropdb', $database, 'admin'); $rc = $dbh->func('shutdown', 'admin'); $rc = $dbh->func('reload', 'admin'); =head1 例 #!/usr/bin/perl use strict; use DBI(); # データベースへの接続 my $dbh = DBI->connect("DBI:mysql:database=test;host=localhost", "joe", "joe's password", {'RaiseError' => 1}); # テーブル'foo'をドロップ。'foo'が存在していないと、これは失敗するでしょう。 # そのため周りをevalで囲んでいます。 eval { $dbh->do("DROP TABLE foo") }; print "Dropping foo failed: $@\n" if $@; # 新しいテーブル'foo'を作成します。これは失敗するはずがありません。 # そのためエラーをキャッチしていません。 $dbh->do("CREATE TABLE foo (id INTEGER, name VARCHAR(20))"); # 'foo'にデータをINSERTします。nameをクォートするために # $dbh->quote()を使っています。 $dbh->do("INSERT INTO foo VALUES (1, " . $dbh->quote("Tim") . ")"); # 同じこと。ただしプレースホルダを使っています。 $dbh->do("INSERT INTO foo VALUES (?, ?)", undef, 2, "Jochen"); # 今度はテーブルからのデータを取り出します my $sth = $dbh->prepare("SELECT * FROM foo"); $sth->execute(); while (my $ref = $sth->fetchrow_hashref()) { print "Found a row: id = $ref->{'id'}, name = $ref->{'name'}\n"; } $sth->finish(); # データベースからの切断 $dbh->disconnect(); =head1 説明 BはMySQLデータベースのためのPerl5データベース・インターフェース・ ドライバです。言い換えると:DBD::mysqlはPerlプログラミング言語と MySQLリレーショナル・データベース管理システムに入っている MySQLプログラミングAPIとのインターフェースです。このプログラミングAPIで 提供されているほとんどの機能がサポートされています。あまり使われない いくつかの機能がなくなっています。これは主にだれも それを要求したことがなかったからです :-) これが最も必要とされることですから、最初にDBD::mysqlの使い方について 説明します。インストールについては、以下のセクション L<インストール>、 L、L<既知のバグ>をご覧下さい。 簡単な例に付いては、上記のL<例>をご覧下さい。 Perlからは、以下のステートメントでインタフェースを有効にします: use DBI; この後、複数のMySQLデータベース・サーバに接続し、簡単な オブジェクト指向インターフェースを介してそれらのデータベースへ 複数の問い合わせを送信することが出来ます。データベース・ハンドルと ステートメント・ハンドルという2つのタイプのオブジェクトが利用可能です。 Perl は以下のようなconnectメソッドでデータベース・ハンドルを返します: $dbh = DBI->connect("DBI:mysql:database=$db;host=$host", $user, $password, {RaiseError => 1}); 一度データベースにつながると、以下のようにしてSQLステートメントを 実行することが出来ます: my $query = sprintf("INSERT INTO foo VALUES (%d, %s)", $number, $dbh->quote("name")); $dbh->do($query); quoteとdoメソッドについての詳細はLをご覧下さい。 他の方法として以下のものがあります: $dbh->do("INSERT INTO foo VALUES (?, ?)", undef, $number, $name); この場合、quoteメソッドは自動的に行われます。Lでbind_paramメソッドも ご覧下さい。詳細に付いては以下のL<データベース・ハンドル>をご覧下さい。 結果を取り出したければ、以下のようにしてステートメント・ハンドルと 呼ばれるものを作成する必要があります: $sth = $dbh->prepare("SELECT * FROM $table"); $sth->execute(); このステートメント・ハンドルはいくつかの目的のために使うことができます。 何よりもまずデータの行を取り出せます: my $row = $sth->fetchow_hashref(); テーブルにIDとNAMEというカラムがあれば、$row はキーとしてIDとNAMEを 持つハッシュへのリファレンスとなります。詳細に付いては、 以下のL<ステートメント・ハンドル>をご覧下さい。 それでは、よりフォーマルなアプローチをしてきましょう: =head2 クラス・メソッド =over =item B use DBI; $dsn = "DBI:mysql:$database"; $dsn = "DBI:mysql:database=$database;host=$hostname"; $dsn = "DBI:mysql:database=$database;host=$hostname;port=$port"; $dbh = DBI->connect($dsn, $user, $password); Cは常に指定しなければいけません。 =over =item host =item port ホスト名。指定がないか、''が指定されれば、ローカル・マシン上でUNIXソケットの ためのデフォルトのポートで動いているMySQLデーモンがデフォルトとなります。 MySQLデーモンが標準でないポート番号で動いていれば、ポート番号を connectのC引数でI<ホスト名>とI<ポート番号>をコロン(C<:>)でつなげるか、 あるいはC引数を使って明示的に示すことが出来ます。 =item mysql_client_found_rows MySQLサーバーに接続しているときにフラグCLIENT_FOUND_ROWSを 有効(TRUE値)あるいは無効(FALSE値)にします。これは不思議な影響があります: mysql_client_found_rowsなしに、以下のような問い合わせをおこなうと UPDATE $table SET id = 1 WHERE id = 1 MySQLエンジンは常に0を返します。なぜならどの行も変更されないからです。 しかしmysql_client_found_rowsがあると、人によっては期待しているかもしれない idが1である行の数を返します。(少なくとも他のエンジンとの互換性のために) =item mysql_compression MySQL 3.22.3のものと同様、新しい機能がサポートされています: もしDSNにオプション"mysql_compression=1"が入っていれば、 クライアントとサーバとの通信は圧縮されます。 =item mysql_connect_timeout DSNにオプション"mysql_connect_timeout=##"が入っていると、そのサーバーへの 接続リクエストは指定された秒数後、成功していなければタイムアウトします。 =item mysql_read_default_file =item mysql_read_default_group これらのオプションは/etc/my.confや~./my.confのような構成ファイルを 読み込むために使うことが出来ます。デフォルトでは、MySQLの Cクライアント・ライブラリはクライアント・プログラム(mysql、mysqladmin、....) とは違って、何も構成ファイルを使いません。このため、以下のように 構成ファイルを読み込むように明示的に要求する必要があります: $dsn = "DBI:mysql:test;mysql_read_default_file=/home/joe/my.cnf"; $dbh = DBI->connect($dsn, $user, $password) オプションmysql_read_default_group は構成ファイルでのデフォルト・グループを 指定するために使うことが出来ます:通常これはIグループです。 以下の例をご覧下さい: [client] host=localhost [perl] host=perlhost (エントリの順番に注意してください! [client]と[perl]セクションを反対にすると 例は動きません!) この構成ファイルを読み込んだならば、典型的にはIに接続されます。 しかし以下のようにすると: $dsn = "DBI:mysql:test;mysql_read_default_group=perl;" . "mysql_read_default_file=/home/joe/my.cnf"; $dbh = DBI->connect($dsn, $user, $password); Iに接続されます。デフォルト・グループを指定し、ファイルを指定しないと、 デフォルトの構成ファイルがすべて読み込まれるということに注意してください。 詳細に付いてはC関数mysql_options()のドキュメントをご覧下さい。 =item mysql_socket MySQL 3.21.15のものと同様。サーバーに接続するために使われるUNIXソケットを 選択することが出来ます。以下のようにします: mysql_socket=/dev/mysql クライアントに組みこまれているソケットのための場所以外を使うのでなければ、 通常このオプションは必要ありません。 =item mysql_ssl true値で、MySQLデータベースに接続するときCLIENT_SSLフラグが有効に なります: mysql_ssl=1 これはサーバーとの通信が暗号化されるということを意味します。 mysql_sslを有効にすると、以下のフラグも使いたいと思うかもしれません: =item mysql_ssl_client_key =item mysql_ssl_client_cert =item mysql_ssl_ca_file =item mysql_ssl_ca_path =item mysql_ssl_cipher これらはmysql_sslが有効なとき、mysql_ssl_set呼び出しの対応する パラメータを指定するために使われます。 =item mysql_local_infile MySQL 3.23.49と同様に、LOAD DATAのためのLOCAL機能はデフォルトでは MySQLクライアント・ライブラリでは無効になっているかもしれません。 もしDSNにオプション"mysql_local_infile=1"が入っていると、 LOAD DATA LOCALが有効になります。(しかし、 サーバーがLOCALを却下するよう構成されているサーバーであっても このオプションは効力を持ちます。) =back =back =head2 プライベートなメタデータ・メソッド =over =item B my $drh = DBI->install_driver("mysql"); @dbs = $drh->func("$hostname:$port", '_ListDBs'); @dbs = $drh->func($hostname, $port, '_ListDBs'); @dbs = $dbh->func('_ListDBs'); C<$hostname>、ポートC<$port>で走っているmysqlデーモンによって 管理されている全てのデータベースのリストを返します。このメソッドは Cで走っているデータベースにはほとんど必要ありません: 可能であれば、この場合には移植性の高い以下のメソッドを使うべきです @dbs = DBI->data_sources("mysql"); ホスト名またはポート番号をCに与える方法がないということは、 このメソッドの設計上の問題です。このためだけにCをサポート しているのです。:-( =back =head2 サーバ管理 =over =item admin $rc = $drh->func("createdb", $dbname, [host, user, password,], 'admin'); $rc = $drh->func("dropdb", $dbname, [host, user, password,], 'admin'); $rc = $drh->func("shutdown", [host, user, password,], 'admin'); $rc = $drh->func("reload", [host, user, password,], 'admin'); または $rc = $dbh->func("createdb", $dbname, 'admin'); $rc = $dbh->func("dropdb", $dbname, 'admin'); $rc = $dbh->func("shutdown", 'admin'); $rc = $dbh->func("reload", 'admin'); サーバ管理のためには、サーバへの接続が必要です。この接続を取得するには 2つのオプションがあります。1つはドライバ・ハンドル(drh)を使い、 適切な引数(host デフォルトはlocalhost、user デフォルトは''、 password デフォルトは'')を指定します。ドライバ・ハンドルは以下のようにして 取得することができます $drh = DBI->install_driver('mysql'); もう1つは既にあるデータベース・ハンドル(dbh)の接続を再利用します。 管理目的のために使える関数はたった1つで、m(y)sqladminプログラムと同等です。 実行されるコマンドは第1引数に依存します: =over =item createdb データベース$dbnameを作成します。"m(y)sqladmin create $dbname"と同じです。 =item dropdb $dbnameというデータベースを削除します。"m(y)sqladmin drop $dbname"と同じです。 データベースの削除ではなにもI<プロンプトを出さない>ことに注意してください。 DBIからundoを可能にすることもできません。 一度dropDB()メソッドを発行すると、データベースは逝ってしまいます! これらのメソッドは自分のリスクのもとにお使いください。 =item shutdown データベース・エンジンを何も言わずにシャット・ダウンします。(プロンプトなしに!) "m((y)sqladmin shutdown"と同じです。 =item reload サーバ構成ファイル、そして/あるいはテーブルをリロードします。 アクセス権限を変更したり、新しいユーザを作ったときには特に重要です。 =back =back =head1 データベース・ハンドル DBD::mysqlドライバは以下のドライバ・ハンドルの属性をサポートして います(読込のみ)。 $errno = $dbh->{'mysql_errno'}; $error = $dbh->{'mysql_error}; $info = $dbh->{'mysql_hostinfo'}; $info = $dbh->{'mysql_info'}; $insertid = $dbh->{'mysql_insertid'}; $info = $dbh->{'mysql_protoinfo'}; $info = $dbh->{'mysql_serverinfo'}; $info = $dbh->{'mysql_stat'}; $threadId = $dbh->{'mysql_thread_id'}; これらはそれぞれ、mysql_errno(), mysql_error(), mysql_get_host_info(), mysql_info(), mysql_insert_id(), mysql_get_proto_info(), mysql_get_server_info(), mysql_stat() and mysql_thread_id()に対応します。 =head1 ステートメント・ハンドル DBD::mysqlのステートメント・ハンドルは多くの属性をサポートしています。 これらには以下の例のようにアクセスします、 my $numFields = $sth->{'NUM_OF_FIELDS'}; ほとんどの属性はIが成功した後でないと適性ではないことに 注意してください。そのような場合には、Cが返されます。 もっとも重要な例外はC属性です:これはドライバに mysql_store_resultではなく、mysql_use_resultを強制的に 使うようにします。mysql_use_resultはより速く、メモリ消費もより少ないのですが、 他のプロセスを妨害しがちです(これはmysql_store_resultがデフォルトである理由です) C属性を設定することは、以下のように使います: my $sth = $dbh->prepare("QUERY", { "mysql_use_result" => 1}); または my $sth = $dbh->prepare("QUERY"); $sth->{"mysql_use_result"} = 1; カラムに依存する属性、例えばI、カラム名は配列へのリファレンス として返されます。この配列インデックスはIまたは同類のメソッド によって返される配列でのインデックスに対応します。例えば以下のコードは テーブル名のヘッダを全ての行と一緒に出力します: my $sth = $dbh->prepare("SELECT * FROM $table"); if (!$sth) { die "Error:" . $dbh->errstr . "\n"; } if (!$sth->execute) { die "Error:" . $sth->errstr . "\n"; } my $names = $sth->{'NAME'}; my $numFields = $sth->{'NUM_OF_FIELDS'}; for (my $i = 0; $i < $numFields; $i++) { printf("%s%s", $i ? "," : "", $$names[$i]); } print "\n"; while (my $ref = $sth->fetchrow_arrayref) { for (my $i = 0; $i < $numFields; $i++) { printf("%s%s", $i ? "," : "", $$ref[$i]); } print "\n"; } 移植可能なアプリケーションでは、頭だけを大文字にしたり、大文字小文字を 混った名前の属性を使うように制限すべきです。名前が小文字の属性はDBD::mysqlで 提供されています。属性には以下のものが含まれます: =over =item ChopBlanks この属性はIがカラムの値の前と後ろについている空白を切り捨てるかを 決定します。空白の切捨てはI属性に影響を与えません。 =item mysql_insertid MySQLは自動的にユニークなキーの値を選ぶ機能があります。もしこれが起こると、 新しいIDがこの属性に格納されます。この属性にアクセスするもう1つの 方法は$dbh->{'mysql_insertid'}'を使うことです。この場合には$dbhを 使うということを注意してください!) =item mysql_is_blob ブール値の配列へのリファレンス:TRUEは、対応するカラムがblobであることを示します。 この属性はMySQLにのみ適正です。 =item mysql_is_key ブール値の配列へのリファレンス:TRUEは対応するカラムがキーであることを示します。 この属性はMySQLにのみ適正です。 =item mysql_is_num ブール値の配列へのリファレンス:TRUEは対応するカラムに数値が 入っていることを示します。 =item mysql_is_pri_key ブール値の配列へのリファレンス:TRUEは対応するカラムがプライマリ・キーで あることを示します。 =item mysql_is_auto_increment ブール値の配列へのリファレンス:TRUEは対応するカラムがAUTO_INCREMENT カラムであることを示します。これはMySQLにのみ適正です。 =item mysql_length =item mysql_max_length カラム・サイズの最大長の配列へのリファレンス。Iは 結果テーブルでの物理的に現れた最大長、Iは論理的に可能な最大です。 IはMySQLにのみ適正です。 =item NAME カラム名の配列へのリファレンス。 =item NULLABLE ブール値の配列へのリファレンス;TRUEは、このカラムにNULLが入っても いいことを示します。 =item NUM_OF_FIELDS I