Class-DBI-0.96 > Class::DBI


        Class::DBI - シンプルなデータベース抽象クラス


        package Music::DBI;
        use base 'Class::DBI';
        Music::DBI->connection('dbi:mysql:dbname', 'username', 'password');

        package Music::Artist;
        use base 'Music::DBI';
        Music::Artist->columns(All => qw/artistid name/);
        Music::Artist->has_many(cds => 'Music::CD');

        package Music::CD;
        use base 'Music::DBI';
        Music::CD->columns(All => qw/cdid artist title year/);
        Music::CD->has_many(tracks => 'Music::Track');
        Music::CD->has_a(artist => 'Music::Artist');
        Music::CD->has_a(reldate => 'Time::Piece',
                inflate => sub { Time::Piece->strptime(shift, "%Y-%m-%d") },
                deflate => 'ymd',

        Music::CD->might_have(liner_notes => LinerNotes => qw/notes/);

        package Music::Track;
        use base 'Music::DBI';
        Music::Track->columns(All => qw/trackid cd position title/); 

        #-- Meanwhile, in a nearby piece of code! --#

        my $artist = Music::Artist->create({ artistid => 1, name => 'U2' });

        my $cd = $artist->add_to_cds({ 
                cdid   => 1,
                title  => 'October',
                year   => 1980,

        # Oops, got it wrong.

        # etc.

        foreach my $track ($cd->tracks) {
                print $track->position, $track->title

        $cd->delete; # also deletes the tracks

        my $cd  = Music::CD->retrieve(1);
        my @cds = Music::CD->retrieve_all;
        my @cds = Music::CD->search(year => 1980);
        my @cds = Music::CD->search_like(title => 'October%');


Class::DBI provides a convenient abstraction layer to a database.


It not only provides a simple database to object mapping layer, but can be used to implement several higher order database functions (triggers, referential integrity, cascading delete etc.), at the application level, rather than at the database.

このモジュールは、オブジェクト・マッピングレイヤへの単純なデータベースを 提供するだけではない。データベースレベルよりもアプリケーションレベルで、 いくつかの高レベルな一般的的なデータベース機能(トリガー、参照統合、 カスケードデリート)を実装するのに用いられる。

This is particularly useful when using a database which doesn't support these (such as MySQL), or when you would like your code to be portable across multiple databases which might implement these things in different ways.

これらの機能をサポートしていないデータベース(例えばMySQLなど)を使う際には ことのほか役立つ。あるいは、こういったことを様々な方法で実装している 複数のデータベースに対して、あなたのコードを移植しようとしている際にも 便利である。

In short, Class::DBI aims to make it simple to introduce 'best practice' when dealing with data stored in a relational database.

要するに、リレーショナルデータベースに保持されているデータを扱うときに ”最前のやり方”を導入しやすくするのがClass::DBIの狙いなのだ。



You must have an existing database set up, have installed and the necessary DBD:: driver module for that database. See DBI and the documentation of your particular database and driver for details.

既存のデータベースを準備しなければならない。DBI.pmとそのデータベースに 必要なDBD::ドライバーモジュールがインストールされていなければならない。 詳細については、DBI及び、実際のデータベースとドライバーのドキュメントを 参照のこと。


Class::DBI works on a simple one class/one table model. It is your responsibility to have your database tables already set up. Automating that process is outside the scope of Class::DBI.

Class::DBIは、単純な”1クラス1テーブル”モデルで動作する。データベースを 既に準備の出来ている状態にするのはあなたの責任だ。このプロセスを自動化する のはClass::DBIの範疇外である。

Using our CD example, you might declare a table something like this:


        CREATE TABLE cd (
                cdid   INTEGER   PRIMARY KEY,
                artist INTEGER, # references 'artist'
                title  VARCHAR(255),
                year   CHAR(4),

It's usually wise to set up a "top level" class for your entire application to inherit from, rather than have each class inherit directly from Class::DBI. This gives you a convenient point to place system-wide overrides and enhancements to Class::DBI's behavior.

通常は各クラスを直接Class::DBIから継承させるよりも、”トップレベル”クラスを つくり、アプリケーション全体はそれを継承する方が賢いやり方だ。こうすることで システム全体でオーバーライドしたり、Class::DBIの振る舞いを向上させるといった 利点が得られる。

        package Music::DBI;
        use base 'Class::DBI';

Class::DBI needs to know how to access the database. It does this through a DBI connection which you set up by calling the connection() method.

Class::DBIはデータベースにアクセスする方法を知らねばならない。これは あなたが用意したDBI接続を通じてなされるのだが、それには connection() メソッドを呼び出す。

        Music::DBI->connection('dbi:mysql:dbname', 'user', 'password');

By setting the connection up in your application base class all the table classes that inherit from it will share the same connection.

アプリケーションベースクラスの接続が確立すれば、このクラスを継承している 全てのテーブルクラスが同じ接続を共有することになる。

        package Music::CD;
        use base 'Music::DBI';

Each class will inherit from your application base class, so you don't need to repeat the information on how to connect to the database.

各クラスはアプリケーションベースクラスを継承する。よって、データベース 接続方法の情報を繰り返す必要はない。


Inform Class::DBI what table you are using for this class:



This is done using the columns() method. In the simplest form, you tell it the name of all your columns (with the single primary key first):

これにはcolumns()メソッドを使って行う。最も単純な形式は、全カラムの名前を クラスに伝えることだ(最初のものが主キーになる)。

        Music::CD->columns(All => qw/cdid artist title year/);

If the primary key of your table spans multiple columns then declare them using a separate call to columns() like this:

テーブルの主キーが複数のカラムにまたがる場合は、次のようにして columns()を別々に呼び出して宣言する。

        Music::CD->columns(Primary => qw/pk1 pk2/);
        Music::CD->columns(Others => qw/foo bar baz/);

For more information about how you can more efficiently use subsets of your columns, see "LAZY POPULATION"

カラムのサブセットをより効率的に利用する方法については、"LAZY POPULATION" を参照。


That's it! You now have a class with methods to \create(), \retrieve(), \search() for, \update() and \delete() objects from your table, as well as accessors and mutators for each of the columns in that object (row).

準備完了! テーブルから生成されるオブジェクトに対してcreate()、retrieve()、 search()、update()およびdelete()するメソッドを持ったクラスを手に入れた。 もちろんそのオブジェクト(列)の各カラムに対するアクセサとミューテータも 持っている。

Let's look at all that in more detail:




        __PACKAGE__->connection($data_source, $user, $password, \%attr);

This sets up a database connection with the given information.


This uses Ima::DBI to set up an inheritable connection (named Main). It is therefore usual to only set up a connection() in your application base class and let the 'table' classes inherit from it.

Ima::DBIを使って継承可能なコネクション(Mainと名づけられる)を確立している。 そのため、あなたのアプリケーションのベースクラスでのみconnection()を使用し、 ”テーブル”クラスにはそれを継承させるのが一般的だ。

        package Music::DBI;
        use base 'Class::DBI';

        Music::DBI->connection('dbi:foo:dbname', 'user', 'password');

        package My::Other::Table;
        use base 'Music::DBI';

Class::DBI helps you along a bit to set up the database connection. connection() provides its own default attributes depending on the driver name in the data_source parameter. The connection() method provides defaults for these attributes:

Class::DBIは、ほんの少しだけデータベース接続のお手伝いをする。 connection()は、data_sourceパラメータ内のドライバー名に基づくデフォルト 属性値を提供する。connection()メソッドはデフォルトで以下の属性を提供する:

        FetchHashKeyName   => 'NAME_lc',
        ShowErrorStatement => 1,
        ChopBlanks         => 1,
        AutoCommit         => 1,

(Except for Oracle and Pg, where AutoCommit defaults 0, placing the database in transactional mode).

(OracleとPgは例外で、AutoCommitのデフォルトが0のため、データベースは トランザクションモードになっている)

The defaults can always be extended (or overridden if you know what you're doing) by supplying your own \%attr parameter. For example:

これらの既定値は\%attrパラメータを用意することで、いつでも拡張できる (あるいは自分が何をやっているのか理解していればオーバーライドも)。例えば:


We use the inherited RootClass of DBIx::ContextualFetch from Ima::DBI, and you should be very careful not to change this unless you know what you're doing!

Ima::DBIから継承したDBIx::ContextualFetchのRootClassを利用している。 だから、自分が何をやっているのかわかっていない限りは、このクラスを 変更しないよう気をつけるべきである。

動的なデータベース接続 / db_Main

It is sometimes desirable to generate your database connection information dynamically, for example, to allow multiple databases with the same schema to not have to duplicate an entire class hierarchy.

時には、データベース接続の情報を動的に生成したい場合がある。例えば、 同じスキーマを用いる複数のデータベースが完全なクラスヒエラルキーを 重複させないようにする場合。

The preferred method for doing this is to supply your own db_Main() method rather than calling connection(). This method should return a valid database handle, and should ensure it sets the standard attributes described above, preferably by combining $class->_default_attributes() with your own.

これを行なうのに好ましい方法は、connection()を呼び出すよりも、 あなた自身のdb_Main()メソッドを用意することだ。そのメソッドは妥当な データベースハンドルを返す必要があり、上で述べた標準的な属性値を確実に セットするべきだ。これはうまいことに、あなたのメソッドと $class->_default_attributes()とを結合することでできる。

Note that connection information is class data, and that changing it at run time may have unexpected behaviour for instances of the class already in existence.

注意して欲しいのだが、コネクション情報はクラスデータなので、実行時に それを変更してしまうと、既に存在しているそのクラスのインスタンスの 振る舞いを予期せぬものにしてしまうかもしれない。



        $table = Class->table;
        $table = $obj->table;

An accessor to get/set the name of the database table in which this class is stored. It -must- be set.

このクラスが保持するデータベーステーブルの名前を取得・設定する ためのアクセサ。テーブル名は設定*しなければ*ならない。

Table information is inherited by subclasses, but can be overridden.



        package Shop::Order;

When Class::DBI constructs SQL, it aliases your table name to a name representing your class. However, if your class's name is an SQL reserved word (such as 'Order') this will cause SQL errors. In such cases you should supply your own alias for your table name (which can, of course, be the same as the actual table name).

Class::DBIがSQLを構築する際、テーブル名に対するエイリアスとして、あなたの クラスを表す名前をあてる。しかし、クラス名がSQLの予約している単語(Orderなど) である場合、SQLエラーが発生する。このような場合に、テーブル名に対して独自の 別名を用意する必要がある(もちろん、これは実際のテーブル名と同じにできる)。

This can also be passed as a second argument to 'table':


        __PACKAGE__-->table('orders', 'orders');

As with table, this is inherited but can be overriden.


sequence / auto_increment


        $sequence_name = Class->sequence;
        $sequence_name = $obj->sequence;

If you are using a database which supports sequences and you want to use a sequence to automatically supply values for the primary key of a table, then you should declare this using the sequence() method:

もしもあなたがシーケンスをサポートしているデータベースを使っていて、かつ、 シーケンスを利用してテーブルの主キーの値を自動的に供給したいならば、 sequence()メソッドの使用を宣言するとよい:

        __PACKAGE__->columns(Primary => 'id');

Class::DBI will use the sequence to generate a primary key value when objects are created without one.

主キーなしでオブジェクトを生成すると、Class::DBIはシーケンスを利用して 主キーの値を生成する。

*NOTE* This method does not work for Oracle. However, Class::DBI::Oracle (which can be downloaded separately from CPAN) provides a suitable replacement sequence() method.

*注意* このメソッドはOracleでは動作しない。しかし、Class::DBI::Oracle (別途CPANからダウンロードできる)がsequence()メソッドのうまい代替手段を 提供している。

If you are using a database with AUTO_INCREMENT (e.g. MySQL) then you do not need this, and any call to create() without a primary key specified will fill this in automagically.

あなたの使っているデータベースがAUTO_INCREMENT機能を持っているなら (例:MySQL)、このメソッドを使う必要はない。主キー指定せずに create()を呼び出せば、魔法の如く自動的に主キーが生成される。

Sequence and auto-increment mechanisms only apply to tables that have a single column primary key. For tables with multi-column primary keys you need to supply the key values manually.

シーケンスと自動インクリメント機能は、主キーカラムが一つだけのテーブルに のみ適用される。複数の主キーカラムを持つテーブルに対しては、手動でキーの 値を設定してやらねばならない。


The following are methods provided for convenience to create, retrieve and delete stored objects. It's not entirely one-size fits all and you might find it necessary to override them.

ここで取り上げるのは、オブジェクトの生成、取り出し、削除の便宜を 図るためのメソッドである。メソッド単体であらゆる事態に対応できるわけでは ないので、必要に応じてそれらをオーバーライドすることになるだろう。


        my $obj = Class->create(\%data);

This is a constructor to create a new object and store it in the database.


%data consists of the initial information to place in your object and the database. The keys of %data match up with the columns of your objects and the values are the initial settings of those fields.

%dataは、オブジェクトとデータベースに入れられる初期情報で構成される。 %dataのキーはオブジェクトのカラムに対応し、%dataの値はそれらのフィールドに 初期状態でセットされる。

        my $cd = Music::CD->create({ 
                cdid   => 1,
                artist => $artist,
                title  => 'October',
                year   => 1980,

If the table has a single primary key column and that column value is not defined in %data, create() will assume it is to be generated. If a sequence() has been specified for this Class, it will use that. Otherwise, it will assume the primary key can be generated by AUTO_INCREMENT and attempt to use that.

もしテーブルが単一の主キーカラムを持ち、そのカラム値が%dataにおいて定義 されていないならば、create()は生成されるべき値を仮定する。sequence()が このクラス用に指定されていれば、それが利用される。そうでなければ、 AUTO_INCREMENTによって生成可能な主キーを仮定し、その利用が試みられる。

The before_create trigger is invoked directly after storing the supplied values into the new object and before inserting the record into the database. The object stored in $self may not have all the functionality of the final object after_creation, particularly if the database is going to be providing the primary key value.

与えられた値が新しいオブジェクトに格納された直後、かつ、そのレコードを データベースに挿入する前にbefore_createトリガが発動される。$self内に 保持されているオブジェクトは、after_creation[トリガ]の最終的なオブジェクト が持っている機能全てを持っているわけではないかもしれない。特に、 そのデータベースに主キー値が与えられようとしている場合は。

For tables with multi-column primary keys you need to supply all the key values, either in the arguments to the create() method, or by setting the values in a before_create trigger.

複数の主キーカラムを持つテーブルに対しては、全てのキー値をあなたが 提供しなければならない。これはcreate()への引数としてか、あるいは before_createトリガ内で値をセットすることによって行なう。

If the class has declared relationships with foreign classes via has_a(), you can pass an object to create() for the value of that key. Class::DBI will Do The Right Thing.

もしそのクラスがhas_a()を通じて外部キーを持つリレーションシップを 宣言しているなら、そのキーの値のためにオブジェクトをcreate()に渡す ことができる。Class::DBIはこれを適切に処理をするだろう。

After the new record has been inserted into the database the data for non-primary key columns is discarded from the object. If those columns are accessed again they'll simply be fetched as needed. This ensures that the data in the application is consistent with what the database actually stored.

新しいレコードがデータベースに挿入された後、主キーカラム以外のデータは そのオブジェクトから破棄される。これらのカラムに再度アクセスすると 必要に応じてデータベースから取り出される。これにより、アプリケーション内の データとデータベースが実際に保持しているものとの一致が保証される。

The after_create trigger is invoked after the database insert has executed.



        my $cd = Music::CD->find_or_create({ artist => 'U2', title => 'Boy' });

This checks if a CD can be found to match the information passed, and if not creates it.

これは、渡された情報に一致したCDが見つかるかどうかを調べ、もしも 存在しないならばデータを作成する。


        Music::CD->search(year => 1980, title => 'Greatest %')->delete_all;

Deletes this object from the database and from memory. If you have set up any relationships using has_many, this will delete the foreign elements also, recursively (cascading delete). $obj is no longer usable after this call.

このオブジェクトをデータベースとメモリから削除する。もしもhas_manyを 使って何らかのリレーションシップを設定しているなら、このメソッドは 外部要素も再帰的に削除する(カスケードデリート)。このメソッドを呼び 出した後、$objはもはや使用不可能となる。

Multiple objects can be deleted by calling delete_all on the Iterator returned from a search. Each object found will be deleted in turn, so cascading delete and other triggers will be honoured.

searchメソッドから返されたイテレータに対してdelete_allを呼び出すことで、 複数のオブジェクトを削除できる。各々のオブジェクトはその都度削除される。 そのため、カスケードデリートとその他のトリガは履行される。

The before_delete trigger is when an object instance is about to be deleted. It is invoked before any cascaded deletes. The after_delete trigger is invoked after the record has been deleted from the database and just before the contents in memory are discarded.

オブジェクトインスタンスが削除され始めるときが、before_deleteトリガの 発動するときである。このトリガはカスケードデリートの前に発動する。 after_deleteトリガは、レコードがデータベースから削除された後、かつ、 メモリ内のコンテンツが破棄される直前に発動される。


We provide a few simple search methods, more to show the potential of the class than to be serious search methods.

我々はわずかだがシンプルな検索用メソッドを提供する。これは大真面目な検索 メソッドである以上に、そのクラスの潜在的能力を示している。


        $obj = Class->retrieve( $id );
        $obj = Class->retrieve( %key_values );

Given key values it will retrieve the object with that key from the database. For tables with a single column primary key a single parameter can be used, otherwise a hash of key-name key-value pairs must be given.

キーの値を指定すると、データベースからそのキーを持ったオブジェクトを 取り出す。ひとつのカラム主キーを持ったテーブルに対しては、一つの パラメータが使用できる。そうでなければ、キー名・キー値のペアとなる ハッシュを指定しなければならない。

        my $cd = Music::CD->retrieve(1) or die "No such cd";


        my @objs = Class->retrieve_all;
        my $iterator = Class->retrieve_all;

Retrieves objects for all rows in the database. This is probably a bad idea if your table is big, unless you use the iterator version.

データベースの全行からオブジェクトを取り出す。テーブルが大きな場合に イテレータ版を使わないなら、恐らくこの方法はまずいことになるだろう。

        @objs = Class->search(column1 => $value, column2 => $value ...);

This is a simple search for all objects where the columns specified are equal to the values specified e.g.:

このメソッドは単純に、指定したカラムと指定した値が等しい全オブジェクトを 探し出す。例えば:

        @cds = Music::CD->search(year => 1990);
        @cds = Music::CD->search(title => "Greatest Hits", year => 1990);

You may also specify the sort order of the results by adding a final hash of arguments with the key 'order_by':

引数の最後に'order_by'というキーのハッシュを加えることで、結果に対して ソート順も指定できる。

        @cds = Music::CD->search(year => 1990, { order_by=>'artist' });


        @objs = Class->search_like(column1 => $like_pattern, ....);

This is a simple search for all objects where the columns specified are like the values specified. $like_pattern is a pattern given in SQL LIKE predicate syntax. '%' means "any one or more characters", '_' means "any single character".

このメソッドは単純に、指定したカラムが指定した値と似ている全オブジェクトを 探し出す。$like_patternは、SQLのLIKE叙述構文で与えられたパターンである。 '%'は”一つないしはそれ以上の任意のキャラクタ”を、'_'は”任意の一キャラクタ” を意味している。

        @cds = Music::CD->search_like(title => 'October%');
        @cds = Music::CD->search_like(title => 'Hits%', artist => 'Various%');

You can also use 'order_by' with these, as with search().



        my $it = Music::CD->search_like(title => 'October%');
        while (my $cd = $it->next) {
                print $cd->title;

Any of the above searches (as well as those defined by has_many) can also be used as an iterator. Rather than creating a list of objects matching your criteria, this will return a Class::DBI::Iterator instance, which can return the objects required one at a time.

上記の検索メソッドは(has_manyによる定義と同様)イテレータとしても使える。 これは基準に適合したオブジェクトのリストを生成するのではなくて、 Class::DBI::Iteratorインスタンスを返す。このインスタンスは必要な オブジェクトを一度に返すことができる。

Currently the iterator initially fetches all the matching row data into memory, and defers only the creation of the objects from that data until the iterator is asked for the next object. So using an iterator will only save significant memory if your objects will inflate substantially when used.

現在のところ、イテレータはまず最初に適合した全ての行データをメモリに フェッチし、イテレータが次のオブジェクトを要求されるまで、そのデータから オブジェクトを生成するのを遅延するだけである。そのため、オブジェクトを 利用した時、実際的にそのオブジェクトがインフレートする場合にのみ、 イテレータの利用でメモリが大幅に節約できるだろう。

In the case of has_many relationships with a mapping method, the mapping method is not called until each time you call 'next'. This means that if your mapping is not a one-to-one, the results will probably not be what you expect.

マッピングメソッドを伴うhas_manyリレーションシップの場合、あなたが'next'を 呼び出すまでマッピングメソッドは呼ばれない。このことは、マッピングが一対一で ないなら、その結果は恐らくあなたが期待するようなものにはならないということを 意味している。



You can also subclass the default iterator class to override its functionality. This is done via class data, and so is inherited into your subclasses.

デフォルトのイテレータクラスのサブクラスをつくることで、その機能を オーバーライドできる。これはクラスデータを通じてなされるので サブクラスへ継承される。


        my $obj = Class->construct(\%data);

This is used to turn data from the database into objects, and should thus only be used when writing constructors. It is very handy for cheaply setting up lots of objects from data for without going back to the database.

このメソッドは、データベースからのデータをオブジェクトに変えるのに用いる。 それゆえ、コンストラクタを書くときだけ使用するべきである。 データベースへ戻りに行かずとも、データから大量のオブジェクトを手軽に 用意できる点が大変便利だ。

For example, instead of doing one SELECT to get a bunch of IDs and then feeding those individually to retrieve() (and thus doing more SELECT calls), you can do one SELECT to get the essential data of many objects and feed that data to construct():

例えばSELECTでIDの束を取り出し、それらのIDを個々retrieve()に与える (つまり多くのSELECTコールを行なうということ)代わりに、一つのSELECTで 多くのオブジェクトの実質データを取り出し、そのデータをconstruct()に与え られる。

         return map $class->construct($_), $sth->fetchall_hash;

The construct() method creates a new empty object, loads in the column values, and then invokes the select trigger.

construct()メソッドは新規の空オブジェクトを生成し、そのカラムに値を ロードする。そしてそれからselectトリガを発生させる。



        $new_obj = $obj->copy;
        $new_obj = $obj->copy($new_id);
        $new_obj = $obj->copy({ title => 'new_title', rating => 18 });

This creates a copy of the given $obj, removes the primary key, sets any supplied column values and calls create() to insert a new record in the database.

このメソッドは、$objのコピーをつくり、主キーを削除し、与えられたカラムの 値をセットし、そしてcreate()を呼んで新たなレコードをデータベースに挿入する。

For tables with a single column primary key, copy() can be called with no parameters and the new object will be assigned a key automatically. Or a single parameter can be supplied and will be used as the new key.

主キーが一つだけのテーブルは、copy()をパラメータ無しで呼べる。 この場合新しいオブジェクトには自動的に主キーが割り当てられる。 あるいはパラメータを一つ与えると、それが新しい主キーとして使われる。

For tables with a multi-olumn primary key, copy() must be called with parameters which supply new values for all primary key columns, unless a before_create trigger will supply them. The create() method will fail if any primary key columns are not defined.

複数の主キーを持つテーブルでは、全ての主キー用に新しい値を提供しないといけ ないので、before_createがそれらの新しい値を提供しない限り、パラメータを つけてcopy()を呼ばなければならない。主キーを定義しないとcreate()メソッドは 失敗する。

        my $blrunner_dc = $blrunner->copy("Bladerunner: Director's Cut");
        my $blrunner_unrated = $blrunner->copy({
                Title => "Bladerunner: Director's Cut",
                Rating => 'Unrated',


        my $new_obj = Sub::Class->move($old_obj);
        my $new_obj = Sub::Class->move($old_obj, $new_id);
        my $new_obj = Sub::Class->move($old_obj, \%changes);

For transferring objects from one class to another. Similar to copy(), an instance of Sub::Class is created using the data in $old_obj (Sub::Class is a subclass of $old_obj's subclass). Like copy(), you can supply $new_id as the primary key of $new_obj (otherwise the usual sequence or autoincrement is used), or a hashref of multiple new values.

あるクラスから別のクラスへとオブジェクトを移動する。copy()と同じように $old_obj内のデータを使ってSub::Classのインスタンスを生成する(Sub::Classは $old_objのサブクラスのサブクラス)。copy()同様、$new_objの主キーとして $new_idを与えるか(与えなければ通常のシーケンス、あるいは自動インクリメントが 用いられる)、複数の新しい値のハッシュリファレンスを与える。


        __PACKAGE__->add_trigger(trigger_point_name => \&code_to_execute);

        # e.g.

        __PACKAGE__->add_trigger(after_create  => \&call_after_create);

It is possible to set up triggers that will be called at various points in the life of an object. Valid trigger points are:

オブジェクトの生成消滅までの様々なポイントで呼び出すトリガを設定できる。 適切なポイントは以下とおり:

        before_create       (deflationでも利用される)
        before_set_$column  (add_constraintによっても利用される)
        after_set_$column   (inflationならびにhas_aによっても利用される)
        before_update       (deflationならびにmight_haveによっても利用される)
        select              (inflationならびにconstructと_fleshによって利用される)

You can create any number of triggers for each point, but you cannot specify the order in which they will be run. Each will be passed the object being dealt with (whose values you may change if required), and return values will be ignored.

各ポイント毎に任意の数のトリガをつくれるが、それらが実行される順番を 指定することはできない。各トリガにはデフォルトでオブジェクトが渡され (必要ならオブジェクトの値を変更する)、戻り値は無視される。

All triggers are passed the object they are being fired for. Some triggers are also passed extra parameters as name-value pairs. The individual triggers are documented with the methods that trigger them.

全てのトリガには、トリガを引き起こしたオブジェクトが渡される。また、 いくつかのトリガには、名前と値のペアによる追加のパラメータが渡される。 個々のトリガに関するドキュメントは、それを起こすメソッドのところで触れている。


        __PACKAGE__->add_constraint('name', column => \&check_sub);

        # 例

        __PACKAGE__->add_constraint('over18', age => \&check_age);

        # シンプルな例
        sub check_age { 
                my ($value) = @_;
                return $value >= 18;

        # クロスフィールドチェック - age < 18 ならSSNを持たねばならない
        sub check_age { 
                my ($value, $self, $column_name, $changing) = @_;
                return 1 if $value >= 18;     # 十分な年齢だ
                return 1 if $changing->{SSN}; # SSN (社会保障番号) を与えられる
                return 0 if !ref($self);      # これはcreateなのでSSNを持っていない
                return 1 if $self->ssn;       # 既にデータベース上にある
                return 0;                     # どこにもSSNを発見できなかった

It is also possible to set up constraints on the values that can be set on a column. The constraint on a column is triggered whenever an object is created and whenever the value in that column is being changed.

カラムに設定できない値に対しても制約は設定できる。オブジェクトが生成される ときはいつでも、そしてそのカラムの値が変更されるときはいつでも、カラムに 対する制約が発動される。

The constraint code is called with four parameters:


        - The new value to be assigned
        - The object it will be assigned to
        (or class name when initially creating an object)
        - The name of the column
        (useful if many constraints share the same code)
        - A hash ref of all new column values being assigned
        (useful for cross-field validation)

        - 代入される新しい値
        - 代入されるオブジェクト(最初にオブジェクトがcreateされるときはクラス名)
        - カラム名(たくさんの制約が同じコードを共有している場合に便利)
        - 代入される新しいカラム値全てのハッシュリファレンス

The constraints are applied to all the columns being set before the object data is changed. Attempting to create or modify an object where one or more constraint fail results in an exception and the object remains unchanged.

制約は、そのオブジェクトデータが変更される前に、設定される全てのカラムに 対して適用される。オブジェクトの生成や変更を試み、一つ以上の制約が 失敗して例外を発生させると、そのオブジェクトは変更されないままである。

Note 1: Constraints are implemented using before_set_$column triggers. This will only prevent you from setting these values through a the provided create() or set() methods. It will always be possible to bypass this if you try hard enough.

注意1:制約はbefore_set_$columnトリガを使って実装されている。このため、 提供されているcreate()やset()メソッドを通じてのみ、それらの値の設定を 妨げられるだろう。あなたが十分苦労をすればいつでも抜け道が可能だ。

Note 2: When an object is created constraints are currently only checked for column names included in the parameters to create(). This is probably a bug and is likely to change in future.

注意2:オブジェクトが生成されるとき、現在のところ制約はcreate()に 渡されたパラメータに含まれるカラム名だけをチェックする。これは 恐らくバグであり、将来は変更されるだろう。


        Film->constrain_column(year => qr/\d{4}/);
        Film->constrain_column(rating => [qw/U Uc PG 12 15 18/]);

Simple anonymous constraints can also be added to a column using the constrain_column() method. By default this takes either a regex which must match, or a reference to a list of possible values.

constrain_column()メソッドを使えば、シンプルな無名制約をカラムに 追加できる。デフォルトでこのメソッドは、マッチしなければならない 正規表現か、取り得る値のリストリファレンスを受け取る。

However, this behaviour can be extended (or replaced) by providing a constraint handler for the type of argument passed to constrain_column. This behavior should be provided in a method named "_constrain_by_$type", where $type is the moniker of the argument. For example, the two shown above would be provided by _constrain_by_array() and _constrain_by_regexp().

ただしこの振る舞いは、constrain_columnに渡す引数の型に対する 制約ハンドラを用意することで、拡張(ないしは置き換え)できる。 これは"_constrain_by_$type"と名づけられたメソッド内で提供され、 ここで$typeは引数のmonikerのことである。例えば上の二つの例は、 _constrain_by_array()と_constrain_by_regexp()によって提供されている。


Before an object is assigned data from the application (via create or a set accessor) the normalize_column_values() method is called with a reference to a hash containing the column names and the new values which are to be assigned (after any validation and constraint checking, as described below).

アプリケーションから(createかsetアクセサを通じて)オブジェクトに データが割り当てられる前に、ハッシュへのリファレンスを伴って normalize_column_values()メソッドが呼び出される。ハッシュはカラム名と 割り当てられる新しい値を含む(下記にあるように、妥当性チェックと制約 チェックの後)。

Currently Class::DBI does not offer any per-column mechanism here. The default method is empty. You can override it in your own classes to normalize (edit) the data in any way you need. For example the values in the hash for certain columns could be made lowercase.

現在のところ、Class::DBIはカラム毎のチェックメカニズムを提供していない。 デフォルトのメソッドは空だ。あなた自身のクラス内で、望むやり方で メソッドをオーバーライドすればデータの正規化(編集)が行える。例えば、 ハッシュ内のあるカラムの値を小文字にするとか。

The method is called as an instance method when the values of an existing object are being changed, and as a class method when a new object is being created.

既存のオブジェクトの値が変更されるとき、このメソッドはインスタンスメソッド として呼び出される。そして新しいオブジェクトが生成されるときには、クラス メソッドとして呼び出される。


Before an object is assigned data from the application (via create or a set accessor) the validate_column_values() method is called with a reference to a hash containing the column names and the new values which are to be assigned.

アプリケーションから(createかsetアクセサを通じて)オブジェクトにデータが 割り当てられる前に、validate_column_values()が呼び出される。このメソッド には、カラム名と割り当てられる新しい値を含んだハッシュへのリファレンスが 渡される。

The method is called as an instance method when the values of an existing object are being changed, and as a class method when a new object is being created.

既存のオブジェクトの値が変更されるとき、このメソッドはインスタンスメソッド として呼び出される。そして新しいオブジェクトが生成されるときには、クラス メソッドとして呼び出される。

The default method calls the before_set_$column trigger for each column name in the hash. Each trigger is called inside an eval. Any failures result in an exception after all have been checked. The exception data is a reference to a hash which holds the column name and error text for each trigger error.

デフォルトのメソッドは、ハッシュ内の各カラムに対するbefore_set_$column トリガを呼び出す。何か失敗すると、全てチェックし終えた後に例外を発生 させる。この例外データは、各トリガのエラー毎にカラム名とエラーテキストを 含んだハッシュリファレンスである。

When using this mechanism for form data validation, for example, this exception data can be stored in an exception object, via a custom _croak() method, and then caught and used to redisplay the form with error messages next to each field which failed validation.

フォームデータの妥当性チェックにこのメカニズムを使うと、例えば、例外 データをカスタマイズした_croak()を通じて例外オブジェクトに格納してから 捕捉できる。そして妥当性チェックに失敗した各フィールドの横にエラー メッセージを出しつつ、再度フォームの表示に利用できる。


All errors that are generated, or caught and propagated, by Class::DBI are handled by calling the _croak() method (as an instance method if possible, or else as a class method).

エラーが発生、あるいは捕捉されて伝搬すると、Class::DBIは _croak()メソッドを呼び出して処理を行う(可能ならインスタンス メソッドとして、さもなければクラスメソッドとして)。

The _croak() method is passed an error message and in some cases some extra information as described below. The default behaviour is simply to call Carp::croak($message).

_croak()メソッドにはエラーメッセージが渡されるが、場合によっては 下記に示したように、追加情報が渡される。デフォルトの振る舞いは 単にCarp::croak($message)を呼び出すだけである。

Applications that require custom behaviour should override the _croak() method in their application base class (or table classes for table-specific behaviour). For example:

独自の振る舞いを必要とするアプリケーションでは、ベースクラスにおいて _croak()メソッドをオーバーライドすること(テーブル独自の振る舞いは テーブルクラスでオーバーライドする)。例えば:

        use Error;

        sub _croak {
                my ($self, $message, %info) = @_;
                # 無視する予定の二重挿入エラー以外は
                # エラーを例外オブジェクトに変換
                Error->throw(-text => $message, %info)
                        unless $message =~ /^Can't insert .* duplicate/;

The _croak() method is expected to trigger an exception and not return. If it does return then it should use return; so that an undef or empty list is returned as required depending on the calling context. You should only return other values if you are prepared to deal with the (unsupported) consequences.

_croak()メソッドは例外を発生させることが期待されるので、returnしない。 もし本当にreturnするなら、return;とすること。こうすれば呼び出された 文脈に応じてundefか空リストが返される。もしも(サポートしていない)結果 を処理する準備ができているなら、他の値を返してもよい。

For exceptions that are caught and propagated by Class::DBI, $message includes the text of $@ and the original $@ value is available in $info{err}. That allows you to correctly propagate exception objects that may have been thrown 'below' Class::DBI (using Exception::Class::DBI for example).

Class::DBIが捕捉・伝搬した例外では、$messageは$@のテキストを含んでおり、 オリジナルの$@の値は$info{err}から利用できる。これを使ってClass::DBI”に” 投げられるであろう例外オブジェクトを正しく伝搬できる(例えば Exception::Class::DBIを使って)。

Exceptions generated by some methods may provide additional data in $info{data} and, if so, also store the method name in $info{method}. For example, the validate_column_values() method stores details of failed validations in $info{data}. See individual method documentation for what additional data they may store, if any.

あるメソッドによって発生した例外は$info{data}に追加データを提供する。 そしてその場合、$info{method}にはメソッド名も格納される。例えば、 validate_column_values()メソッドは$info{data}に失敗した妥当性チェックの 詳細を格納する。どんな追加データが保持されるかについては、(もしあれば) 個々のメソッドのドキュメントを参照してもらいたい。

警告 (Warning)

All warnings are handled by calling the _carp() method (as an instance method if possible, or else as a class method). The default behaviour is simply to call Carp::carp().

全ての警告は_carp()メソッドを呼び出して処理される(可能なら インスタンスメソッドとして、そうでなければクラスメソッドとして)。 デフォルトの振る舞いは、単にCarp::carp()を呼び出すだけだ。



Class::DBI inherits from Class::Accessor and thus provides individual accessor methods for every column in your subclass. It also overrides the get() and set() methods provided by Accessor to automagically handle database reading and writing. (Note that as it doesn't make sense to store a list of values in a column, set() takes a hash of column => value pairs, rather than the single key => values of Class::Accessor).

Class::DBIはClass::Accessorを継承しているので、あなたのサブクラスにある カラム毎に個々のアクセサを提供する。また、Accessorが提供するget()とset() メソッドをオーバーライドして、データベースの読み書きを自動的に処理する ようにする(あるカラムの値のリストを格納するという意味ではないことに注意、 set()は column => value ペアのハッシュを取るのであって、 key => Class::Accessorの複数値、をとるのではない)。


        $value = $obj->get($column_name);
        @values = $obj->get(@column_names);

        $obj->set($column_name => $value);
        $obj->set($col1 => $value1, $col2 => $value2 ... );

These methods are the fundamental entry points for getting and setting column values. The extra accessor methods automatically generated for each column of your table are simple wrappers that call these get() and set() methods.

これらのメソッドは、カラム値の取得と設定の基礎をなすエントリーポイント である。あなたのテーブルの各カラム毎に自動で生成される追加のアクセサ メソッドは、単純にこれらget()とset()メソッドのラッパーである。

The set() method calls normalize_column_values() then validate_column_values() before storing the values. The before_set_$column trigger is invoked by validate_column_values(), checking any constraints that may have been set up. The after_set_$column trigger is invoked after the new value has been stored.

set()メソッドはnormalize_column_values()を呼び出し、それから値を格納する 前にvalidate_column_values()を呼び出す。before_set_$columnトリガは validate_column_values()によって発動され、用意されていた制約のチェックを 行う。after_set_$columnトリガは、その新しい値が格納された後で発動する。

It is possible for an object to not have all its column data in memory (due to lazy inflation). If the get() method is called for such a column then it will select the corresponding group of columns and then invoke the select trigger.

オブジェクトは、一部のカラムデータをメモリに持たないでいることが可能だ (遅延インフレーションによる)。そのようなカラムに対してget()メソッドが 呼ばれると、メソッドは対応するカラムグループを選び、selectトリガを 発動する。


accessor_name / mutator_name

If you want to change the name of your accessors, you need to provide an accessor_name() method, which will convert a column name to a method name.

アクセサの名前を変更したいなら、accessor_name()メソッドを用意することに なる。これはカラム名をメソッド名に変換する。

e.g: if your local naming convention was to prepend the word 'customer' to each column in the 'customer' table, so that you had the columns 'customerid', 'customername' and 'customerage', you would end up with code filled with calls to $customer->customerid, $customer->customername, $customer->customerage etc. By creating an accessor_name method like:

例えば:あなたの名前の付け方の慣習から、'customer'テーブルの内の 各コラムに対して'customer'という単語を付け加え、'customerid'、 'customername'そして'customerage'を持つとする。あなたのコードは $customer->customerid、$customer->customername、$customer->customerage を呼び出すだろう。そこで以下のaccessor_nameメソッドをつくることによって:

        sub accessor_name {
                my ($class, $column) = @_;
                $column =~ s/^customer//;
                return $column;

Your methods would now be the simpler $customer->id, $customer->name and $customer->age etc.

メソッドはよりシンプルに$customer->id、$customer->nameそして $customer->age等々となる。

Similarly, if you want to have distinct accessor and mutator methods, you would provide a mutator_name() method which would return the name of the method to change the value:

似たようなものだが、あなたがアクセサメソッドとミューテターメソッドを 区別したいなら、mutator_name()を用意する。このメソッドは、値を変更する ためのメソッドの名前を返す:

        sub mutator_name {
                my ($class, $column) = @_;
                return "set_$column";

If you override the mutator_name, then the accessor method will be enforced as read-only, and the mutator as write-only.

mutator_nameをオーバーライドすると、アクセサメソッドは強制的に read-onlyになり、ミューテータはwrite-onlyとなる。

update vs 自動update

There are two modes for the accessors to work in: manual update and autoupdate. When in autoupdate mode, every time one calls an accessor to make a change an UPDATE will immediately be sent to the database. Otherwise, if autoupdate is off, no changes will be written until update() is explicitly called.

アクセサと協調して動作する二つのモード:updateとautoupdate。 autoupdateモードの場合、アクセサを呼び出して変更を行なうたびに、 直ちにデータベースにUPDATEが送られる。それ以外、autoupdateがオフの場合、 update()を明示的に呼び出さない限り、変更は書き込まれない。

This is an example of manual updating:


        # NumExplodingSheep()とRating()の呼び出しはメモリ内に変更を加える
        # だけで、データベースを変更しない。ひとたびupdate()を呼び出すと
        # 変更は一挙にデータベースに書き込まれる。

And of autoupdating:


        # このオブジェクトに対して自動更新を有効にする

        # アクセサを呼ぶ毎に新しい値が直ちに書き込まれる

Manual updating is probably more efficient than autoupdating and it provides the extra safety of a discard_changes() option to clear out all unsaved changes. Autoupdating can be more convenient for the programmer. Autoupdating is off by default.

手動更新はたぶん自動更新よりも効率的だ。そしてdiscard_changes()を使う ことで未セーブの変更を全てクリアするという、安全装置が加わる。 自動更新は、プログラマにとっては、より便利になり得る。自動更新は デフォルトで無効になっている。

If changes are left un-updated or not rolledback when the object is destroyed (falls out of scope or the program ends) then Class::DBI's DESTROY method will print a warning about unsaved changes.

(スコープから外れるかプログラムが終了することで)オブジェクトが破壊 されるときに、変更点が未更新のままだったり、ロールバックしなかったりすると、 Class::DBIのDESTROYメソッドは未セーブの変更に関する警告を発する。


        $update_style = Class->autoupdate;

        $update_style = $obj->autoupdate;

This is an accessor to the current style of auto-updating. When called with no arguments it returns the current auto-updating state, true for on, false for off. When given an argument it turns auto-updating on and off: a true value turns it on, a false one off.

これは現在の自動更新状態へのアクセサである。引数無しでメソッドを 呼び出すと、現在の自動更新状態、有効なら真、無効なら偽が返される。 引数を与えると自動更新を有効あるいは無効にする: 真値なら有効、偽値なら無効。

When called as a class method it will control the updating style for every instance of the class. When called on an individual object it will control updating for just that object, overriding the choice for the class.

クラスメソッドとして呼ぶと、全てのインスタンスに対して更新スタイルを 制御する。個々のオブジェクトで呼び出した場合は、クラスに対するスタイルを オーバーライドして、そのオブジェクトに対する制御を行なう。

        __PACKAGE__->autoupdate(1);     # クラスに対して自動更新を有効

        $obj = Class->retrieve('Aliens Cut My Hair');
        $obj->autoupdate(0);      # このオブジェクトでは自動更新を無効

The update setting for an object is not stored in the database.




If "autoupdate" is not enabled then changes you make to your object are not reflected in the database until you call update(). It is harmless to call update() if there are no changes to be saved. (If autoupdate is on there'll never be anything to save.)

"autoupdate"が有効でない場合、オブジェクトに対して行なった変更は、 update()を呼び出すまで、データベースに反映されない。セーブするべき 変更点なしにupdate()を呼んでも害は無い(自動更新が有効なら、セーブ するべきことは何も無いだろう)。

Note: If you have transactions turned on for your database (but see "TRANSACTIONS" below) you will also need to call dbi_commit(), as update() merely issues the UPDATE to the database).

注意:データベースのトランザクションを有効にしている場合(下の "トランザクション"を参照)、さらにdbi_commitを呼び出す必要がある。 というのも、update()は単にデータベースにUPDATEを送るだけだからだ。

After the database update has been executed, the data for columns that have been updated are deleted from the object. If those columns are accessed again they'll simply be fetched as needed. This ensures that the data in the application is consistent with what the database actually stored.

データベースの更新が実行された後、更新されたカラムのデータは オブジェクトから削除される。再度これらのカラムにアクセスすると、必要に 応じてデータベースから取り出してくる。これによって、アプリケーション内の データとデータベースが実際に保持しているものとの一致が保証される。

When update() is called the before_update($self) trigger is always invoked immediately.

update()を呼び出すと、常に直ちにbefore_update($self)トリガが 発動される。

If any columns have been updated then the after_update trigger is invoked after the database update has executed and is passed: ($self, discard_columns => \@discard_columns, rows => $rows)

何らかのカラムが更新されると、データベースの更新が実行された後、 after_updateトリガが発動する。渡されるのは: ($self, discard_columns => \@discard_columns, rows => $rows)

(where rows is the return value from the DBI execute() method).


The trigger code can modify the discard_columns array to affect which columns are discarded.

このトリガのコードは、discard_columns配列を変更することで、どの カラムを破棄するかに影響を及ぼせる。

For example:


        Class->add_trigger(after_update => sub {
                my ($self, %args) = @_;
                my $discard_columns = $args{discard_columns};
                # 'foo'で始まるフィールドの更新がなされた場合、md5_hashカラムは
                # 破棄される。なぜならmd5_hashはトリガによって変更されてしまう
                # からだ。
                push @$discard_columns, 'md5_hash' if grep { /^foo/ } @$discard_columns;

Take care to not delete a primary key column unless you know what you're doing.

自分が何をしているのかわかっていないなら、主キーを削除しないように 注意すること。

The update() method returns the number of rows updated, which should always be 1, or else -1 if no update was needed. If the record in the database has been deleted, or its primary key value changed, then the update will not affect any records and so the update() method will return 0.

update()メソッドは更新された行の数を返す。これは常に1を返すか、あるいは 更新する必要がなかった場合には-1が返る。データベース内のレコードが削除 されると、あるいは主キーが変更されると、更新はいかなるレコードにも影響を 与えない。そのため、update()メソッドは0を返す。



Removes any changes you've made to this object since the last update. Currently this simply discards the column values from the object.

最後に更新をしてからこのオブジェクトに加えた変更を取り除く。 現在のところ、これは単にオブジェクトからカラム値を破棄するだけだ。

If you're using autoupdate this method will throw an exception.



        my $changed = $obj->is_changed;
        my @changed_keys = $obj->is_changed;

Indicates if the given $obj has changes since the last update. Returns a list of keys which have changed. (If autoupdate is on, this method will return an empty list, unless called inside a before_update or after_set_$column trigger)

指定した$objが最後の更新から変更されたかどうかを示す。変更された キーのリストを返す(autoupdateがonの場合、before_updateか after_set_$column内で呼ばれない限り、このメソッドは空リストを返す)。


        $id = $obj->id;

Returns a unique identifier for this object. It's the equivalent of $obj->get($self->columns('Primary')); A warning will be generated if this method is used on a table with a multi-column primary key.

このオブジェクトの一意な識別子を返す。obj->get($self->columns('Primary')); に等しい。複数の主キーカラムを持つテーブルでこのメソッドを使うと、 警告を発する。


On some occasions, such as when you're writing triggers or constraint routines, you'll want to manipulate data in a Class::DBI object without using the usual get() and set() accessors, which may themselves call triggers, fetch information from the database, and the like. Rather than intereacting directly with the hash that makes up a Class::DBI object (the exact implementation of which may change in a future release) you should use Class::DBI's low-level accessors. These appear 'private' to make you think carefully about using them - they should not be a common means of dealing with the object.

時には、例えばトリガや制約のためのルーチンを書いてる場合など、通常の get()やset()アクセサを使わないでClass::DBIオブジェクトのデータを操作 したいと思うだろう。これらのメソッドはそれ自身、トリガを呼び出したり、 データベースから情報を引き出したり、等々する。Class::DBIオブジェクトを 構成するハッシュ(今後のリリースで正確な実装は変更するかもしれない)と 直接やりとりをするよりも、Class::DBIの低レベルアクセサを使うべきである。 それらは'private'メソッドといえるので、使うときは慎重に ―― それらを オブジェクトを扱う一般的なやり方とすべきではない。

The object is modelled as a set of key-value pairs, where the keys are normalized column names (returned by find_column()), and the values are the data from the database row represented by the object. Access is via these functions:

オブジェクトはキー/値のペアとしてモデル化されている。ここでキーとは、 正規化されたカラム名(find_column()が返す値)のことであり、値とは そのオブジェクトによって表されるデータベース行のデータである。次の メソッドからアクセスする:

        @values = $object->_attrs(@cols);

Returns the values for one or more keys.


        $object->_attribute_store( { $col0 => $val0, $col1 => $val1 } );
        $object->_attribute_store($col0, $val0, $col1, $val1);

Stores values in the object. They key-value pairs may be passed in either as a simple list or as a hash reference. This only updates values in the object itself; changes will not be propagated to the database.

オブジェクトに値を格納する。キー/値のペアは単にリストとしてか、 あるいはハッシュリファレンスとして渡す。これはオブジェクト自身の 値を更新するだけである;値の変更はデータベースには反映されない。

        $object->_attribute_set( { $col0 => $val0, $col1 => $val1 } );
        $object->_attribute_set($col0, $val0, $col1, $val1);

Updates values in the object via _attribute_store(), but also logs the changes so that they are propagated to the database with the next update. (Unlike set(), however, _attribute_set() will not trigger an update if autoupdate is turned on.)

_attribute_store()を通じてオブジェクトの値を更新する。ただし、変更を 記録することで、次の更新時にデータベースに反映される(しかしset()とは 違って、autoupdateがオンでも_attribute_set()はupdateをトリガしない)。

        @values = $object->_attribute_delete(@cols);

Deletes values from the object, and returns the deleted values.


        $bool = $object->_attribute_exists($col);

Returns a true value if the object contains a value for the specified column, and a false value otherwise.

オブジェクトが指定したカラムの値を持っていれば真を返す。そうでなければ 偽を返す。

By default, Class::DBI uses simple hash references to store object data, but all access is via these routines, so if you want to implement a different data model, just override these functions.

デフォルトでClass::DBIはオブジェクトデータを格納するのに単純なハッシュ リファレンスを使っているとはいえ、全てのアクセスはこれらのルーチンを 通じてなされている。そのため、異なるデータモデルを実装しようと思ったら、 これらのメソッドをオーバーライドするだけでよい。


Class::DBI and its subclasses overload the perl builtin stringify and bool operators. This is a significant convenience.

Class::DBIとそのサブクラスは、perl組み込みの文字列演算子と ブール演算子をオーバーロードする。これは非常に便利だ。

The perl builtin bool operator is overloaded so that a Class::DBI object reference is true so long as all its key columns have defined values. (This means an object with an id() of zero is not considered false.)

組み込みのブール演算子がオーバーロードされる結果、Class::DBIオブジェクト リファレンスは、全カラムの値が定義されている限り真となる(つまり、id()が 0を返すオブジェクトでも偽とみなさないですむわけだ)。

When a Class::DBI object reference is used in a string context it will, by default, return the value of the primary key. (Composite primary key values will be separated by a slash).

Class::DBIオブジェクトリファレンスが文字列コンテキストで使われた場合、 デフォルトで主キーの値を返す(複合主キーの値はスラッシュで区切られる)。

You can also specify the column(s) to be used for stringification via the special 'Stringify' column group. So, for example, if you're using an auto-incremented primary key, you could use this to provide a more meaningful display string:

特別な'Stringify'カラムグループを通じて、カラムを文字列化するように 指定することもできる。だから例えば、あなたが自動インクリメントされる 主キーを使っているなら、この仕組みを使ってより意味のある文字列を表示 させることができる:

        Widget->columns(Stringify => qw/name/);

If you need to do anything more complex, you can provide an stringify_self() method which stringification will call:

もっと複雑なことがしたいなら、文字列化で呼び出されるstringify_self()メソッド を用意できる。

        sub stringify_self { 
                my $self = shift;
                return join ":", $self->id, $self->name;

This overloading behaviour can be useful for columns that have has_a() relationships. For example, consider a table that has price and currency fields:

このオーバーロードの振る舞いは、has_a()リレーションシップを持つカラムに 対して有用となろう。例えば、価格と通貨フィールドを持つテーブルを考えてみる:

        package Widget;
        use base 'My::Class::DBI';
        Widget->columns(All => qw/widgetid name price currency_code/);

        $obj = Widget->retrieve($id);
        print $obj->price . " " . $obj->currency_code;

The would print something like "42.07 USD". If the currency_code field is later changed to be a foreign key to a new currency table then $obj->currency_code will return an object reference instead of a plain string. Without overloading the stringify operator the example would now print something like "42.07 Widget=HASH(0x1275}" and the fix would be to change the code to add a call to id():

これは"42.07 USD"のように表示されるだろう。currency_codeフィールドが 後で変更されて、新しく通貨テーブルの外部キーとなった場合、 $obj->currency_codeは平素な文字列の代わりにオブジェクトリファレンスを 返す。文字列化演算子をオーバーロードできなければ、今やこの例は "42.07 Widget=HASH(0x1275}"などと表示されてしまう。そしてid()を 呼び出すようにコードを修正してやらなければならないだろう。

        print $obj->price . " " . $obj->currency_code->id;

However, with overloaded stringification, the original code continues to work as before, with no code changes needed.

しかし、文字列化のオーバーロードによって、元のコードは以前の ままに動作し、コードを変更する必要はなくなる。

This makes it much simpler and safer to add relationships to exisiting applications, or remove them later.

この機能を使うことで、既存のアプリケーションにリレーションシップを追加 したり、後でそれらを取り除いたりするのがより簡単に、より安全になる。


Databases are all about relationships. And thus Class::DBI provides a way for you to set up descriptions of your relationhips.

データベースといえばリレーションシップだ。それゆえClass::DBIは、 あなたがリレーションシップの記述を設定するための方法を提供する。

Currently we provide three such methods: 'has_a', 'has_many', and 'might_have'.

現在のところ、我々はそのような3つのメソッドを提供する:'has_a'、 'has_many'、そして'might_have'だ。


        Music::CD->has_a(artist => 'Music::Artist');
        print $cd->artist->name;

We generally use 'has_a' to supply lookup information for a foreign key, i.e. we declare that the value we have stored in the column is the primary key of another table. Thus, when we access the 'artist' method we don't just want that ID returned, but instead we inflate it to this other object.

我々は一般的に'has_a'を使って検索情報を外部キーに提供する。つまり、 カラム内に格納した値が、別のテーブルの主キーであると宣言している。 よって、'artist'メソッドにアクセスしたときにそのIDが返ってくるのを 望むのではなく、代わりにこの別のオブジェクトへインフレートする。

However, we can also use has_a to inflate the data value to any other object. A common usage would be to inflate a date field to a Time::Piece object:

しかしまた、has_aを使ってそのデータを任意の別のオブジェクトにインフレート することもできる。次の例はどちらもデータフィールドをTime::Piece オブジェクトにインフレートしている:

        Music::CD->has_a(reldate => 'Date::Simple');
        print $cd->reldate->format("%d %b, %Y");

        Music::CD->has_a(reldate => 'Time::Piece',
                inflate => sub { Time::Piece->strptime(shift, "%Y-%m-%d") },
                deflate => 'ymd',
        print $cd->reldate->strftime("%d %b, %Y");

If the foreign class is another Class::DBI representation we will call retrieve() on that class with our value. Any other object will be instantiated either by calling new($value) or using the given 'inflate' method. If the inflate method name is a subref, it will be executed, and will be passed the value and the Class::DBI object as arguments.

外部クラスが別のClass::DBIの代表であるなら、自クラスの持っている値を 使ってretrieve()を呼び出す。それ以外のオブジェクトの場合は、new($vlue)を 呼び出すか、あるいは'inflate'メソッドを使うことでインスタンス化される。 もしinflateメソッドの名前がコードリファレンスであるなら、それが実行され、 引数としてその値とClass::DBIオブジェクトが渡される。

When the object is being written to the database the object will be deflated either by calling the 'deflate' method (if given), or by attempting to stringify the object. If the deflate method is a subref, it will be passed the Class::DBI object as an argument.

そのオブジェクトがデータベースに書き込まれると、(指定しているなら) 'deflate'メソッドを呼び出すか、あるいはそのオブジェクトを文字列化しよう と試みることによって、オブジェクトはデフレートされる。deflateメソッドが コードリファレンスであるなら、 引数としてClass::DBIオブジェクトが 渡される。

*NOTE* You should not attempt to make your primary key column inflate using has_a() as bad things will happen. If you have two tables which share a primary key, consider using might_have() instead.

*注意* has_a()を使って主キーカラムをインフレートするべきではない。悪い ことが起きるだろう。主キーを共有する二つのテーブルがあるなら、代わりに might_have()の利用を検討すること。


        Class->has_many(method_to_create => "Foreign::Class");

        Music::CD->has_many(tracks => 'Music::Track');

        my @tracks = $cd->tracks;

        my $track6 = $cd->add_to_tracks({ 
                position => 6,
                title    => 'Tomorrow',

This method declares that another table is referencing us (i.e. storing our primary key in its table).

このメソッドは、別のテーブルが我々を参照している(つまり、そのテーブル内に 我々の主キーがある)と宣言する。

It creates a named accessor method in our class which returns a list of all the matching Foreign::Class objects.

メソッドは我々のクラスに名前付きアクセサを生成する。このアクセサは マッチするForeign::Classオブジェクトの全リストを返す。

In addition it creates another method which allows a new associated object to be constructed, taking care of the linking automatically. This method is the same as the accessor method with "add_to_" prepended.

加えて、もう一つメソッドを生成する。それは自動的にリンクを処理して 新しく関連付けられたオブジェクトを構築するメソッドだ。このメソッドは "add_to_"が前に付け加わったアクセサである。

The add_to_tracks example above is exactly equivalent to:


        my $track6 = Music::Track->create({
                cd       => $cd,
                position => 6,
                title    => 'Tomorrow',

When setting up the relationship we examine the foreign class's has_a() declarations to discover which of its columns reference our class. (Note that because this happens at compile time, if the foreign class is defined in the same file, the class with the has_a() must be defined earlier than the class with the has_many(). If the classes are in different files, Class::DBI should be able to do the right thing). If no such has_a() declarations can be found, or none link to us, we assume that it is linking to us via a column named after the moniker() of our class. If this is not true you can pass an additional third argument to the has_many() declaration stating which column of the foreign class references us.

リレーションシップを設定すると、我々のクラスは、その外部クラスのhas_a() 宣言を調べて、どのカラムが我々のクラスを参照しているかを発見する。 (注意して欲しいのだが、これはコンパイル時に起こるので、もし外部クラスが 同じファイル内で定義されているなら、has_a()を持っているそのクラスは has_many()を持っているクラスよりも先に宣言されなければならない。 違うファイルにクラスがあるならClass::DBIは正しくことにあたれるはずだ。) そのようなhas_a()宣言が見出されない場合、あるいは我々のクラスにリンクして いない場合、我々のクラスのmoniker()に基づいて名づけられたカラムを通じて リンクされていると仮定する。これが正しくないなら、has_many()宣言に 三番目の引数を加えることで、その外部クラスのどのカラムが我々を参照してるか 指定できる。


        Music::Artist->has_many(cds => 'Music::CD');
        my @cds = $artist->cds(year => 1980);

When calling the method created by has_many, you can also supply any additional key/value pairs for restricting the search. The above example will only return the CDs with a year of 1980.

has_manyによって生成されたメソッドを呼び出すときに、検索に制限を かけるためにキー/値のペアを追加で渡せる。上の例では1980年のCDだけが 返される。


        Music::CD->has_many(tracks => 'Music::Track', { order_by => 'playorder' });

Often you wish to order the values returned from has_many. This can be done by passing a hash ref containing a 'order_by' value of the column by which you want to order.

has_manyから返される値を整列させたいことはよくある。これは 'order_by'と並び替えたいカラム名のペアを含むハッシュリファレンスを渡す ことで可能だ。


        Music::CD->has_many(styles => [ 'Music::StyleRef' => 'style' ]);

Sometimes we don't want to return an instance of the Foreign::Class, but instead the result of calling a method on that object. We can do this by changing the Foreign::Class declaration to a listref of the Foreign::Class and the method to call on that class.

しばしばForeign::Classのインスタンスではなくて、代わりにその オブジェクトに対するメソッドを呼び出した結果が欲しいことがある。 これはForeign::Class宣言を、Foreign::Classとそのクラス上で呼ぶメソッドの リストリファレンスに変更することでできる。

The above is exactly equivalent to:


        Music::CD->has_many(_style_refs => 'Music::StyleRef');

        sub styles { 
                my $self = shift;
                return map $_->style, $self->_style_refs;

For an example of where this is useful see "MANY TO MANY RELATIONSHIPS" below.



        Music::CD->might_have(method_name => Class => (@fields_to_import));

        Music::CD->might_have(liner_notes => LinerNotes => qw/notes/);

        my $liner_notes_object = $cd->liner_notes;
        my $notes = $cd->notes; # equivalent to $cd->liner_notes->notes;

might_have() is similar to has_many() for relationships that can have at most one associated objects. For example, if you have a CD database to which you want to add liner notes information, you might not want to add a 'liner_notes' column to your main CD table even though there is no multiplicity of relationship involved (each CD has at most one 'liner notes' field). So, we create another table with the same primary key as this one, with which we can cross-reference.

最大でも一つの関連したオブジェクトを持ちうるリレーションシップという点で、 might_have()はhas_many()に似ている。例えばCDのデータベースがあり、 ライナーノーツ情報をそこに加えたいとする。しかし例え複数のリレーションシップ (CDは最大でも一つの'liner notes'フィールドを持つ)が関わっていないとしても、 あなたはメインとなるCDテーブルに'liner_notes'カラムを付け加えたくはない だろう。そこで、同じ主キーを持ったもう一つのテーブルをこのカラムとして作成し、 それを利用してクロスリファレンスできるようにする。

But you don't want to have to keep writing methods to turn the the 'list' of liner_notes objects you'd get back from has_many into the single object you'd need. So, might_have() does this work for you. It creates you an accessor to fetch the single object back if it exists, and it also allows you import any of its methods into your namespace. So, in the example above, the LinerNotes class can be mostly invisible - you can just call $cd->notes and it will call the notes method on the correct LinerNotes object transparently for you.

しかし、has_manyから取得したliner_notesオブジェクトの'リスト'を、あなたの 望む一オブジェクトに戻すためにメソッドを書きつづけるなどということは したくない。そう、might_have()はあなたのためにこの仕事をやってくれる。 このメソッドは、もし存在するなら一つのオブジェクトを取り出すアクセサを 生成する。これを使って任意のメソッドをあなたの名前空間にインポートする こともできる。そこで上の例の場合、LinerNotesクラスをほとんど不可視に できる――$cd->notesと呼び出すだけでいい。そうすればあなたにとって透過的な 正しいLinerNotesを扱うnotesメソッドが呼び出される。

Making sure you don't have namespace clashes is up to you, as is correctly creating the objects, but I may make these simpler in later versions. (Particularly if someone asks for them!)

正しくオブジェクトを生成するためにも、名前空間の衝突が起きないように あなた自身で確認すること。ただ、私は今後のバージョンでこれらをより 簡単にできるようにするかもしれない(特に、誰かが私にそれを求めるなら!)。


has_a(), might_have() and has_many() check that the relevant class has already been loaded. If it hasn't then they try to load the module of the same name using require. If the require fails because it can't find the module then it will assume it's not a simple require (i.e., Foreign::Class isn't in Foreign/ and that you will take care of it and ignore the warning. Any other error, such as a syntax error, triggers an exception.

has_a()、might_have()そしてhas_many()は、関連モジュールが既にロード されているかチェックする。もしされていなければ、rquireを使って同じ名前の モジュールをロードしようと試みる。モジュールを見つけられないでrequireが 失敗した場合、単純なrequireではだめで(要するにForeign::Classは Foreign/Class.pmにない)、あなたが何とかすると見なし、警告を無視する。 それ以外のエラー、例えば構文エラーなどは例外を引き起こす。

NOTE: The two classes in a relationship do not have to be in the same database, on the same machine, or even in the same type of database! It is quite acceptable for a table in a MySQL database to be connected to a different table in an Oracle database, and for cascading delete etc to work across these. This should assist greatly if you need to migrate a database gradually.

注意:リレーションシップ内の二つのクラスは、同じマシン上の同じ データベースに、あるいは同じタイプのデータベースにすら、ある必要はない! MySQLデータベースがOracleデータベースの違うテーブルに接続したり、これらの データベースを横断してカスケードデリートその他の操作が行なわれるのは、 全く問題ない。データベースを段階的に移植するつもりなら、このことが 大いに役立つはずだ。


Class::DBI does not currently support Many to Many relationships, per se. However, by combining the relationships that already exist it is possible to set these up.

Class::DBIは今のところ、それ自体では多対多リレーションシップをサポート していない。しかし、既存のリレーションシップを組み合わせることで 多対多リレーションシップをセットできる。

Consider the case of Films and Actors, with a linking Role table. First of all we'll set up our Role class:

役割(Role)テーブルを使って、映画(Film)と役者(Actor)の場合を想定する。 まず始めはRoleクラスを用意する:

        Role->columns(Primary => qw/film actor/);
        Role->has_a(film => 'Film');
        Role->has_a(actor => 'Actor');

We have a multi-column primary key, with each column pointing to another class.


Then, we need to set up our Film and Actor class to use this linking table:


        Film->columns(All => qw/id title rating/);
        Film->has_many(stars => [ Role => 'actor' ]);

        Actor->columns(All => qw/id name/);
        Actor->has_many(films => [ Role => 'film' ]);

In each case we use the 'mapping method' variation of has_many() to say that we don't want an instance of the Role class, but rather the result of calling a method on that instance. As we have set up those methods in Role to inflate to the actual Actor and Film objects, this gives us a cheap many-to-many relationship. In the case of Film, this is equivalent to the more long-winded:

それぞれのケースで、has_many()の”マッピングメソッド”を利用することで 我々はRoleクラスのインスタンスを欲しているのではなく、そのインスタンスの メソッドを呼び出した結果を欲していることを示している。Roleのメソッドを 実際のActorとFilmオブジェクトへインフレートするために設定したことで、 簡単な多対多リレーションシップが手に入る。Filmを例にすると、これはより 回りくどい以下のものと同じである:

        Film->has_many(roles => "Role");

        sub actors { 
                my $self = shift;
                return map $_->actor, $self->roles 

As this is almost exactly what is created internally, add_to_stars and add_to_films will generally do the right thing as they are actually doing the equivalent of add_to_roles:

これは内部で生成されたものとほぼ同じであり、add_to_starsとadd_to_films は、それらが実際にadd_to_rolesと同じことを行なうのと同様、正しく動作する:

        $film->add_to_actors({ actor => $actor });

Similarly a cascading delete will also do the right thing as it will only delete the relationship from the linking table.

同様にカスケードデリートも、リンクテーブルからリレーションシップを 削除するだけの場合と同様に、正しく動作する。

If the Role table were to contain extra information, such as the name of the character played, then you would usually need to skip these short-cuts and set up each of the relationships, and associated helper methods, manually.

仮にRoleテーブルがさらなる情報、例えば役柄名などを含んでいたならば、 通常はこのような近道は省いてリレーションシップを設定し、関連付けられた ヘルパーメソッドを手動で設定しなければならなかっただろう。



The relationships described above are implemented through Class::DBI::Relationship subclasses. These are then plugged into Class::DBI through an add_relationship_type() call:

上に挙げたリレーションシップは、Class::DBI::Relationshipの サブクラスを通じて実装されている。そしてadd_relationship_type()の 呼び出しによってClass::DBIに挿入される:

                has_a      => "Class::DBI::Relationship::HasA",
                has_many   => "Class::DBI::Relationship::HasMany",
                might_have => "Class::DBI::Relationship::MightHave",

If is thus possible to add new relationship types, or modify the behaviour of the existing types. See Class::DBI::Relationship for more information on what is required.

よって、新しいリレーションシップのタイプを追加したり、既存のタイプの 振る舞いを修正したりできる。何が必要かといった詳しい情報は Class::DBI::Relationshipを参照のこと。


There are several main approaches to setting up your own SQL queries:


For queries which could be used to create a list of matching objects you can create a constructor method associated with this SQL and let Class::DBI do the work for you, or just inline the entire query.

オブジェクトにマッチするリスト生成に用いられる問い合わせをするために、 SQLに関連するコンストラクタメソッドを生成し、Class::DBIを働かせられる。 あるいは完全なクエリーをインライン化できる。

For more complex queries you need to fall back on the underlying Ima::DBI query mechanism. (Caveat: since Ima::DBI uses sprintf-style interpolation, you need to be careful to double any "wildcard" % signs in your queries).

より複雑な問い合わせを利用するには、下支えしているIma::DBIの問い合わせ メカニズムを頼らなければならない。(警告:Ima::DBIはsprintfによる文字列の 挿入を行なうので、問い合わせ文中の”ワイルドカード”%記号を重複するのに 気をつけないといけない。)


        __PACKAGE__->add_constructor(method_name => 'SQL_where_clause');

The SQL can be of arbitrary complexity and will be turned into: SELECT (essential columns) FROM (table name) WHERE <your SQL>

このSQL文は好きなだけ複雑なものにでき、以下のように変換される: SELECT (実質カラム) FROM (テーブル名) WHERE <あなたのSQL>

This will then create a method of the name you specify, which returns a list of objects as with any built in query.

そしてあなたの指定した名前のメソッドが生成される。このメソッドは、 組み込まれた問い合わせを使ってオブジェクトリストを返す。

For example:


        Music::CD->add_constructor(new_music => 'year > 2000');
        my @recent = Music::CD->new_music;

You can also supply placeholders in your SQL, which must then be specified at query time:

また、SQL内にプレースホルダを入れられる。これは問い合わせ時に 指定されなければならない:

        Music::CD->add_constructor(new_music => 'year > ?');
        my @recent = Music::CD->new_music(2000);


On occasions where you want to execute arbitrary SQL, but don't want to go to the trouble of setting up a constructor method, you can inline the entire WHERE clause, and just get the objects back directly:

任意のSQLを実行はしたいが、コンストラクタメソッドの準備でゴタゴタに 巻き込まれたくないようなときは、完全なWHERE句を埋め込むやり方がある。 これで直接オブジェクトを取得できる:

        my @cds = Music::CD->retrieve_from_sql(qq{
                artist = 'Ozzy Osbourne' AND
                title like "%Crazy"      AND
                year <= 1986
                ORDER BY year
                LIMIT 2,3

Ima::DBI queries

When you can't use 'add_constructor', e.g. when using aggregate functions, you can fall back on the fact that Class::DBI inherits from Ima::DBI and prefers to use its style of dealing with statements, via set_sql().

'add_constructor'が使えないとき、例えば集約関数を使う場合などは、 Class:DBIがIma::DBIを継承しており、set_sql()を通じてSQL文を扱うスタイル をとっている事実に頼ればよい。

The Class::DBI set_sql() method defaults to using prepare_cached() unless the $cache parameter is defined and false (see Ima::DBI docs for more information).

Class::DBIのset_sql()メソッドは、$cacheパラメータが定義されていて、 かつ、偽でない限り、デフォルトでprepare_cached()を使う(詳細は Ima::DBIのドキュメントを参考に)。

To assist with writing SQL that is inheritable into subclasses, several additional substitutions are available here: __TABLE__, __ESSENTIAL__ and __IDENTIFIER__. These represent the table name associated with the class, its essential columns, and the primary key of the current object, in the case of an instance method on it.

サブクラスへ継承可能なSQLを書く手助けとして、いくつかの追加的な代替手段が 利用可能である:__TABLE__、__ESSENTIAL__そして__IDENTIFIER__。 これらはそれぞれ、クラスに関連付けられたテーブル名、実質カラム、 そしてインスタンスメソッドとして使った場合の現在のオブジェクトの 主キーを表している。

For example, the SQL for the internal 'update' method is implemented as:


        __PACKAGE__->set_sql('update', <<"");
                UPDATE __TABLE__
                SET    %s
                WHERE  __IDENTIFIER__

The 'longhand' version of the new_music constructor shown above would similarly be:


        Music::CD->set_sql(new_music => qq{
                SELECT __ESSENTIAL__
                  FROM __TABLE__
                 WHERE year > ?

We also extend the Ima::DBI set_sql() to create a helper shortcut method, named by prefixing the name of your SQL fragment with search_. Thus, the above call to set_sql() will automatically set up the method Music::CD->search_new_music(), which will execute this search and return the relevant objects or Iterator. (If you have placeholders in your query, you must pass the relevant arguments when calling your search method.)

また、Ima::DBIのset_sql()を拡張して、ヘルパーメソッドを生成している。 このメソッドはあなたのSQL断片の前にsearch_をつけた名前である。よって、 上の例にあるset_sql()の呼び出しは、自動的にMusic::CD->search_new_music() メソッドを用意する。これは検索を実行し、関連するオブジェクトや イテレータを返す。(問い合わせの中にプレースホルダがある場合、 検索メソッドを呼ぶ際に関連する引数を渡さなければならない)

This does the equivalent of:


        sub search_new_music {
                my ($class, @args) = @_;
                my $sth = $class->sql_new_music;
                return $class->sth_to_objects($sth);

The $sth which we use to return the objects here is a normal DBI-style statement handle, so if your results can't even be turned into objects easily, you can still call $sth->fetchrow_array etc and return whatever data you choose.

オブジェクトを返すためにここで我々が使っている$sthは、通常のDBI型 ステートメントハンドルである。そのため、あなたが得た結果が簡単には オブジェクトにならない場合でも、$sth->fetchrow_arrayその他を 呼び出して、あなたが選んだデータなら何でも返すことができる。

Of course, any query can be added via set_sql, including joins. So, to add a query that returns the 10 Artists with the most CDs, you could write (with MySQL):

もちろん、set_sqlを通じて、どんな問い合わせも付け加えられる。joinを含めて。 そのため、最も多くのCDを出している10人のアーティストを返す問い合わせを加える には、このように書く(MySQLを使用):

        Music::Artist->set_sql(most_cds => qq{
                SELECT, COUNT( AS cds
                  FROM artist, cd
                 WHERE = cd.artist
                 GROUP BY
                 ORDER BY cds DESC
                 LIMIT 10

        my @artists = Music::Artist->search_most_cds();

If you also need to access the 'cds' value returned from this query, the best approach is to declare 'cds' to be a TEMP column. (See "Non-Persistent Fields" below).

この問い合わせから返された'cds'の値にもアクセスする必要があるなら、 最もよいアプローチは'cds'をTEMPカラムとして宣言することだ(下の "非永続フィールド"を参照)。


        my @music = Music::CD->search_where(
                artist => [ 'Ozzy', 'Kelly' ],
                status => { '!=', 'outdated' },

The Class::DBI::AbstractSearch module, available from CPAN, is a plugin for Class::DBI that allows you to write arbitrarily complex searches using perl data structures, rather than SQL.

CPANから取得可能なClass::DBI::AbstractSearchモジュールは、 Class::DBIのプラグインであり、SQLではなくperlのデータ構造を 使って、任意の複雑な検索を書くことができる。


Selects which only return a single value can take advantage of Ima::DBI's $sth->select_val() call, coupled with Class::DBI's sql_single SQL.

一つの値だけを返すSELECTは、Class::DBIのsql_singleに与えるSQLと対となって Ima::DBIの$sth->select_val()を利用できる。


Selects which only return a single value can take advantage of Ima::DBI's $sth->select_val() call. For example,

一つの値だけを返すSELECTは、Ima::DBIの$sth->select_val()呼び出しを 利用できる。例えば、

        __PACKAGE__->set_sql(count_all => "SELECT COUNT(*) FROM __TABLE__");
        # .. then ..
        my $count = $class->sql_count_all->select_val;


Internally we define a very simple SQL fragment: "SELECT %s FROM __TABLE__". Using this we implement the above Class->count_all(), as

内部で非常に単純なSQL小片を定義している:"SELECT %s FROM __TABLE__"。 これを使って上記のClass->count_all()を次のように実装する。


This interpolates the COUNT(*) into the %s of the SQL, and then executes the query, returning a single value.

これはCOUNT(*)をSQL文の%sに挿入する。そしてその問い合わせを実行し、 一つの値を返す。

Any SQL set up via set_sql() can of course be supplied here, and select_val can take arguments for any placeholders there.

もちろんset_sql()を通じてなされたどんなSQLでもここに与えられるし、 select_valはプレースホルダのための引数をとれる。

Internally we define several helper methods using this approach:


- count_all
- maximum_value_of($column)
- minimum_value_of($column)


In the tradition of Perl, Class::DBI is lazy about how it loads your objects. Often, you find yourself using only a small number of the available columns and it would be a waste of memory to load all of them just to get at two, especially if you're dealing with large numbers of objects simultaneously.

Perlの伝統により、Class::DBIはあなたのオブジェクトをどのようにロードするか に関しては怠惰である。小数のカラムだけを利用するのに、メモリを浪費して全部の オブジェクトをロードしたあげく、ただ二つを取得するなどということがしばしば あるだろう。とくに、非常にたくさんのオブジェクトを同時に扱うような場合は そうだ。

You should therefore group together your columns by typical usage, as fetching one value from a group can also pre-fetch all the others in that group for you, for more efficient access.

それゆえ、カラムをグループとしてまとめるべきである。典型例として、 グループから一つの値を取り出すのに、グループ内の他の全ての値も予め 取り出しておくことができ、より効率の良いアクセスを望める。

So for example, if we usually fetch the artist and title, but don't use the 'year' so much, then we could say the following:

そこで例えば、artistとtitleはいつも取り出すけれども、'year'はそれほど 使わない場合、以下のようにすればよい:

        Music::CD->columns(Primary   => qw/cdid/);
        Music::CD->columns(Essential => qw/artist title/);
        Music::CD->columns(Others    => qw/year runlength/);

Now when you fetch back a CD it will come pre-loaded with the 'cdid', 'artist' and 'title' fields. Fetching the 'year' will mean another visit to the database, but will bring back the 'runlength' whilst it's there.

これでCDから取り出すときは、'cdid'、'artist'そして'title'フィールドが予め ロードされる。'year'を取り出すのはデータベースに対する別口の問い合わせを 意味するが、このときには'runlength'も返ってくる。

This can potentially increase performance.


If you don't like this behavior, then just add all your non-primary key columns to the one group, and Class::DBI will load everything at once.

この振る舞いを望まないときは、非主キーカラムを全て一つのグループに 加えるだけでよい。そうすればClass::DBIは一度に全てをロードする。


        my @all_columns  = $class->columns;
        my @columns      = $class->columns($group);

        my @primary      = $class->primary_columns;
        my $primary      = $class->primary_column;
        my @essential    = $class->_essential;

There are four 'reserved' groups: 'All', 'Essential', 'Primary' and 'TEMP'.

'予約された'4つのグループ:'All'、'Essential'、'Primary'そして 'TEMP'。

'All' are all columns used by the class. If not set it will be created from all the other groups.

'All'はクラスが使う全カラムである。これを設定しないと、他の全 グループから生成される。

'Primary' is the primary key columns for this class. It must be set before objects can be used.

'Primary'はこのクラスの主キーカラムである。オブジェクトが利用可能に なる前に設定されなければならない

If 'All' is given but not 'Primary' it will assume the first column in 'All' is the primary key.

'All'が指定されているが'Primary'が指定されていない場合、'ALL'の最初の カラムが主キーであると仮定される。

'Essential' are the minimal set of columns needed to load and use the object. Only the columns in this group will be loaded when an object is retrieve()'d. It is typically used to save memory on a class that has a lot of columns but where we mostly only use a few of them. It will automatically be set to 'All' if you don't set it yourself. The 'Primary' column is always part of your 'Essential' group and Class::DBI will put it there if you don't.

'Essential'は、オブジェクトをロードし利用するのに必要な最小限の カラムセットである。オブジェクトがretrieve()されるとき、このグループ内の カラムだけがロードされる。たくさんのカラムを持つが、そのうちのほんの少し だけを使うようなクラスでメモリを節約するというのが典型的な使い方だ。 このグループを指定しない場合、自動的に'All'の内容がセットされる。 'Primary'カラムは常に'Essential'グループの一部であり、あなたがセット しない場合、Class::DBIがそれを行なう。

[訳者補注:0.92のChangesにおいて The Essential column group now defaults to Primary rather than All. とあり、実際にはAllが設定されるのではなく、Primaryが設定されるだけ です。要注意!!]

For simplicity we provide primary_columns(), primary_column(), and _essential() methods which return these. The primary_column() method should only be used for tables that have a single primary key column.

簡略のため、これらの設定を返すprimary_columns()、primary_column()、 そして_essential()メソッドを用意している。primary_column()は、単一の 主キーカラムを持つテーブルに対してのみ使うべきである。


        Music::CD->columns(TEMP => qw/nonpersistent/);

If you wish to have fields that act like columns in every other way, but that don't actually exist in the database (and thus will not persist), you can declare them as part of a column group of 'TEMP'.

いつでもカラムのように振舞うが、実際にはデータベース上に存在しない (それゆえ永続しない)フィールドが欲しいなら、'TEMP'というカラムグループ の一部として宣言することができる。



The columns of a class are stored as Class::DBI::Column objects. This method will return you the object for the given column, if it exists. This is most useful either in a boolean context to discover if the column exists, or to 'normalize' a user-entered column name to an actual Column.

クラスのカラムは、Class::DBI::Columnオブジェクトとして保持されている。 このメソッドは、もし存在しているなら指定したカラムのオブジェクトを返す。 これは、そのカラムが存在しているかを調べるブールコンテキストか、あるいは ユーザーが入力したカラム名を実際のColumnへと'正規化'する場合のどちらかで 非常に役に立つ。

The interface of the Column object itself is still under development, so you shouldn't really rely on anything internal to it.

Columnオブジェクトのインターフェース自体はまだ開発途中である。 そのため、実際にはこのインターフェースに内部的に依存するべきではない。


Class::DBI suffers from the usual problems when dealing with transactions. In particular, you should be very wary when committing your changes that you may actually be in a wider scope than expected and that your caller may not be expecting you to commit.

Class::DBIはトランザクションを扱うときに生じる、よくある問題に苦しむ。 殊に、予想以上に広範囲のスコープにおいてあなたがなした変更をコミット する場合には、また、あなたがコミットすることを呼び出し側が予想して いない場合には細心の注意を払う必要がある。

However, as long as you are aware of this, and try to keep the scope of your transactions small, ideally always within the scope of a single method, you should be able to work with transactions with few problems.

しかしこのことに気づいている限り、また、トランザクションのスコープを 小さなものに、理念上は常に一つのメソッドのスコープ内に、維持しようと する限り、ほとんど問題なくトランザクションを使った仕事ができるはずだ。

dbi_commit / dbi_rollback


We provide these thin aliases through to the DBI's commit() and rollback() commands to commit or rollback all changes to this object.

DBIのcommit()とrollback()コマンドへの貧弱なエイリアスを提供している。 これらは、このオブジェクトへの全変更をcommitあるいはrollbackするためにある。


A nice idiom for turning on a transaction locally (with AutoCommit turned on globally) (courtesy of Dominic Mitchell) is:

トランザクションを局所化(グローバルにAutoCommitを有効にしていて)する うまい慣用句(Dominic Mitchellに感謝)は:

        sub do_transaction {
                my $class = shift;
                my ( $code ) = @_;
                # このスコープに対してAutoCommitを無効にする。
                # ローカルなAutoCommitがスコープを外れるとき、
                # すなわち、このブロックを抜けると自動的にcommitされる。
                local $class->db_Main->{ AutoCommit };

                # トランザクション内で必要となるコードを実行。
                eval { $code->() };
                if ( $@ ) {
                        my $commit_error = $@;
                        eval { $class->dbi_rollback }; # これもdieするかもしれない!
                        die $commit_error;

        And then you just call:


        Music::DBI->do_transaction( sub {
                my $artist = Music::Artist->create({ name => 'Pink Floyd' });
                my $cd = $artist->add_to_cds({ 
                        title => 'Dark Side Of The Moon', 
                        year => 1974,

Now either both will get added, or the entire transaction will be rolled back.

これで両方が付け加えられるか、さもなければトランザクションは完全に ロールバックする。


Class::DBI supports uniqueness of objects in memory. In a given perl interpreter there will only be one instance of any given object at one time. Many variables may reference that object, but there can be only one.

Class::DBIはメモリ内にあるオブジェクトの一意性をサポートしている。 あるPerlインタプリタにおいて、オブジェクトのインスタンスは同時に 一つだけ存在する。多くの変数がそのオブジェクトを参照するかも しれないが、しかしそのオブジェクトはただ一つのものとして存在できる。

Here's an example to illustrate:


        my $artist1 = Music::Artist->create({ artistid => 7, name => 'Polysics' });
        my $artist2 = Music::Artist->retrieve(7);
        my $artist3 = Music::Artist->search( name => 'Polysics' )->first;

Now $artist1, $artist2, and $artist3 all point to the same object. If you update a property on one of them, all of them will reflect the update.

$artist1、$artist2、そして$artist3は全て同じオブジェクトを指している。 この中の一つを更新しても、それら全てに更新が反映される。

This is implemented using a simple object lookup index for all live objects in memory. It is not a traditional cache - when your objects go out of scope, they will be destroyed normally, and a future retrieve will instantiate an entirely new object.

これはメモリ内で生きている全オブジェクトに対する単純な参照インデックスを 使って実装している。伝統的なキャッシュではない――オブジェクトが スコープを抜けると普通にそれらは破壊され、後で取り出すときは完全に新しい オブジェクトとしてインスタンス化する。

The ability to perform this magic for you replies on your perl having access to the Scalar::Util::weaken function. Although this is part of the core perl distribution, some vendors do not compile support for it. To find out if your perl has support for it, you can run this on the command line:

この魔法を実行できるかどうかは、あなたが使っているperlが Scalar::Util::weaken関数にアクセスできるかどうかによる。これはコアPerl ディストリビューションの一部であるにも関わらず、ベンダによってはサポート するようにコンパイルしていない。あなたのperlがサポートしているか 調べるには、コマンドラインで次のように実行する:

        perl -e 'use Scalar::Util qw(weaken)'

If you get an error message about weak references not being implemented, Class::DBI will not maintain this lookup index, but give you a separate instances for each retrieve.

弱いリファレンスは実装されていないというエラーメッセージが出た場合、 Class::DBIはこの参照インデックスを維持しないだろうが、取り出しの度に 別々のインスタンスをよこすだろう。

A few new tools are offered for adjusting the behavior of the object index. These are still somewhat experimental and may change in a future release.

オブジェクトインデックスの振る舞いを調整するために、わずかだが新しい ツールが提供されている。これらはまだ幾分実験的であり、将来のリリース では変更するかもしれない。



This is an object method for removing a single object from the live objects index. You can use this if you want to have multiple distinct copies of the same object in memory.

オブジェクトインデックスから一つのオブジェクトを取り除くための オブジェクトメソッド。メモリ内で同じオブジェクトの別々のコピーを 複数持とうとするならこれが使える。



You can call this method on any class or instance of Class::DBI, but the effect is universal: it removes all objects from the index.

Class::DBIのどんなクラスないしはインスタンスからこのメソッドを呼び出せる。 しかしその効果は全般に及ぶ:インデックスから全てのオブジェクトを取り除く。



Weak references are not removed from the index when an object goes out of scope. This means that over time the index will grow in memory. This is really only an issue for long-running environments like mod_perl, but every so often we go through and clean out dead references to prevent it. By default, this happens evey 1000 object loads, but you can change that default for your class by calling the purge_object_index_every method with a number.

オブジェクトがスコープを抜けても、弱いリファレンスは取り除かれない。 これは時間が経つにつれてメモリ内のインデックスが増大することを意味する。 実際にはmod_perlのような長期実行環境においてのみ問題になるのだが、 この肥大化に直面するたびに死んだリファレンスを一掃することで、それを 防ぐようになっている。この掃除はデフォルトで1000オブジェクトがロード されるごとに発生する。しかし数値と一緒にpurge_object_index_everyを 呼び出せば、あなたのクラスのデフォルト値を変更できる。

Eventually this may handled in the DESTROY method instead.


As a final note, keep in mind that you can still have multiple distinct copies of an object in memory if you have multiple perl interpreters running. CGI, mod_perl, and many other common usage situations run multiple interpreters, meaning that each one of them may have an instance of an object representing the same data. However, this is no worse than it was before, and is entirely normal for database applications in multi-process environments.

最後の注意として、複数のPerlインタプリタを実行しているなら、依然として メモリ内にオブジェクトの別々のコピーを複数持てることを忘れないで欲しい。 CGI、mod_perl、そしてそれ以外の多くの一般的な利用状況で複数の インタプリタが走っている。これはそれらの一つひとつが同じデータを表す オブジェクトの実体を持っているかもしれない。だが、これは以前よりも 悪くは無いし、マルチプロセス環境のデータベースアプリケーションにとっては 至極当然のことなのだ。


The preferred method of interacting with Class::DBI is for you to write a subclass for your database connection, with each table-class inheriting in turn from it.

Class::DBIと相互作用する好ましいメソッドを使えば、データベース接続のための サブクラスを書ける。各テーブルクラスはそこから順番に継承する。

As well as encapsulating the connection information in one place, this also allows you to override default behaviour or add additional functionality across all of your classes.

一つの場所に接続情報をカプセル化するのと同様、これを使うことにより、 あなたのクラス全てを横断してデフォルトの振る舞いをオーバーライドしたり、 機能を追加したりできる。

As the innards of Class::DBI are still in flux, you must exercise extreme caution in overriding private methods of Class::DBI (those starting with an underscore), unless they are explicitly mentioned in this documentation as being safe to override. If you find yourself needing to do this, then I would suggest that you ask on the mailing list about it, and we'll see if we can either come up with a better approach, or provide a new means to do whatever you need to do.

Class::DBIの内部構造はまだ流動的なので、Class::DBIのプライベートメソッド (アンダーバーで始まるメソッド)をオーバーライドする際は、極度の注意を 払わなければならない。このドキュメント内でオーバーライドしても安全であると 明示的に言及されていない限りは。もしオーバーライドの必要を感じたなら、 それに関してメーリングリストで尋ねて欲しい。よりよいアプローチを提案 できるのか、あるいは新しい手段を提供できるのかを我々は検討するだろう。




Altering your primary key column currently causes Bad Things to happen. I should really protect against this.

現状において、主キーカラムの変更は悪いことをもたらす。 私はそれを何とかしようと思う。


Theoretically Class::DBI should work with almost any standard RDBMS. Of course, in the real world, we know that that's not true. We know that it works with MySQL, PostgrSQL, Oracle and SQLite, each of which have their own additional subclass on CPAN that you should explore if you're using them.

理論的には、Class::DBIはほとんどの標準的なRDBMで動作するはずだ。 もちろん、現実にはそれが正しくないことを我々は知っている。 MySQL、PostgreSQL、OracleそしてSQLiteで動作することは知られており、 それぞれCPANに付加的なサブクラスが存在する。

        L<Class::DBI::mysql>, L<Class::DBI::Pg>, L<Class::DBI::Oracle>,

For the most part it's been reported to work with Sybase, although there are some issues with multi-case column/table names. Beyond that lies The Great Unknown(tm). If you have access to other databases, please give this a test run, and let me know the results.

大部分について、Sybaseで動作するというレポートを受けている。ただし マルチケースのカラム・テーブル名でいくつかの問題があるのだが。それ以上 のことについては"The Great Unknown(tm)"だ。もしあなたが他のデータベースに アクセスするのなら、このモジュールをテスト実行して頂きたい。そして 私に結果を知らせて欲しい。

This is known not to work with DBD::RAM. As a minimum it requires a database that supports table aliasing, and a DBI driver that supports placeholders.

このモジュールはDBD::RAMでは動作しないことが知られている。最低限、 テーブルエイリアスをサポートしているデータベースと、プレースホルダを サポートしているDBIドライバが必要である。


Tony Bowden <>


Michael G Schwern <>


Tim Bunce, Tatsuhiko Miyagawa, Perrin Hawkins, Alexander Karelas, Barry Hoggard, Bart Lateur, Boris Mouzykantskii, Brad Bowman, Brian Parker, Casey West, Charles Bailey, Christopher L. Everett Damian Conway, Dan Thill, Dave Cash, David Jack Olrik, Dominic Mitchell, Drew Taylor, Drew Wilson, Jay Strauss, Jesse Sheidlower, Jonathan Swartz, Marty Pauley, Michael Styer, Mike Lambert, Paul Makepeace, Phil Crow, Richard Piacentini, Simon Cozens, Simon Wilcox, Thomas Klausner, Tom Renfro, Uri Gutman, William McKee, the Class::DBI mailing list, the POOP group, and all the others who've helped, but that I've forgetten to mention.


Support for Class::DBI is via the mailing list. The list is used for general queries on the use of Class::DBI, bug reports, patches, and suggestions for improvements or new features.

Class::DBIのサポートはメーリングリストを通じてなされる。 そこではClass::DBIの利用についての一般的な問い合わせ、バグレポート、 そして新しい機能の改良の提案がされている。

To join the list visit

You can also report bugs through the CPAN RT interface, but I'll proabably also forward those to the mailing list for discussion (and often bounce mailing list bug reports to the RT interface so I don't forget about them!)

CPAN RTを使ってバグを報告することもできる。だが私はたぶんそれらを 議論のためにメーリングリストに送るだろう(そしてときにはメーリング リストでのバグレポートをRTに投げるので、それらを忘れることはない!)。

When submitting patches I quite like the 'diff -Bub' format. Bug fixes also get applied much quicker if you supply a failing test case (even in preference to a fix!)

パッチを送るなら私は'diff -Bub'形式を好む。あなたが失敗した テストケースを送ってくれると、バグフィクスはもっと迅速に適用される だろう(どれをフィックスするかの好みはあるとしても!)。

The interface to Class::DBI is fairly stable, but there are still occasions when we need to break backwards compatability. Such issues will be raised on the list before release, so if you use Class::DBI in a production environment, it's probably a good idea to keep a watch on the list (and definitely on the CHANGES file of a new release).

Class::DBIのインターフェースはうまく安定している。しかしまだ後方互換を 壊さなければならないときもある。そのような案件についてはリリース前に メーリングリストで提起するので、もしプロダクション環境でClass::DBIを 使う場合は、メーリングリストを(そして明らかに新バージョンのCHANGESを) ウォッチし続けたほうがたぶん良いだろう。


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


There is a Class::DBI wiki at:

Amongst other things it provides the beginnings of a Cookbook of typical tricks and tips. Please contribute!

その他の中で、初心者向けのコツや技のクックブックを提供している。 貢献されたし!

There are lots of 3rd party subclasses and plugins available. For a full list see:

大量のサードパーティのサブクラスとプラグインが利用可能だ。 完全なリストは:

An article on Class::DBI was published on a while ago. It's slightly out of date already, but it's a good introduction:

少し前にClass::DBIの記事がPerl.comに載った。もういささか古くはなって いるが、優れたイントロダクションだ: provides a document comparing a variety of different approaches to database persistence, such as Class::DBI, Alazabo, Tangram, SPOPS etc. はデータベースの永続に対する様々な 異なるアプローチ、Class::DBI、Alazabo、Tangram、SPOPS等々 の比較をしたドキュメントを提供している。

Class::DBI is built on top of Ima::DBI, Class::Accessor and Class::Data::Inheritable.

Class::DBIは、Ima::DBIClass::Accessorそして Class::Data::Inheritableの上に構築されている。