Manager モジュール
Description
Manager モジュールは、データベースの構造を管理するためのメソッドを提供します。 これらのメソッドは、その機能によって分類され、データベース要素の 作成、編集 (alter あるいは update)、一覧および削除 (drop) といった機能があります。このドキュメントでは、 使用できるメソッドについて説明してその使用例を示します。 データベース "events_db" において、次のようなテーブルを 作成、変更そして削除するものとします。
events(id, name, datetime);
people(id, name);
event_participants(event_id, person_id);
Manager モジュールの機能を組み込むには、まず最初にそれを読み込む必要があります。
Manager モジュールの読み込み
<?php
require_once 'MDB2.php';
$dsn = 'pgsql://someuser:apasswd@somehost';
$mdb2 =& MDB2::factory($dsn);
if (PEAR::isError($mdb2)) {
die($mdb2->getMessage());
}
// Manager モジュールを読み込みます
$mdb2->loadModule('Manager');
?>
モジュールを組み込むと、このようにそのメソッドを使用することができます。
データベースの作成
<?php
// PHP5
$mdb2->createDatabase('events_db');
// PHP4 および PHP5
$mdb2->manager->createDatabase('events_db');
?>
このドキュメントでは、これ以降は PHP 5 互換の方法を使用します。
データベース要素の作成
これらのメソッドは、新しいデータベースやテーブル、インデックス、 制約そしてシーケンスを作成するものです。
データベースの作成
events_db データベースの作成および設定
<?php
// MDB2 の準備
require_once 'MDB2.php';
$dsn = 'mysql://root:test@localhost'; // DB 名を省略していることに注意しましょう
$mdb2 =& MDB2::factory($dsn);
// Manager モジュールを読み込みます
$mdb2->loadModule('Manager');
// データベースを作成します
$mdb2->createDatabase('events_db');
// 新しいデータベースで作業するように設定します
$mdb2->setDatabase('events_db');
// 次回以降の DSN は次のようになります
// mysql://root:test@localhost/events_db
?>
テーブルの作成
データベースが作成できたので、こんどはそこにテーブルを追加していきましょう。 メソッド createTable() には三つのパラメータを指定します。 それぞれテーブル名、フィールド定義の配列および追加のオプション (任意。RDBMS 固有のもの) となります。
events テーブルの作成
<?php
$definition = array (
'id' => array (
'type' => 'integer',
'unsigned' => 1,
'notnull' => 1,
'default' => 0,
),
'name' => array (
'type' => 'text',
'length' => 255
),
'datetime' => array (
'type' => 'timestamp'
)
);
$mdb2->createTable('events', $definition);
?>
定義配列のキーは、テーブルのフィールド名となります。 その値は配列で、必須のキー 'type' と、 'type' の値にもとづいたその他のキーで構成されます。 'type' キーの値は、MDB2 のデータ型と同じものです。 データ型によって、その他のオプションは変化します。
| データ型 | length | default | not null | unsigned |
|---|---|---|---|---|
| text | x | x | x | |
| boolean | x | x | ||
| integer | x | x | x | |
| decimal | x | x | ||
| float | x | x | ||
| timestamp | x | x | ||
| time | x | x | ||
| date | x | x | ||
| clob | x | x | ||
| blob | x | x |
createTable() の三番目のパラメータは、 そのテーブルの別のオプションです。 文字セットや照合順序、その他 RDBMS 固有のプロパティ (MySQL のテーブルエンジンなど) を指定します。 MySQL の場合の例を以下に示します。
people テーブルの作成
<?php
$table_options = array(
'comment' => 'Repository of people',
'charset' => 'utf8',
'collate' => 'utf8_unicode_ci',
'type' => 'innodb',
);
$definition = array (
'id' => array (
'type' => 'integer',
'unsigned' => 1,
'notnull' => 1,
'default' => 0,
),
'name' => array (
'type' => 'text',
'length' => 255
)
);
$mdb2->createTable('people', $definition, $table_options);
?>
サンプルデータベースの仕上げとして、 event_participants テーブルを作成するコードを示します。
event_participants テーブルの作成
<?php
$definition = array (
'event_id' => array (
'type' => 'integer',
'unsigned' => 1,
'notnull' => 1,
'default' => 0,
),
'person_id' => array (
'type' => 'integer',
'unsigned' => 1,
'notnull' => 1,
'default' => 0,
),
);
$mdb2->createTable('event_participants', $definition, $table_options);
?>
制約の作成
サンプルデータベースのテーブルでは、id が主キーでなければなりません。 主キーを作成するために使用するのが createConstraint() メソッドです。このメソッドのパラメータは、テーブル名と 制約名、そして定義配列の三つです。
配列 definition の完全な構造は、このようになります (これは、外部キー制約を表すものです)。
<?php
$definition = array (
'primary' => false,
'unique' => false,
'foreign' => true,
'check' => false,
'fields' => array (
'field1name' => array(), // ひとつのエントリがひとつのフィールドに対応します
'field2name' => array(), // フィールドの並び順とあわせます
'field3name' => array(
'sorting' => ascending|descending,
'position' => 3,
),
)
'references' => array(
'table' => name,
'fields' => array(
'field1name' => array( // ひとつのエントリがひとつの参照フィールドに対応します
'position' => 1,
),
)
'deferrable' => false,
'initiallydeferred' => false,
'onupdate' => CASCADE|RESTRICT|SET NULL|SET DEFAULT|NO ACTION,
'ondelete' => CASCADE|RESTRICT|SET NULL|SET DEFAULT|NO ACTION,
'match' => SIMPLE|PARTIAL|FULL,
);
?>
events テーブルおよび people テーブルの主キーの作成
<?php
$definition = array (
'primary' => true,
'fields' => array (
'id' => array()
)
);
$mdb2->createConstraint('events', 'keyname', $definition);
$mdb2->createConstraint('people', 'keyname', $definition);
?>
注意: RDBMS によっては、制約名を無視するものもあります。たとえば MySQL では、主キーを作成する際には メソッドコール時に指定した keyname の値を使用せず、PRIMARY を使用します。 また、外部キーを作成する際にも メソッドコール時に指定した keyname の値を使用せず、[tablename]_ibfk_[n] を使用します。
定義配列では、制約にどのフィールドを含めるのかを fields キーで指定します。 定義配列で使用できるその他のキーは primary と unique でこれらは boolean 値となります。
別のキーを event_participants で作成してみましょう。 これは、各行が一意でなければならない、つまり、 ある人間がひとつのイベントには一度しか参加しないというものです。 定義配列の fields には両方のフィールドを指定し、 unique キーを true に設定します。
unique 制約の作成
<?php
$definition = array (
'unique' => true,
'fields' => array (
'event_id' => array(),
'person_id' => array(),
)
);
$mdb2->createConstraint('event_participants', 'unique_participant', $definition);
?>
インデックスの作成
インデックスを作成するには createIndex() メソッドを使用します。このメソッドのシグネチャは createConstraint() と同じです。つまり、 テーブル名とインデックス名そして定義配列を指定します。 定義配列のキーはひとつ、fields で、 その値は連想配列となります。この連想配列には、 インデックスを構成するフィールドが含まれます。 フィールド情報は配列で指定し、そのキーは以下のようになります。
-
sorting には ascending あるいは descending を指定します。
-
length には整数値を指定します。
インデックスの作成
<?php
$definition = array(
'fields' => array(
'datetime' => array()
)
);
$mdb2->createIndex('events', 'event_timestamp', $definition);
?>
シーケンスの作成
MDB2 がシーケンスを処理する方法については、 こちら を参照ください。今回のサンプルデータベースの events テーブルでは、 'id' を自動インクリメントさせる必要があります。そのために使用するメソッドが nextId() で、これはシーケンスの次の値を取得します。 nextId() は、もしシーケンステーブルがなければ作成します。 しかし、事前にそれを createSequence() で作成しておくこともできます。このメソッドには、シーケンス名のほかに オプションでシーケンスの開始値を指定します。
シーケンスの作成
<?php
$mdb2->createSequence('events');
$mdb2->createSequence('people', 1);
?>
デフォルトの MDB2 の設定では、上の例は 二つのテーブル events_seq および people_seq を作成します。 それぞれのテーブルについて、ひとつのフィールド 'sequence' が存在します。しかし、このフィールド名やテーブル名の最後の '_seq' は変更可能です。変更するには、MDB2 のオプション seqname_format および seqcol_name を使用します。
データベースのテーブルの変更
一度作成したテーブルに対して、テーブルの名前の変更やフィールドの追加、削除、 名前の変更などを行うには alterTable() メソッドを使用します。alterTable() には三つのパラメータを指定します。それぞれテーブル名、 変更内容の定義そして boolean の "check-only" フラグとなります。 このフラグを true にすると、実際の変更は行われません。 指定した変更が、その RDBMS およびテーブルで実行可能かどうかのみを調べます。 二番目の引数 (変更内容の定義) は、これらのキーを持つ配列です。
-
name : テーブルの新しい名前。これが、唯一テーブル自身に関連するキーです。 それ以外のキーは、すべてフィールド定義に関するものです。
-
add : 追加するフィールド。
-
remove : 削除するフィールド。
-
change : 変更するフィールド。
-
rename : 名前を変更するフィールド。
データベース要素の一覧
データベース内に何があるかを見るには、list*() 系の関数を使用します。すなわち、以下のような関数です。
-
listDatabases()
-
listFunctions()
-
listSequences(): オプションで、データベース名をパラメータとして受け取ります。 省略した場合は、現在選択しているデータベースとみなします。
-
listTableConstraints(): テーブル名を受け取ります。
-
listTableFields(): テーブル名を受け取ります。
-
listTableIndexes(): テーブル名を受け取ります。
-
listTables(): オプションで、データベース名を受け取ります。
-
listTableTriggers(): テーブル名を受け取ります。
-
listTableViews(): テーブル名を受け取ります。
-
listUsers()
-
listViews(): オプションで、データベース名を受け取ります。
データベース要素の一覧
<?php
$dbs = $mdb2->listDatabases();
print_r($dbs);
/*
出力結果:
Array
(
[0] => information_schema
[1] => events_db
[2] => mysql
[3] => test
[4] => test_db
[5] => test_db_explain
[6] => test_mdb2
)
*/
$seqs = $mdb2->listSequences('events_db');
print_r($seqs);
/*
出力結果:
Array
(
[0] => events
[1] => people
)
*/
$cons = $mdb2->listTableConstraints('event_participants');
print_r($cons);
/*
出力結果:
Array
(
[0] => unique_participant
)
*/
$fields = $mdb2->listTableFields('events');
print_r($fields);
/*
出力結果:
Array
(
[0] => id
[1] => name
[2] => datetime
)
*/
$idx = $mdb2->listTableIndexes('events');
print_r($idx);
/*
出力結果:
Array
(
[0] => event_timestamp
)
*/
$tables = $mdb2->listTables();
print_r($tables);
/*
出力結果:
Array
(
[0] => event_participants
[1] => events
[2] => people
)
*/
// 現在はビューを作成するためのメソッドはありません。
// そこで、ここでは "手動で" 作成します
$sql = "CREATE VIEW names_only AS SELECT name FROM people";
$mdb2->exec($sql);
$sql = "CREATE VIEW last_ten_events AS SELECT * FROM events ORDER BY id DESC LIMIT 0,10";
$mdb2->exec($sql);
// ビューの一覧
$views = $mdb2->listViews();
print_r($views);
/*
出力:
Array
(
[0] => last_ten_events
[1] => names_only
)
*/
/*
MySQL ドライバでは、以下は実装されていません
listTableTriggers()
listTableViews()
listFunctions()
*/
?>
データベース要素の削除
上に示したすべての create*() 系メソッドについて、 対応する drop*() 系メソッドが存在します。これらによって、 データベースやテーブル、フィールド、インデックスあるいは制約を削除することができます。 drop*() 系のメソッドは、削除対象の項目が存在するかどうかをチェックしません。 したがって、結果が PEAR error であるかどうかを確認するようにしてください。
データベース要素の削除
<?php
// デフォルトでは、PEAR のエラーが発生したら、終了 (die) します
PEAR::setErrorHandling(PEAR_ERROR_DIE);
// これ以降の文で、一時的にエラー処理方法を変更します
PEAR::pushErrorHandling(PEAR_ERROR_RETURN);
// シーケンスを削除します
$result = $mdb2->dropSequence('存在しないシーケンス名');
if (PEAR::isError($result)) {
echo 'シーケンスが存在しません';
} else {
echo 'シーケンスを削除しました';
}
// 別のシーケンス
$result = $mdb2->dropSequence('people');
// 制約を削除します
$mdb2->dropConstraint('events', 'PRIMARY', true);
// 注意: 三番目のパラメータは、これが
// 主キーであることを示します
$mdb2->dropConstraint('event_participants', 'unique_participant');
// インデックスを削除します
$mdb2->dropIndex('events', 'event_timestamp');
// テーブル名を削除します
$mdb2->dropTable('events');
// データベースを削除します
$mdb2->dropDatabase('events_db');
// 通常のエラー処理に戻します
PEAR::popErrorHandling();
?>
忘却曲線を使ってこの知識を確実に記憶に残す
