=encoding euc-jp

=head1 名前

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

=head1 イントロダクション

So, you are bored with SQL, and want a native Perl interface for your
database?  Or you've been doing this for a while with L<Class::DBI>,
and think there's a better way?  You've come to the right place.

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

=head1 THE DBIx::Class WAY

Here are a few simple tips that will help you get your bearings 
with DBIx::Class.  

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

=head2 テーブルはResultSourcesになる

DBIx::Class needs to know what your Table structure looks like.  You do that
by defining L<DBIx::Class::ResultSource>s.  Each table get's a ResultSource,
which defines the Columns it has, along with any Relationships it has to
other tables.  (And oh, so much more besides)  The important thing to 
understand:
  
DBIx::Class は、対象となるテーブルの構造がどんなものなのかを知っている必要があります。
そのために、L<DBIx::Class::ResultSource>を定義します。それぞれのテーブルにResultSourceがあり、
テーブルのカラムや他のテーブルとのリレーションシップを定義します。
(そして、ああ、それ以上に、)理解しなればいけない、重要なことは:

  A ResultSource == Table
  
(most of the time, but just bear with my simplification)

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

=head2 ResultSetについての全て

So, we've got some ResultSources defined.  Now, we want to actually use 
those definitions to help us translate the queries we need into
handy perl objects!  

ResultSourceを定義出来たので、実際に、必要なクエリをお手軽なPerlのオブジェクトに
翻訳するのに、この定義を使いたいですね！

Let's say we defined a ResultSource for an "album" table with three 
columns: "albumid", "artist", and "title".  Any time we want to query
this table, we'll be creating a L<DBIx::Class::ResultSet> from it's
ResultSource.  For example, the results of:

次のカラムを持った"album"のResultSourceを定義したとしましょう: "albumid" と
"artist" と "title"。 このテーブルに問い合わせたいときはいつでも、
そのResultSourceから、L<DBIx::Class::ResultSet>オブジェクトを作ります。
例えば、次の結果の:

    SELECT albumid, artist, title FROM album;
    
Would be retrieved by creating a ResultSet object from the album
table's ResultSource, likely by using the "search" method.  

album テーブルの ResultSource から ResultSetオブジェクトを作ることで、
おそらく、"search" メソッドを使って、取得できます。

DBIx::Class doesn't limit you to creating only simple ResultSets --
if you wanted to do something like:

DBIx::Classは単純なResultSetsを作るだけではありません -- 
次のようなものが欲しければ:

    SELECT title FROM album GROUP BY title;
   
You could easily achieve it. 

簡単にできます。

The important thing to understand: 

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

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

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

=head2 Search は "prepare"のようなもの

DBIx::Class tends to wait until it absolutely must fetch information
from the database.  If you are returning a ResultSet, the query won't
execute until you use a method that wants to access the data. (Such
as "next", or "first")

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

The important thing to understand:

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

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

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

=head1 DBIx::Classのセットアップ

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

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

First we'll see how you can set up your classes yourself.  If you want
them to be auto-discovered, just skip to the next section, which shows
you how to use L<DBIx::Class::Schema::Loader>.

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

=head2 手でセットアップする

First, you should create your base schema class, which inherits from
L<DBIx::Class::Schema>:

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

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

In this class you load your result_source ("table", "model") classes, which
we will define later, using the load_classes() method. You can specify which
classes to load manually: 

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

  # load My::Schema::Album and My::Schema::Artist
  __PACKAGE__->load_classes(qw/ Album Artist /);

Or load classes by namespace:

または、名前空間でクラスをロードします:

  # load My::Schema::Album, My::Schema::Artist and My::OtherSchema::LinerNotes
  __PACKAGE__->load_classes(
    {
      'My::Schema' => [qw/ Album Artist /],
      'My::OtherSchema' => [qw/ LinerNotes /]
    }
  );

Or let your schema class load all classes in its namespace automatically:

または、スキーマクラスで、その名前空間にある全てのクラスを自動的にロードします:

   # load My::Schema::*
  __PACKAGE__->load_classes();

Next, create each of the classes you want to load as specified above:

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

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

Load any components required by each class with the load_components() method.
This should consist of "Core" plus any additional components you want to use.
For example, if you want serial/auto-incrementing primary keys:

それぞれのクラスに必要な全てのコンポーネントを load_components() メソッドでロードします。
"Core"にプラスして、使いたい追加のコンポーネントがあるべきです。
例えば、シリアル/オートインクリメントなプライマリーキーが必要なら:

  __PACKAGE__->load_components(qw/ PK::Auto Core /);

C<PK::Auto> is supported for many databases; see
L<DBIx::Class::Storage::DBI> for more information.

C<PK::Auto>は多くのデーターベースをサポートします;
詳しくは、L<DBIx::Class::Storage::DBI>を見てください。

Set the table for your class:

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

  __PACKAGE__->table('album');

Add columns to your class:

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

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

Each column can also be set up with its own accessor, data_type and other
pieces of information that it may be useful to have, just pass C<add_columns>
a hash such as:

それぞれのカラムは、それ自身のアクセサや、あったほうが便利な、data_type や他の情報も
C<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 => '',
                            }
                         );

Most of this data isn't yet used directly by DBIx::Class, but various related
modules such as L<DBIx::Class::WebForm> make use of it. Also it allows you
to create your database tables from your Schema, instead of the other way
around. See L<SQL::Translator> for details.

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

See L<DBIx::Class::ResultSource> for more details of the possible column
attributes.

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

Accessors are created for each column automatically, so My::Schema::Album will
have albumid() (or album(), when using the accessor), artist() and title()
methods.

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

Define a primary key for your class:

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

  __PACKAGE__->set_primary_key('albumid');

If you have a multi-column primary key, just pass a list instead:

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

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

Define relationships that the class has with any other classes by using
either C<belongs_to> to describe a column which contains an ID of another
table, or C<has_many> to make a predefined accessor for fetching objects
that contain this tables foreign key in one of their columns:

クラスが他のクラスと関係があるというリレーションシップを定義することも出来ます。
C<belongs_to>でカラムが他のテーブルのIDを含んでいることや、
C<has_many>で、カラムの1つに、このテーブルの外部キーを含むオブジェクトを取得する
定義済みのアクセサを作れます。

  __PACKAGE__->has_many('albums', 'My::Schema::Artist', 'album_id');

More information about the various types of relationships available, and
how you can design your own, can be found in L<DBIx::Class::Relationship>.

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

=head2 L<DBIx::Class::Schema::Loader>を使う

This is an external module, and not part of the L<DBIx::Class>
distribution.  Like L<Class::DBI::Loader>, it inspects your database,
and automatically creates classes for all the tables in your database.
Here's a simple setup:

これは外部のモジュールであり、L<DBIx::Class>のディストリビューション一部では
ありません。L<Class::DBI::Loader>と同様に、データベースを調べて、
データベース内の全てのテーブル用のクラスを自動的に作ります。単純なセットアップ:

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

  __PACKAGE__->loader_options( relationships => 1 );

  1;

The actual autoloading process will occur when you create a connected
instance of your schema below.

実際の自動ロードのプロセスは下記のスキーマの接続されたインスタンスを作るときに
起こります。

L<DBIx::Class::Schema::Loader> takes lots of other options.  For more
information, consult its documentation.

L<DBIx::Class::Schema::Loader>は、たくさんの他のオプションがあります。
詳しくは、ドキュメントを見てください。

=head2 接続

To connect to your Schema, you also need to provide the connection details.
The arguments are the same as you would use for L<DBI/connect>:

スキーマに接続するためには、接続のための詳細情報を提供しなければいけません。
引数は、L<DBI/connect>と同じです:

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

You can create as many different schema instances as you need. So if you have
a second database you want to access:

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

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

Note that L<DBIx::Class::Schema> does not cache connections for you. If you
use multiple connections, you need to do this manually.

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

To execute some sql statements on every connect you can add them as an option
in a special fifth argument to connect, like so:

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

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

For more information about this and other special C<connect()>-time options,
see L<DBIx::Class::Schema::Storage::DBI/connect_info>.

これについてより詳しい情報と、他の特別なC<connect()>-時のオプションについては、
L<DBIx::Class::Schema::Storage::DBI/connect_info>を見てください。

=head2 基本の使い方

Once you've defined the basic classes, either manually or using
L<DBIx::Class::Schema::Loader>, you can start interacting with your database.

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

To access your database using your $schema object, you can fetch a L<DBIx::Class::Manual::Glossary/"ResultSet">
representing each of your tables by calling the ->resultset method.

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

The simplest way to get a record is by primary key:

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

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

This will run a C<SELECT> with C<albumid = 14> in the C<WHERE> clause,
and return an instance of C<My::Schema::Album> that represents this
row.  Once you have that row, you can access and update columns:

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

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

If you prefer, you can use the C<set_column> and C<get_column>
accessors instead:

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

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

Just like with L<Class::DBI>, you call C<update> to commit your
changes to the database:

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

  $album->update;

If needed, you can throw away your local changes like this:

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

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

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

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

=head2 列の追加及び削除

To create a new record in the database, you can use the C<create>
method.  It returns an instance of C<My::Schema::Album> that can be
used to access the data in the new record:

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

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

Now you can add data to the new record:

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

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

Likewise, you can remove it from the database like this:

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

  $new_album->delete;

You can also remove records without retrieving them first, by calling
delete directly on a ResultSet object.

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

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

=head2 オブジェクトを探す

L<DBIx::Class> provides a few different ways to retrieve data from
your database.  Here's one example:

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

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

In scalar context, as above, C<search> returns a
L<DBIx::Class::ResultSet> object.  It can be used to peek at the first
album returned by the database:

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

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

You can loop over the albums and update each one:

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

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

Or, you can update them all at once:

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

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

For more information on what you can do with a
L<DBIx::Class::ResultSet>, see L<DBIx::Class::ResultSet/METHODS>.

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

In list context, the C<search> method returns all of the matching
rows:

リストコンテキストでは、C<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;
  }

We also provide a handy shortcut for doing a C<LIKE> search:

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

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

Or you can provide your own C<WHERE> clause, like:

もしくは、次のように、自分自身のC<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 );

The preferred way to generate complex queries is to provide a
L<SQL::Abstract> construct to C<search>:

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

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

This results in something like the following C<WHERE> clause:

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

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

For more examples of complex queries, see
L<DBIx::Class::Manual::Cookbook>.

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

The search can also be modified by passing another hash with
attributes:

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

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

C<@albums> then holds the two most recent Bob Marley albums.

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

For a complete overview of the available attributes, see
L<DBIx::Class::ResultSet/ATTRIBUTES>.

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

=head1 SEE ALSO

=over 4

=item * L<DBIx::Class::Manual::Cookbook>

=back

=head1 翻訳について

翻訳者：加藤敦 (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

=cut