=encoding utf8

=head1 NAME

DBIx::Custom::Guides::Ja - DBIx::Customの日本語ガイド

=head1 ガイド

L<DBIx::Custom>はデータベースへのクエリの発行を簡単に行うための

クラスです。L<DBIx::Class>やL<DBIx::Simple>と同じように

L<DBI>のラッパクラスになっています。

L<DBIx::Custom>はO/Rマッパーではありません。O/Rマッパーは

便利ですが、O/Rマッパのたくさんの文法を覚える必要があります。

また、O/Rマッパによって生成されたSQLは非効率なことがありますし、

複雑なSQLを生成することができないので、

生のSQLを発行しなければならない場合がたくさんあります。

L<DBIx::Custom>はO/Rマッパとは対照的な設計が行われています。

L<DBIx::Custom>の主な目的は、SQLを尊重しつつ、DBIだけでは

とてもめんどうな作業を簡単にすることです。もしSQLについて

多くの知識を持っているならば、L<DBIx::Custom>でそのまま

生かすことができます。

L<DBIx::Custom>の仕組みを簡単に説明しておきましょう。

L<DBIx::Custom>では、タグと呼ばれるものを

SQLの中に埋め込むことができます。

    select * from book where {= title} and {=author};

{}で囲まれた部分がタグです。このSQLは実際に実行されるときには

次のようにプレースホルダに展開されます。

    select * from book where title = ? and title = ?;

これらの展開にはどのような意味があるのでしょうかと質問

されることかと思います。

またSQLを簡単に実行するための、

C<insert()>, C<update()>, C<delete()>,C<select()>などの

シュガーメソッドも提供します。

L<DBIx::Custom>はSQLを尊重します。SQLはとても複雑で、美しくはありません。

けれども、SQLはデファクトスタンダードな技術です。

ですので、データベースを学ぶすべての人はSQLを知っています。

あなたがすでにSQLを知っているなら、L<DBIx::Custom>を使って

何かを行うために覚えることはとても少ないです。

では使い方を解説します。

=head2 1. データベースへの接続

L<DBIx::Custom>オブジェクトを生成し、データベースに接続するには

C<connect()>メソッドを使用します。

    use DBIx::Custom;

    my $dbi = DBIx::Custom->connect(data_source => "dbi:mysql:database=dbname",

                                    user => 'ken', password => '!LFKD%$&');

B<Data sourceのサンプル:>

MySQL

    "dbi:mysql:database=$database"

    "dbi:mysql:database=$database;host=$hostname;port=$port"

SQLite

    "dbi:SQLite:dbname=$database"

    "dbi:SQLite:dbname=:memory:"

PostgreSQL

    "dbi:Pg:dbname=$dbname"

Oracle

    "dbi:Oracle:$dbname"

    "dbi:Oracle:host=$host;sid=$sid"

ODBC(Microsoft Access)

    "dbi:ODBC:driver=Microsoft Access Driver (*.mdb);dbq=hoge.mdb"

ODBC(SQL Server)

   "dbi:ODBC:driver={SQL Server};Server=(local);database=test;Trusted_Connection=yes;AutoTranslate=No;"

L<DBIx::Custom>はL<DBI>のラッパです。

L<DBI>オブジェクトはC<dbh>で取得することができます。

    my $dbh = $dbi->dbh;

データベースハンドル属性にはデフォルトで次のものが設定されます。

    $dbi->dbh->{RaiseError} = 1;

    $dbi->dbh->{PrintError} = 0;

    $dbi->dbh->{AutoCommit} = 1;

この設定を行っているので、致命的なエラーが起こると、

例外が発生しプログラムは終了します。

またクエリが発行されると自動的にコミットされます。

=head2 2. シュガーメソッド

L<DBIx::Custom>は、

C<insert()>、C<update()>、C<delete()>、C<select()>

のようなシュガーメソッドを持っています。

小さなことを行うのであれば、SQL文を

作成する必要はありません。

=head3 C<insert()>

C<insert>メソッドです。データベースにデータを挿入します。

    $dbi->insert(table  => 'book',

                 param  => {title => 'Perl', author => 'Ken'});

これは次のL<DBI>の操作と同じです。

    my $sth = $dbh->prepare('insert into (title, author) values (?, ?);');

    $sth->execute('Perl', 'Ken');

=head3 C<update()>

C<update>メソッドです。データベースのデータを更新します。

    $dbi->update(table  => 'book', 

                 param  => {title => 'Perl', author => 'Ken'}, 

                 where  => {id => 5});

これは次のL<DBI>の操作と同じです。

    my $sth = $dbh->prepare(

        'update book set title = ?, author = ? where id = ?;');

    $sth->execute('Perl', 'Ken', 5);

C<update>メソッドは安全のため

where句のないSQLを発行することを許可していません。

もしすべての行を更新したい場合は

C<update_all()>メソッドを使用してください。

    $dbi->update_all(table  => 'book', 

                     param  => {title => 'Perl', author => 'Ken'});

=head3 C<delete()>

C<delete>メソッドです。データベースのデータを削除します。

    $dbi->delete(table  => 'book',

                 where  => {author => 'Ken'});

これは次のL<DBI>の操作と同じです。

    my $sth = $dbh->prepare('delete from book where id = ?;');

    $sth->execute('Ken');

C<delete>メソッドは安全のため

where句のないSQLを発行することを許可していません。

もしすべての行を削除したい場合は

C<delete_all()>メソッドを使用してください。

    $dbi->delete_all(table  => 'book');

=head3 C<select()>

C<select>メソッドです。テーブル名だけを指定しています。

    my $result = $dbi->select(table => 'book');

これは次のL<DBI>の操作と同じです。

    my $sth = $dbh->prepare('select * from book;);

    $sth->execute;

C<select()>メソッドの戻り値はL<DBIx::Custom::Result>

オブジェクトです。C<fetch>メソッドを使用して

行をフェッチすることができます。

    while (my $row = $result->fetch) {

        my $title  = $row->[0];

        my $author = $row->[1];

    }

次のC<select>は行の名前とwhere句を指定したものです。

    my $result = $dbi->select(

        table  => 'book',

        column => [qw/author title/],

        where  => {author => 'Ken'}

    );

次のL<DBI>の操作と同じです。

    my $sth = $dbh->prepare(

        'select author, title from book where author = ?;');

    $sht->execute('Ken');

テーブルをjoinしたい場合はC<relation>を使用します。

    my $result = $dbi->select(

        table    => ['book', 'rental'],

        column   => ['book.name as book_name']

        relation => {'book.id' => 'rental.book_id'}

    );

次のL<DBI>の操作と同じです。

    my $sth = $dbh->prepare(

        'select book.name as book_name from book, rental' .

        'where book.id = rental.book_id;');

    $sth->execute;

SQL文の末尾に文字列を追加したい場合は<append>オプションを使用します。

    my $result = $dbi->select(

        table  => 'book',

        where  => {author => 'Ken'},

        append => 'order by price limit 5',

    );

次のL<DBI>の操作と同じです。

    my $sth = $dbh->prepare(

        'select * book where author = ? order by price limit 5;');

    $sth->execute;

C<append>オプションは、C<insert()>、C<update()>、C<update_all()>

C<delete()>、C<select>メソッドで使用することが

できます。

この後のフィルタリングの解説で詳しく扱いますが、値をフィルタリングしたい

場合はC<filter>オプションを使用することができます。

    $dbi->insert(table  => 'book',

                 param  => {title => 'Perl', author => 'Ken'});

                 filter => {title  => 'encode_utf8',

                            a