名前¶

DBIx::Class::Manual::Intro - DBIx::Class イントロダクション

イントロダクション¶

で、SQLにうんざりしてません？データベース用に自然なPerlのインターフェースが欲しくない？ もしくは、しばらくClass::DBIで、それをしていたけど、もっと良いやりかたがあると思わなかった？ 良いところに来ましたね。

THE DBIx::Class WAY¶

ここにはDBIx::Classに慣れる助けになる、いくつかのTipsがあります。

テーブルはResult Class になる¶

DBIx::Class は、対象となるテーブルの構造がどんなものなのかを知っている必要があります。 そのために、Result Classを定義します。Result Class はDBIx::Class::ResultSource を 経由することで定義されます。それぞれのResult Class に一つのテーブルがあり、そのカラムを 定義します。一緒に他のテーブルとのすべてのリレーションを定義します。 (そして、ああ、それ以上に、)理解しなればいけない、重要なことは:

  A Result class == Table

(ほとんど常に、ですが、この単純化に我慢してください)

ResultSetについての全て¶

ResultSources を定義したら、今度はそれらの定義を、 手軽な perl オブジェクトに必要なクエリを変換するために、実際に使いたいと思います!

"alubum" テーブルのResultSource を定義します。テーブルには３つのカラムがあります: "albumid", "artist", "title" です。 このテーブルにクエリを投げたいなら、 ResultSource からDBIx::Class::ResultSetを作ります。例えば、結果は:

  SELECT albumid, artist, title FROM album;

album テーブル から ResultSet オブジェクトを作るために、テーブルのResultSource から引いてきます。おそらく"search" メソッドを使います。

DBIx::Class は単純なResultSet を作るだけには留まりません。 -- もし次のようなものが 欲しいなら:

  SELECT title FROM album GROUP BY title;

簡単にできます。

理解すべき重要なことは

  Any time you would reach for a SQL query in DBI, you are
  creating a DBIx::Class::ResultSet.

   DBIでSQLクエリを取ろうとするときはいつでも、
   DBIx::Class::ResultSetを作っています。

Search は "prepare"のようなもの¶

DBIx::Classがデータベースから絶対に情報を取得しなければならない時まで、 DBIx::Classは待つ傾向があります。ResultSetを返しても、クエリはデータに アクセスするメソッド("next"や"first"のような)を使うまで実行されません。

わかっておくべき重要なことは:

  Setting up a ResultSet does not execute the query; retrieving
  the data does.

  ResultSetのセットアップはクエリを実行しません; データの取得によって
  クエリが実行されます。

Search results are returned as Rows¶

データベースからの検索の行は、bless されてDBIx::Class::Rowオブジェクトになります。

DBIx::Classのセットアップ¶

Let's look at how you can set and use your first native DBIx::Class tree.

まず最初にネイティブのDBIx::Classツリーをどのようにセットし、使うのかを見ましょう。

最初に、自分でクラスをセットアップする方法を見ますが、クラスを自動で見付けたい場合は、 その次のセクションまでスキップしてください、その次のセクションでは、DBIx::Class::Schema::Loader を使った方法を説明します。

手でセットアップする¶

まず、基本のスキーマクラスを作るべきです。DBIx::Class::Schemaから継承します:

  package My::Schema;
  use base qw/DBIx::Class::Schema/;

このクラスには、result_source ("table", "model") クラス(後で定義します)をロードします。 load_namespaces() メソッドを使います:

  # load My::Schema::Result::* and their resultset classes
  __PACKAGE__->load_namespaces();

デフォルトでは、My::Schema::Result:: 名前空間に全てのResult(Row)クラス 、My::Schema::ResultSet:: 名前空間のすべての結果セットクラスがロードされます。 (if missing, the resultsets are defaulted to be DBIx::Class::ResultSet objects). You can change the result and resultset namespaces by using options to the "load_namespaces" in DBIx::Class::Schema call.

Row クラスのためにload_classesを呼ぶことと、 それらのクラスで全ての必要な結果セットクラスを定義することで、 手で同じことができます。

次に、上で指定した、ロードしたいクラスをそれぞれ作ります:

  package My::Schema::Result::Album;
  use base qw/DBIx::Class::Core/;

それぞれのクラスに必要な追加のコンポーネントを load_components() メソッドでロードします。 必要ならコンポーネントの設定を与えます。例えば、自動的な行の並びかえなら:

  __PACKAGE__->load_components(qw/ Ordered /);
  __PACKAGE__->position_column('rank');

並びかえは、他のものが指示されなければ、'position' と呼ばれるフィールドを参照します。 ここでは、'rank' という名前のフィールドを並びかえに定義しています。 (注意: 並びかえされたコンポーネントを使っているのに、position カラムを定義していないか、 'position' フィールドが列になければ、挿入エラーが起きるでしょう。)

クラスにテーブルをセットします:

  __PACKAGE__->table('album');

クラスにカラムを追加します:

  __PACKAGE__->add_columns(qw/ albumid artist title rank /);

それぞれのカラムは、それ自身のアクセサや、あったほうが便利な、data_type や他の情報も add_columnsに次のようなハッシュを渡します:

  __PACKAGE__->add_columns(albumid =>
                            { accessor  => 'album',
                              data_type => 'integer',
                              size      => 16,
                              is_nullable => 0,
                              is_auto_increment => 1,
                              default_value => '',
                            },
                          artist =>
                            { data_type => 'integer',
                              size      => 16,
                              is_nullable => 0,
                              is_auto_increment => 0,
                              default_value => '',
                            },
                          title  =>
                            { data_type => 'varchar',
                              size      => 256,
                              is_nullable => 0,
                              is_auto_increment => 0,
                              default_value => '',
                            },
                          rank =>
                            { data_type => 'integer',
                              size      => 16,
                              is_nullable => 0,
                              is_auto_increment => 0,
                              default_value => '',
                            }
                         );

このデータのほとんどは、まだ、DBIx::Classで直接に使われません。ですが、 DBIx::Class::WebFormのような、関連する様々なモジュールがそれを使います。 また、他のやりかたの代わりに、スキーマからデータベースを作ることもできます。 詳しくはSQL::Translatorを見てください:

可能なカラムの属性の詳細については、 DBIx::Class::ResultSourceを見てください。

アクセサはそれぞれのカラム用に、自動的に作られます。 My::Schema::Result::Albumは、albumid() (または、アクセサを使ったら、album())、artist()、title() のメソッドが使えます。

クラスにプライマリキーを定義するなら:

  __PACKAGE__->set_primary_key('albumid');

複数カラムのプライマリキーがあるなら、代わりに、リストを渡してください:

  __PACKAGE__->set_primary_key( qw/ albumid artistid / );

belongs_toを使って、他のテーブルのIDを含むカラムを説明することで、 クラスがのリレーションシップを定義することが出来ます。 また、has_manyで、 カラムの1つに、このテーブルの外部キーを含むオブジェクトを取得する 定義済みのアクセサを作れます。

  # in My::Schema::Result::Artist
  __PACKAGE__->has_many('albums', 'My::Schema::Result::Album', 'artist');

様々なタイプの可能なリレーションシップについてと、自分自身のリレーションシップ を設計する方法についての詳しい情報は、DBIx::Class::Relationshipにあります。

DBIx::Class::Schema::Loaderを使う¶

これは外部のモジュールであり、DBIx::Classのディストリビューション一部ではありません。 データベース内の全てのテーブル用のクラスを自動的に作ります。

最も単純な方法はdbicdump スクリプトをDBIx::Class::Schema::Loader ディストリビューション から使うことです。例:

    $ dbicdump -o dump_directory=./lib MyApp::Schema dbi:mysql:mydb user pass

大文字、小文字混在のデータベースなら、preserve_caseオプションを使います:

    $ dbicdump -o dump_directory=./lib -o preserve_case=1 MyApp::Schema \
        dbi:mysql:mydb user pass

Catalystを使っているなら、Catalyst::Model::DBIC::Schemaにある、 ヘルパーを使えます。

    $ script/myapp_create.pl model MyDB DBIC::Schema MyDB::Schema \
        create=static moniker_map='{ foo => "FOO" }' dbi:SQLite:./myapp.db \
        on_connect_do='PRAGMA foreign_keys=ON' quote_char='"'

このヘルパーについてのより詳しい情報は、Catalyst::Helper::Model::DBIC::Schemaを 見てください。

DBIx::Class::Schema::Loaderと DBIx::Class::Schema::Loader::Base のドキュメントを見てください。たくさんの他のオプションに関する情報があります。

接続¶

スキーマに接続するためには、接続のための詳細情報か、データーベースハンドルを提供しなければいけません。

接続のための詳細情報で¶

引数は、"connect" in DBIと同じです:

  my $schema = My::Schema->connect('dbi:SQLite:/home/me/myapp/my.db');

必要に応じて、多くの違ったスキーマインスタンスを作ることが出来ます。 2つ目のデータベースがあり、アクセスしたいなら:

  my $other_schema = My::Schema->connect( $dsn, $user, $password, $attrs );

DBIx::Class::Schemaは接続をキャッシュしないことに注意してください。 複数のコネクションを使うなら、手でしなければなりません。

接続毎に、いくつかのsql文実行したいなら、connectの特別な5版目の引数に オプションとしてとして追加できます:

  my $another_schema = My::Schema->connect(
      $dsn,
      $user,
      $password,
      $attrs,
      { on_connect_do => \@on_connect_sql_statments }
  );

この特別なconnect-時の他のオプションについて詳しくは、 "connect_info" in DBIx::Class::Storage::DBIを見てください。

データベースハンドルで¶

与えられたコードリファレンスは一つの接続されたデータベースハンドルを返すことが期待されます。 (e.g. DBI $dbh)

  my $schema = My::Schema->connect (
    sub { Some::DBH::Factory->connect },
    \%extra_attrs,
  );

基本の使い方¶

基本のクラスを定義したら、手でも、 DBIx::Class::Schema::Loaderでも、 データベースへの連携を始められます。

$schemaオブジェクトでデータベースにアクセスするのに、 resultsetメソッドを呼び出すことで、それぞれのテーブルを表す、 "ResultSet" in DBIx::Class::Manual::Glossaryを取ります。

レコードを取るもっとも簡単な方法は、プライマリーキーで取る方法です:

  my $album = $schema->resultset('Album')->find(14);

WHERE節にalbumid=4で、SELECTが実行され、その列を表す My::Schema::Albumのインスタンスを返します。 その列があれば、カラムにアクセスでき、アップデートできます。

  $album->title('Physical Graffiti');
  my $title = $album->title; # $title holds 'Physical Graffiti'

お好みなら、set_columnとget_columnのアクセサを代わりに使えます:

  $album->set_column('title', 'Presence');
  $title = $album->get_column('title');

ちょうどClass::DBIと同じように、updateを呼んで、 変更をデータベースにコミットできます:

  $album->update;

必要なら、次のようにして、ローカルの変更を捨てることもできます:

  $album->discard_changes if $album->is_changed;

As you can see, is_changed allows you to check if there are local changes to your object.

御覧の通り、is_changedでオブジェクトにローカルの変更が加えられたか どうかをチェックできます。

列の追加及び削除¶

データベースに新しいレコードを作るためには、createメソッドを使います。 My::Schema::Result::Albumのインスタンスを返し、新しいレコードのデータにアクセスするのに 使えます:

  my $new_album = $schema->resultset('Album')->create({
    title  => 'Wish You Were Here',
    artist => 'Pink Floyd'
  });

さぁ、新しいレコードにデータを追加できます:

  $new_album->label('Capitol');
  $new_album->year('1975');
  $new_album->update;

同様に、次のようにして、データベースからそれを削除できます:

  $new_album->delete;

最初にレコードを取ってこずに削除することもできます。 ResultSetオブジェクトで直接にdeleteを呼びます。

  # Delete all of Falco's albums
  $schema->resultset('Album')->search({ artist => 'Falco' })->delete;

オブジェクトを探す¶

DBIx::Classは、データベースからデータを取得するのに、いくつかの 違った方法を提供しています。1つの例として:

  # Find all of Santana's albums
  my $rs = $schema->resultset('Album')->search({ artist => 'Santana' });

スカラコンテキストでは、searchは、DBIx::Class::ResultSetオブジェクト を返します。データベースから返された最初のアルバムを覗くのに使えます:

  my $album = $rs->first;
  print $album->title;

アルバムをループして、それぞれをアップデートできます:

  while (my $album = $rs->next) {
    print $album->artist . ' - ' . $album->title;
    $album->year(2001);
    $album->update;
  }

もしくは、一度に全てをアップデートできます:

  $rs->update({ year => 2001 });

リストコンテキストでは、searchメソッドはマッチした列全てを返します:

  # Fetch immediately all of Carlos Santana's albums
  my @albums = $schema->resultset('Album')->search(
    { artist => 'Carlos Santana' }
  );
  foreach my $album (@albums) {
    print $album->artist . ' - ' . $album->title;
  }

LIKE検索のための、手軽なショートカットもあります:

  # Find albums whose artist starts with 'Jimi'
  my $rs = $schema->resultset('Album')->search_like({ artist => 'Jimi%' });

もしくは、次のように、自分自身のWHERE節を渡せます:

  # Find Peter Frampton albums from the year 1986
  my $where = 'artist = ? AND year = ?';
  my @bind  = ( 'Peter Frampton', 1986 );
  my $rs    = $schema->resultset('Album')->search_literal( $where, @bind );

複雑なクエリを生成する好ましい方法は、SQL::Abstractの構造を searchに渡すことです:

  my $rs = $schema->resultset('Album')->search({
    artist  => { '!=', 'Janis Joplin' },
    year    => { '<' => 1980 },
    albumid => { '-in' => [ 1, 14, 15, 65, 43 ] }
  });

結果は、下記のWHERE節と同様です:

  WHERE artist != 'Janis Joplin'
    AND year < 1980
    AND albumid IN (1, 14, 15, 65, 43)

複雑なクエリの他の例はDBIx::Class::Manual::Cookbookにあります。

属性に他のハッシュを渡すことで、search を修正できます:

  my @albums = My::Schema->resultset('Album')->search(
    { artist => 'Bob Marley' },
    { rows => 2, order_by => 'year DESC' }
  );

@albumns には、最新のBob Marleyのアルバム2つがあります。

DBIx::Class::ResultSetで何が出来るかについてのより詳しい情報は、 "METHODS" in DBIx::Class::ResultSetを見てください。

For a complete overview of the available attributes, see "ATTRIBUTES" in DBIx::Class::ResultSet.

使える属性の完全な概観は、"ATTRIBUTES" in DBIx::Class::ResultSetを見てください

注意¶

プライマリーキーの意義と重要性¶

The concept of a primary key in DBIx::Class warrants special discussion. The formal definition (which somewhat resembles that of a classic RDBMS) is a unique constraint that is least likely to change after initial row creation. However this is where the similarity ends. Any time you call a CRUD operation on a row (e.g. delete, update, discard_changes, etc.) DBIx::Class will use the values of of the primary key columns to populate the WHERE clause necessary to accomplish the operation. This is why it is important to declare a primary key on all your result sources even if the underlying RDBMS does not have one. In a pinch one can always declare each row identifiable by all its columns:

 __PACKAGE__->set_primary_keys (__PACKAGE__->columns);

Note that DBIx::Class is smart enough to store a copy of the PK values before any row-object changes take place, so even if you change the values of PK columns the WHERE clause will remain correct.

If you elect not to declare a primary key, DBIx::Class will behave correctly by throwing exceptions on any row operation that relies on unique identifiable rows. If you inherited datasets with multiple identical rows in them, you can still operate with such sets provided you only utilize DBIx::Class::ResultSet CRUD methods: search, update, delete

For example, the following would not work (assuming People does not have a declared PK):

 my $row = $schema->resultset('People')
                   ->search({ last_name => 'Dantes' })
                    ->next;
 $row->update({ children => 2 }); # <-- exception thrown because $row isn't
                                  # necessarily unique

So instead the following should be done:

 $schema->resultset('People')
         ->search({ last_name => 'Dantes' })
          ->update({ children => 2 }); # <-- update's ALL Dantes to have children of 2

Problems on RHEL5/CentOS5¶

There used to be an issue with the system perl on Red Hat Enterprise Linux 5, some versions of Fedora and derived systems. Further information on this can be found in DBIx::Class::Manual::Troubleshooting

SEE ALSO¶

• DBIx::Class::Manual::Cookbook

翻訳について¶

翻訳者：加藤敦 (ktat.is at gmail.com)

Perlドキュメント日本語訳 Project にて、 Perlモジュール、ドキュメントの翻訳を行っております。

 http://perldocjp.sourceforge.jp/
 http://sourceforge.jp/projects/perldocjp/
 http://www.freeml.com/perldocjp/
 http://www.perldoc.jp