=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