Newer Older
1154 lines | 39.69kb
added experimental expand me...
yuki-kimoto authored on 2010-10-20
1
=encoding utf8
2

            
updated document
yuki-kimoto authored on 2010-10-22
3
=head1 NAME
added experimental expand me...
yuki-kimoto authored on 2010-10-20
4

            
pod fix
Yuki Kimoto authored on 2011-01-21
5
DBIx::Custom::Guide::Ja - DBIx::Customの日本語ガイド
added experimental expand me...
yuki-kimoto authored on 2010-10-20
6

            
7
=head1 ガイド
8

            
9
L<DBIx::Custom>はデータベースへのクエリの発行を簡単に行うための
10
クラスです。L<DBIx::Class>やL<DBIx::Simple>と同じように
updated document
Yuki Kimoto authored on 2011-01-20
11
L<DBI>のラッパクラスになっています。L<DBIx::Class>よりも簡単に、
12
L<DBIx::Simple>よりもはるかに柔軟なことを行うことができます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
13

            
14
L<DBIx::Custom>はO/Rマッパーではありません。O/Rマッパーは
15
便利ですが、O/Rマッパのたくさんの文法を覚える必要があります。
updated document
Yuki Kimoto authored on 2011-01-20
16
また、O/Rマッパによって生成されたSQLは非効率なことがありますし、
17
複雑なSQLを生成することができないので、
18
生のSQLを発行しなければならない場合がたくさんあります。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
19

            
updated document
Yuki Kimoto authored on 2011-01-20
20
L<DBIx::Custom>はO/Rマッパとは対照的な設計が行われています。
updated document
Yuki Kimoto authored on 2011-01-20
21
L<DBIx::Custom>の主な目的は、SQLを尊重しつつ、L<DBI>だけでは
updated document
Yuki Kimoto authored on 2011-01-20
22
とてもめんどうな作業を簡単にすることです。もしSQLについて
23
多くの知識を持っているならば、L<DBIx::Custom>でそのまま
updated document
Yuki Kimoto authored on 2011-01-20
24
活用することができます。
updated document
Yuki Kimoto authored on 2011-01-20
25

            
26
L<DBIx::Custom>の仕組みを簡単に説明しておきましょう。
27
L<DBIx::Custom>では、タグと呼ばれるものを
28
SQLの中に埋め込むことができます。
29

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

            
32
{}で囲まれた部分がタグです。このSQLは実際に実行されるときには
33
次のようにプレースホルダに展開されます。
34

            
updated document
Yuki Kimoto authored on 2011-01-20
35
    select * from book where title = ? and author = ?;
updated document
Yuki Kimoto authored on 2011-01-20
36

            
37
これらの展開にはどのような意味があるのでしょうかと質問
updated document
Yuki Kimoto authored on 2011-01-20
38
されることかと思います。この簡単な仕組みの上に非常にたくさんの
39
有用で便利で使いやすい機能が構築されます。それは以下のようなものです。
updated document
Yuki Kimoto authored on 2011-01-20
40

            
updated document
Yuki Kimoto authored on 2011-01-20
41
=over 4
updated document
Yuki Kimoto authored on 2011-01-20
42

            
updated document
Yuki Kimoto authored on 2011-01-20
43
=item 1. プレースホルダのパラメータをハッシュリファレンスで指定
updated document
Yuki Kimoto authored on 2011-01-20
44

            
updated document
Yuki Kimoto authored on 2011-01-20
45
L<DBI>をそのまま使うのであればプレースホルダのパラメータは配列
46
で指定する必要があります。
updated document
Yuki Kimoto authored on 2011-01-20
47

            
updated document
Yuki Kimoto authored on 2011-01-20
48
    $sth->execute(@bind);
49

            
50
L<DBIx::Custom>を利用するのであればハッシュリファレンスで指定すること
51
できます。
52
    
53
    my $param = {title => 'Perl', author => 'Ken'};
54
    $dbi->execute($sql, $param);
55

            
56
=item 2. パラメータのフィルタリング
57

            
58
たとえば、日付の列は、Perlで扱うときにはC<Time::Piece>などの日付オブジェクト
59
で扱い、データベースに格納するときはデータベースの日付型に変換したい
60
と思うのではないでしょうか。またデータベースから取り出すときは
61
データベースの日付型から日付オブジェクトに変換したと思うのでは
62
ないでしょうか。
63

            
64
このようなときはフィルタ機能を使うことができます。
65

            
66
まずフィルタを登録します。
67

            
68
    $dbi->register_filter(
69
        tp_to_date => sub {
70
            ...
71
        },
72
        date_to_tp => sub {
73
            ...
74
        }
75
    );
76

            
77
次にテーブルの各列にこのフィルタを適用します。
78

            
79
    $dbi->apply_filter('book',
renamed dbi_options to dbi_o...
Yuki Kimoto authored on 2011-01-23
80
        'issue_date' => {out => 'tp_to_date', in => 'date_to_tp'}
updated document
Yuki Kimoto authored on 2011-01-20
81
    );
82

            
83
outはPerlからデータベースに保存する方向、inはデータベースからPerlに取得する方向です。
84

            
85
SQLを発行するときにテーブルの指定を行えば、自動的にこのフィルタが適用されます。
86

            
87
    $dbi->execute($sql, $param, table => 'book');
88

            
89
=item 3. 選択的な検索条件
90

            
91
生のDBIを利用しているとき一番たいへんなのは選択的な検索条件を作成したいときです。
92

            
93
たとえば、検索条件にtitleとauthorが指定された場合は次のSQLを
94

            
95
    select * from book where title = ? and author = ?;
96

            
97
titleだけの場合は次のSQLを
98

            
99
    select * from book where title = ?;
100
    
101
authorだけの場合は次のSQLを発行した場合を考えましょう。
102

            
103
    select * from book where author = ?;
104

            
105
これはとても大変な作業なので、通常はL<SQL::Abstract>を動的に生成してくれる
106
モジュールを利用することになります。
107

            
108
L<DBIx::Custom>はさらに簡単で便利な方法を用意しています。
109

            
110
    my $where = $dbi->where;
111
    $where->param({title => 'Perl'});
112
    $where->clause(
113
        ['and', '{= title}', {'= author'}]
114
    );
115

            
116
    my $sql = "select * from book $where";
117

            
118
詳しい説明は後ほど行いますが、上記のように記述すれば、
119
L<DBIx::Custom>では選択的な検索条件を持つWhere句を生成することができます。
120
検索条件が入れ子になった構造やorについても対応しています。
121

            
122
=item 4. 挿入、更新、削除、選択を行うためのメソッド
123

            
124
L<DBIx::Custom>ではSQLをさらに簡単に実行するための
125
メソッドも提供しています。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
126
C<insert()>, C<update()>, C<delete()>,C<select()>などの
updated document
Yuki Kimoto authored on 2011-01-20
127
シュガーメソッドを使って、挿入、更新、削除、選択という操作を行うことが
128
できます。
129

            
130
    my $param = {title => 'Perl', author => 'Ken'};
131
    $dbi->insert(table => 'book', param => $param);
132

            
133
=item 5. テーブル単位の操作の登録
134

            
135
テーブルに対して操作を登録することができます。これによって
136
テーブル名を繰り返し指定する必要がなくなり、ソースコードの
137
見通しが良くなります。
138

            
139
    $dbi->talbe('book',
140
        list => sub {
141
            ...
142
        },
143
        list_somethin => sub {
144
            
145
        }
146
    );
147

            
148
登録したメソッドはそのまま利用することができます。
149

            
150
    $dbi->table('book')->list;
added experimental expand me...
yuki-kimoto authored on 2010-10-20
151

            
updated document
Yuki Kimoto authored on 2011-01-20
152
通常O/Rマッパはテーブルに対応するクラスを作成しなければ
153
ならないことが多いですが、L<DBIx::Custom>ではこの作業を簡便に
154
しており、上記のように登録することができます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
155

            
updated document
Yuki Kimoto authored on 2011-01-20
156
=back
157

            
158
L<DBIx::Custom>はL<DBI>を補うとても便利なモジュールです。
159
興味をもたれた方は、この後で詳しい解説を行いますので、
160
ご覧になってみてください。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
161

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

            
updated document
Yuki Kimoto authored on 2011-01-23
164
まずL<DBIx::Custom>を読み込みます。
165

            
166
    use DBIx::Custom;
167

            
added experimental expand me...
yuki-kimoto authored on 2010-10-20
168
L<DBIx::Custom>オブジェクトを生成し、データベースに接続するには
169
C<connect()>メソッドを使用します。
170

            
updated document
Yuki Kimoto authored on 2011-01-23
171
    my $dbi = DBIx::Custom->connect(
172
        data_source => "dbi:mysql:database=dbname",
173
        user => 'ken',
174
        password => '!LFKD%$&',
175
        dbi_options => {mysql_enable_utf8 => 1}
176
    );
added experimental expand me...
yuki-kimoto authored on 2010-10-20
177

            
updated document
Yuki Kimoto authored on 2011-01-23
178
C<data_source>はデータベースシステムに応じたフォーマットで
179
指定する必要があります。以下にデータベースごとのフォーマット
180
方法のサンプルを掲載しておきます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
181

            
updated document
Yuki Kimoto authored on 2011-01-23
182
B<MySQL>
added experimental expand me...
yuki-kimoto authored on 2010-10-20
183

            
deprecated DBIx::Custom::MyS...
root authored on 2010-11-26
184
    "dbi:mysql:database=$database"
185
    "dbi:mysql:database=$database;host=$hostname;port=$port"
added experimental expand me...
yuki-kimoto authored on 2010-10-20
186

            
updated document
Yuki Kimoto authored on 2011-01-23
187
B<SQLite>
deprecated DBIx::Custom::MyS...
root authored on 2010-11-26
188

            
189
    "dbi:SQLite:dbname=$database"
190
    "dbi:SQLite:dbname=:memory:"
191

            
updated document
Yuki Kimoto authored on 2011-01-23
192
B<PostgreSQL>
deprecated DBIx::Custom::MyS...
root authored on 2010-11-26
193

            
194
    "dbi:Pg:dbname=$dbname"
195

            
updated document
Yuki Kimoto authored on 2011-01-23
196
B<Oracle>
deprecated DBIx::Custom::MyS...
root authored on 2010-11-26
197

            
198
    "dbi:Oracle:$dbname"
199
    "dbi:Oracle:host=$host;sid=$sid"
200

            
updated document
Yuki Kimoto authored on 2011-01-23
201
B<ODBC(Microsoft Access)>
deprecated DBIx::Custom::MyS...
root authored on 2010-11-26
202

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

            
updated document
Yuki Kimoto authored on 2011-01-23
205
B<ODBC(SQL Server)>
deprecated DBIx::Custom::MyS...
root authored on 2010-11-26
206

            
207
   "dbi:ODBC:driver={SQL Server};Server=(local);database=test;Trusted_Connection=yes;AutoTranslate=No;"
added experimental expand me...
yuki-kimoto authored on 2010-10-20
208

            
updated document
Yuki Kimoto authored on 2011-01-23
209
また認証が求められる場合は、C<user>とC<password>ユーザ名と
210
パスワードを指定する必要があります。
211

            
added experimental expand me...
yuki-kimoto authored on 2010-10-20
212
L<DBIx::Custom>はL<DBI>のラッパです。
updated document
Yuki Kimoto authored on 2011-01-23
213
L<DBI>のデータベースハンドルはC<dbh>で取得することができます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
214

            
215
    my $dbh = $dbi->dbh;
216

            
updated document
Yuki Kimoto authored on 2011-01-23
217
L<DBIx::Custom>ではデータベースハンドル属性にはデフォルトで次のものが設定されます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
218
    
219
    $dbi->dbh->{RaiseError} = 1;
220
    $dbi->dbh->{PrintError} = 0;
221
    $dbi->dbh->{AutoCommit} = 1;
222

            
223
この設定を行っているので、致命的なエラーが起こると、
224
例外が発生しプログラムは終了します。
225
またクエリが発行されると自動的にコミットされます。
226

            
updated document
Yuki Kimoto authored on 2011-01-23
227
=head2 2. 挿入、更新、削除、選択のためのメソッド
added experimental expand me...
yuki-kimoto authored on 2010-10-20
228

            
229
L<DBIx::Custom>は、
230
C<insert()>、C<update()>、C<delete()>、C<select()>
updated document
Yuki Kimoto authored on 2011-01-23
231
のような挿入、更新、削除、選択を行うためのメソッドを持っています。
232
簡単なことをを行うのであれば、SQLを自分で記述する必要がありません。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
233

            
update pod
Yuki Kimoto authored on 2011-01-26
234
=head3 データの挿入 C<insert()>
added experimental expand me...
yuki-kimoto authored on 2010-10-20
235

            
updated document
Yuki Kimoto authored on 2011-01-23
236
データベースにデータを挿入するにはC<insert()>を使用します。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
237

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
238
    $dbi->insert(table  => 'book',
added experimental expand me...
yuki-kimoto authored on 2010-10-20
239
                 param  => {title => 'Perl', author => 'Ken'});
240

            
updated document
Yuki Kimoto authored on 2011-01-23
241
C<table>にはテーブル名、C<param>には挿入したいデータを指定します。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
242

            
updated document
Yuki Kimoto authored on 2011-01-23
243
次のSQLが発行されます。
244

            
245
    insert into (title, author) values (?, ?);
added experimental expand me...
yuki-kimoto authored on 2010-10-20
246

            
update pod
Yuki Kimoto authored on 2011-01-26
247
=head3 データの更新 C<update()>
added experimental expand me...
yuki-kimoto authored on 2010-10-20
248

            
updated document
Yuki Kimoto authored on 2011-01-23
249
データベースのデータを更新するには、C<update()>を使用します。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
250

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
251
    $dbi->update(table  => 'book', 
added experimental expand me...
yuki-kimoto authored on 2010-10-20
252
                 param  => {title => 'Perl', author => 'Ken'}, 
253
                 where  => {id => 5});
254

            
updated document
Yuki Kimoto authored on 2011-01-23
255
C<table>にはテーブル名、C<param>には挿入したいデータ、C<where>には
256
条件を指定します。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
257

            
updated document
Yuki Kimoto authored on 2011-01-23
258
次のSQLが発行されます。
259

            
260
    update book set title = ?, author = ?;
added experimental expand me...
yuki-kimoto authored on 2010-10-20
261

            
262
C<update>メソッドは安全のため
263
where句のないSQLを発行することを許可していません。
264
もしすべての行を更新したい場合は
updated document
Yuki Kimoto authored on 2011-01-23
265
C<update_all()>を使用してください。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
266

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
267
    $dbi->update_all(table  => 'book', 
added experimental expand me...
yuki-kimoto authored on 2010-10-20
268
                     param  => {title => 'Perl', author => 'Ken'});
269

            
update pod
Yuki Kimoto authored on 2011-01-26
270
=head3 データの削除 C<delete()>
added experimental expand me...
yuki-kimoto authored on 2010-10-20
271

            
updated document
Yuki Kimoto authored on 2011-01-23
272
データベースのデータを1件削除するには、C<delete()>を使用します。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
273

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
274
    $dbi->delete(table  => 'book',
added experimental expand me...
yuki-kimoto authored on 2010-10-20
275
                 where  => {author => 'Ken'});
276

            
updated document
Yuki Kimoto authored on 2011-01-23
277
C<table>にはテーブル名、C<where>には条件を指定します。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
278

            
updated document
Yuki Kimoto authored on 2011-01-23
279
次のSQLが発行されます。
280

            
281
    delete from book where id = ?;
added experimental expand me...
yuki-kimoto authored on 2010-10-20
282

            
283
C<delete>メソッドは安全のため
284
where句のないSQLを発行することを許可していません。
285
もしすべての行を削除したい場合は
updated document
Yuki Kimoto authored on 2011-01-23
286
C<delete_all()>を使用してください。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
287

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
288
    $dbi->delete_all(table  => 'book');
added experimental expand me...
yuki-kimoto authored on 2010-10-20
289

            
update pod
Yuki Kimoto authored on 2011-01-26
290
=head3 データの選択 C<select()>
added experimental expand me...
yuki-kimoto authored on 2010-10-20
291

            
updated document
Yuki Kimoto authored on 2011-01-23
292
行を選択するにはC<select()>を使用します。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
293

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
294
    my $result = $dbi->select(table => 'book');
added experimental expand me...
yuki-kimoto authored on 2010-10-20
295

            
updated document
Yuki Kimoto authored on 2011-01-23
296
C<table>だけを指定して、他の条件を指定しない場合は次のSQLが発行されます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
297

            
updated document
Yuki Kimoto authored on 2011-01-23
298
    select * from book;
added experimental expand me...
yuki-kimoto authored on 2010-10-20
299

            
300
C<select()>メソッドの戻り値はL<DBIx::Custom::Result>
updated document
Yuki Kimoto authored on 2011-01-23
301
オブジェクトです。行をフェッチするにはC<fetch()>を使用します。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
302

            
303
    while (my $row = $result->fetch) {
304
        my $title  = $row->[0];
305
        my $author = $row->[1];
306
    }
307

            
updated document
Yuki Kimoto authored on 2011-01-23
308
L<DBIx::Custom::Result>についてはこの後L<3. 行のフェッチ/"3. 行のフェッチ">で詳しく扱います。
309

            
310
さまざまなC<select()>の使い方を見ていきましょう。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
311
次のC<select>は行の名前とwhere句を指定したものです。
312

            
313
    my $result = $dbi->select(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
314
        table  => 'book',
updated document
Yuki Kimoto authored on 2011-01-23
315
        column => ['author',  'title'],
added experimental expand me...
yuki-kimoto authored on 2010-10-20
316
        where  => {author => 'Ken'}
317
    );
318

            
updated document
Yuki Kimoto authored on 2011-01-23
319
C<column>には列名を、C<where>には条件を指定することができます。
320
次のSQLが発行されます。
321

            
322
    select author, title from book where author = ?;
added experimental expand me...
yuki-kimoto authored on 2010-10-20
323

            
updated document
Yuki Kimoto authored on 2011-01-23
324
テーブルを結合したい場合ははC<relation>にテーブルの
325
関係を記述します。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
326

            
327
    my $result = $dbi->select(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
328
        table    => ['book', 'rental'],
updated document
Yuki Kimoto authored on 2011-01-23
329
        where    => {book.name => 'Perl'},
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
330
        relation => {'book.id' => 'rental.book_id'}
added experimental expand me...
yuki-kimoto authored on 2010-10-20
331
    );
332

            
updated document
Yuki Kimoto authored on 2011-01-23
333
bookテーブルのid列とrentalテーブルのbook_idが関連付けられます。
334
次のSQLが発行されます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
335

            
updated document
Yuki Kimoto authored on 2011-01-23
336
    select * from book, rental where book.name = ? and book.id = rental.book_id;
added experimental expand me...
yuki-kimoto authored on 2010-10-20
337

            
updated document
Yuki Kimoto authored on 2011-01-23
338
SQL文の末尾に文字列を追加したい場合は<append>を使用します。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
339

            
340
    my $result = $dbi->select(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
341
        table  => 'book',
added experimental expand me...
yuki-kimoto authored on 2010-10-20
342
        where  => {author => 'Ken'},
updated document
Yuki Kimoto authored on 2011-01-23
343
        append => 'for update',
added experimental expand me...
yuki-kimoto authored on 2010-10-20
344
    );
345

            
updated document
Yuki Kimoto authored on 2011-01-23
346
次のSQLが発行されます。
updated document
Yuki Kimoto authored on 2011-01-20
347

            
updated document
Yuki Kimoto authored on 2011-01-23
348
    select * book where author = ? for update;
updated document
Yuki Kimoto authored on 2011-01-20
349

            
updated document
Yuki Kimoto authored on 2011-01-23
350
またC<append>は、C<select>だけでなくC<insert()>、C<update()>、C<update_all()>
351
C<delete()>、C<delete_all()>、C<select()>で使用することもできます。
updated document
Yuki Kimoto authored on 2011-01-20
352

            
update pod
Yuki Kimoto authored on 2011-01-26
353
=head3 SQLの実行 C<execute()>
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
354

            
355
任意のSQLを実行するにはexecuteメソッドを使用します。
356

            
357
    $dbi->execute("select * from book;");
358

            
359
C<execute()>はL<DBIx::Custom>の根幹のメソッドでありタグを展開します。
360

            
361
    $dbi->execute(
362
        "select * from book {= title} and {= author};"
363
        param => {title => 'Perl', author => 'Ken'}
364
    );
365

            
366
上記のタグを含んだSQLは次のように展開されます。
367

            
368
    select * from book title = ? and author = ?;
369

            
370
SQLが実行されるときにプレースホルダ(?)に対応する位置にtitleとauthor
371
の値がが自動的に埋め込まれます。
372

            
373
タグについてはL<5. タグ/"5. タグ">で詳しく解説しますが、
374
ひとつの注意点があります。
375
タグを展開するためにC<{>とC<}>は予約語になっています。
376
もし利用したい場合は直前に\をおいてエスケープを行う必要があります。
377

            
378
    $dbi->execute("... \\{ ... \\} ...");
379

            
380
\自体がPerlのエスケープ文字ですので、二つ必要になるという点に注意してください。
381

            
382
またexecuteのキュートな機能として、SQLの最後にセミコロンをおかなくても
383
かまいません。
384

            
385
    $dbi->execute('select * from book');
386

            
updated document
Yuki Kimoto authored on 2011-01-20
387
=head2 3. 行のフェッチ
388

            
updated document
Yuki Kimoto authored on 2011-01-23
389
C<select()>メソッドの戻り値はL<DBIx::Custom::Result>オブジェクトです。
390
L<DBIx::Custom::Result>には行をフェッチするためのさまざまなメソッドが
updated document
Yuki Kimoto authored on 2011-01-20
391
用意されています。
392

            
update pod
Yuki Kimoto authored on 2011-01-26
393
=head3 1行づつフェッチ(配列) C<fetch()>
updated document
Yuki Kimoto authored on 2011-01-20
394

            
updated document
Yuki Kimoto authored on 2011-01-23
395
一行フェッチして配列のリファレンスに格納するにはC<fetch()>を使用します。
updated document
Yuki Kimoto authored on 2011-01-20
396

            
397
    while (my $row = $result->fetch) {
updated document
Yuki Kimoto authored on 2011-01-23
398
        my $title  = $row->[0];
399
        my $author = $row->[1];
updated document
Yuki Kimoto authored on 2011-01-20
400
    }
401

            
updated document
Yuki Kimoto authored on 2011-01-23
402
whileループを使って、すべての行を取得することができます。
403

            
update pod
Yuki Kimoto authored on 2011-01-26
404
=head3 最初の行だけフェッチ(配列) C<fetch_first()>
updated document
Yuki Kimoto authored on 2011-01-20
405

            
updated document
Yuki Kimoto authored on 2011-01-23
406
一行だけフェッチして配列のリファレンスに格納するにはC<fetch_first()>
407
を使用します。
updated document
Yuki Kimoto authored on 2011-01-20
408

            
409
    my $row = $result->fetch_first;
410

            
updated document
Yuki Kimoto authored on 2011-01-23
411
一行のフェッチが終わった後はそれ以上フェッチできなくなります。
412
内部的には1行のフェッチが終わった後に
413
ステートメントハンドルのC<finish()>が実行されます。
updated document
Yuki Kimoto authored on 2011-01-20
414

            
update pod
Yuki Kimoto authored on 2011-01-26
415
=head3 複数行を順にフェッチ(配列) C<fetch_multi()>
updated document
Yuki Kimoto authored on 2011-01-20
416

            
updated document
Yuki Kimoto authored on 2011-01-23
417
複数行をフェッチして配列のリファレンスを要素に持つ
418
配列のリファレンスに格納するにはC<fetch_multi()>を使用します。
updated document
Yuki Kimoto authored on 2011-01-20
419

            
updated document
Yuki Kimoto authored on 2011-01-23
420
    while (my $rows = $result->fetch_multi(2)) {
421
        my $title0   = $rows->[0][0];
422
        my $author0  = $rows->[0][1];
423
        
424
        my $title1   = $rows->[1][0];
425
        my $author1  = $rows->[1][1];
updated document
Yuki Kimoto authored on 2011-01-20
426
    }
427

            
updated document
Yuki Kimoto authored on 2011-01-23
428
引数には取り出したい行数を指定します。
429

            
430
指定した行を格納した次のようなデータを取得できます。
431

            
432
    [
433
        ['Perl', 'Ken'],
434
        ['Ruby', 'Mark']
435
    ]
436

            
update pod
Yuki Kimoto authored on 2011-01-26
437
=head3 すべての行をフェッチ(配列) C<fetch_all>
updated document
Yuki Kimoto authored on 2011-01-20
438

            
updated document
Yuki Kimoto authored on 2011-01-23
439
すべての行をフェッチして配列のリファレンスを要素に持つ
440
配列のリファレンスに格納するにはC<fetch_all()>を使用します。
updated document
Yuki Kimoto authored on 2011-01-20
441

            
442
    my $rows = $result->fetch_all;
443

            
updated document
Yuki Kimoto authored on 2011-01-23
444
すべての行を格納した次のようなデータを取得できます。
445

            
446
    [
447
        ['Perl', 'Ken'],
448
        ['Ruby', 'Mark']
449
    ]
450

            
update pod
Yuki Kimoto authored on 2011-01-26
451
=head3 1行づつフェッチ(ハッシュ) C<fetch_hash()>
updated document
Yuki Kimoto authored on 2011-01-20
452

            
updated document
Yuki Kimoto authored on 2011-01-23
453
一行フェッチしてハッシュのリファレンスに格納するにはC<fetch_hash()>を使用します。
updated document
Yuki Kimoto authored on 2011-01-20
454

            
455
    while (my $row = $result->fetch_hash) {
456
        my $title  = $row->{title};
457
        my $author = $row->{author};
458
    }
459

            
update pod
Yuki Kimoto authored on 2011-01-26
460
=head3 最初の行だけフェッチ(ハッシュ) C<fetch_hash_first()>
updated document
Yuki Kimoto authored on 2011-01-20
461

            
updated document
Yuki Kimoto authored on 2011-01-23
462
一行だけフェッチしてハッシュのリファレンスに格納するには
463
C<fetch_hash_first()>を使用します。
updated document
Yuki Kimoto authored on 2011-01-20
464

            
465
    my $row = $result->fetch_hash_first;
466

            
updated document
Yuki Kimoto authored on 2011-01-23
467
一行のフェッチが終わった後はそれ以上フェッチできなくなります。
468
内部的には1行のフェッチが終わった後に
469
ステートメントハンドルのC<finish()>が実行されます。
updated document
Yuki Kimoto authored on 2011-01-20
470

            
update pod
Yuki Kimoto authored on 2011-01-26
471
=head3 複数行を順にフェッチ(ハッシュ) C<fetch_hash_multi()>
updated document
Yuki Kimoto authored on 2011-01-20
472

            
updated document
Yuki Kimoto authored on 2011-01-23
473
複数行をフェッチしてハッシュのリファレンスを要素に持つ
474
配列のリファレンスに格納するにはC<fetch_hash_multi()>
475
を使用します。
updated document
Yuki Kimoto authored on 2011-01-20
476

            
477
    while (my $rows = $result->fetch_hash_multi(5)) {
updated document
Yuki Kimoto authored on 2011-01-23
478
        my $title0   = $rows->[0]{title};
479
        my $author0  = $rows->[0]{author};
480
        my $title1  = $rows->[1]{title};
481
        my $author1 = $rows->[1]{author};
updated document
Yuki Kimoto authored on 2011-01-20
482
    }
483

            
updated document
Yuki Kimoto authored on 2011-01-23
484
引数には取り出したい行数を指定します。
485

            
486
指定した行を格納した次のようなデータを取得できます。
487

            
488
    [
489
        {title => 'Perl', author => 'Ken'},
490
        {title => 'Ruby', author => 'Mark'}
491
    ]
492

            
update pod
Yuki Kimoto authored on 2011-01-26
493
=head3 すべての行をフェッチ(ハッシュ) C<fetch_hash_all()>
updated document
Yuki Kimoto authored on 2011-01-20
494

            
updated document
Yuki Kimoto authored on 2011-01-23
495
すべての行をフェッチしてハッシュのリファレンスを要素に持つ
496
配列のリファレンスに格納するにはC<fetch_hash_all()>
497
を使用します。
updated document
Yuki Kimoto authored on 2011-01-20
498

            
499
    my $rows = $result->fetch_hash_all;
500

            
updated document
Yuki Kimoto authored on 2011-01-23
501
すべての行を格納した次のようなデータを取得できます。
502

            
503
    [
504
        {title => 'Perl', author => 'Ken'},
505
        {title => 'Ruby', author => 'Mark'}
506
    ]
507

            
update pod
Yuki Kimoto authored on 2011-01-26
508
=head3 ステートメントハンドル C<sth()>
updated document
Yuki Kimoto authored on 2011-01-23
509

            
510
ステートメントハンドルに直接アクセスしたい場合は
511
<sth>で取得することができます。
updated document
Yuki Kimoto authored on 2011-01-20
512

            
513
    my $sth = $result->sth;
514

            
updated document
Yuki Kimoto authored on 2011-01-23
515
フェッチのパフォーマンスが用件を満たさないときには、
516
ステートメントハンドルから
517
利用できる速度の速いメソッドを利用することができます。
518

            
renamed dbi_options to dbi_o...
Yuki Kimoto authored on 2011-01-23
519
=head2 4. フィルタリング
520

            
521
データベースにデータを登録するときやデータベースからデータを取得する
522
ときに自動的に値の変換を行いたい場合が多いと思います。
523
たとえば、日付を表現する列の場合は、
524
データベースに登録する場合はL<Time::Piece>オブジェクトから
525
データベースの日付のフォーマットに、
526
データベースからデータを取得するときは、その逆を行えると便利です。
527

            
update pod
Yuki Kimoto authored on 2011-01-26
528
=head3 フィルタの登録 C<register_filter()>
renamed dbi_options to dbi_o...
Yuki Kimoto authored on 2011-01-23
529

            
530
フィルタを登録するにはC<register_filter()>を使用します。
531

            
532
    $dbi->register_filter(
533
        # Time::Piece object to DATE format
534
        tp_to_date => sub {
535
            my $date = shift;
536

            
537
            return '0000-00-00' unless $tp;
538
            return $tp->strftime('%Y-%m-%d');
539
        },
540
        
541
        # DATE to Time::Piece object
542
        date_to_tp => sub {
543
            my $date = shift;
544

            
545
            return if $date eq '0000-00-00';
546
            return Time::Piece->strptime($date, '%Y-%m-%d');
547
        },
548
    );
549

            
550
登録したフィルタはC<apply_filter()>などで利用することができます。
551

            
update pod
Yuki Kimoto authored on 2011-01-26
552
=head3 フィルタの適用 C<apply_filter()>
renamed dbi_options to dbi_o...
Yuki Kimoto authored on 2011-01-23
553

            
554
作成したフィルタを適用するには、C<apply_filter()>を使用します。
555

            
556
    $dbi->apply_filter('book',
557
        issue_date => {out => 'tp_to_date', in => 'date_to_tp'},
558
        first_issue_date => {out => 'tp_to_date', in => 'date_to_tp'}
559
    );
560

            
561
第一引数はテーブル名です。第二引数以降は、列名とフィルタルールのペアを記述します。
562
フィルタルールのoutには、データベースにデータを送信するときに適用するフィルタを、
563
フィルタルールのinには、データベースからデータを取得するときに適用するフィルタを
564
記述します。outがデータベースに送信する方向、inがデータベースから取り出す方向です。
565
フィルタには、C<register_filter>で登録したフィルタ名の他に、コードリファレンスを
566
指定することもできます。
567

            
568
    issue_date => {out => sub { ... }, in => sub { ... }}
569

            
570
適用されたフィルタはC<insert()>、C<update()>、C<update_all()>、C<delete()>、
571
C<delete_all()>、C<select()>で有効になります。
572

            
573
    my $tp = Time::Piece->strptime('2010/10/14', '%Y/%m/%d');
574
    my $result = $dbi->select(table => 'book', where => {issu_date => $tp});
575

            
576
データベースにデータが送信されるときに、L<Time::Piece>オブジェクトは
577
データベースの日付のフォーマット「2010-10-14」に変換されます。
578

            
579
また逆にデータをフェッチするときには、データベースの日付のフォーマットは
580
タイムピースオブジェクトに変換されます。
581

            
582
    my $row = $resutl->fetch_hash_first;
583
    my $tp = $row->{issue_date};
584

            
585
このような自動的に実行されるフィルタを登録できることがL<DBIx::Custom>の
586
特徴のひとつです。
587

            
update pod
Yuki Kimoto authored on 2011-01-26
588
=head3 個別のフィルタの適用 C<filter>
renamed dbi_options to dbi_o...
Yuki Kimoto authored on 2011-01-23
589

            
590
C<apply_filter()>を使って最初にすべてのテーブルの列について
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
591
フィルタを定義することもできますが、
592
個別にフィルタを適用することもできます。
renamed dbi_options to dbi_o...
Yuki Kimoto authored on 2011-01-23
593
個別のフィルタはC<apply_filter()>で適用したフィルタを上書きます。
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
594
個別のフィルタはSQLのasを使って、列の別名を作成する必要がある場合に活躍します。
595

            
596
データベースに送信する場合に、個別のフィルタを適用するには、各メソッドの
597
C<filter>オプションを使用します。個別のフィルタは、C<insert()>、C<update()>、
598
C<update_all()>、C<delete()>、C<delete_all()>、C<select()>、C<execute()>
599
で使用することができます。
renamed dbi_options to dbi_o...
Yuki Kimoto authored on 2011-01-23
600

            
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
601
C<insert()>の例を示します。
602

            
603
    $dbi->insert(
604
        table => 'book',
605
        param => {issue_date => $tp, first_issue_date => $tp},
606
        filter => {issue_date => 'tp_to_date', first_issue_date => 'tp_to_date'}
607
    );
608

            
609
C<execute()>の例を示します。
610

            
611
my $sql = <<"EOS";
612
select YEAR(issue_date) as issue_year
613
from book
614
where YEAR(issue_date) = {? issue_year}
615
EOS
616
   
617
    my $result = $dbi->execute(
618
        $sql,
619
        param => {issue_year => '2010'},
620
        filter => {issue_year => 'tp_to_year'}
621
    );
622

            
623
これはC<filter>を使う良くある例です。issue_dateの変換についてはC<apply_filter()>
624
で登録してあるのですが、新しく作成した列であるissue_yearについては、
625
何の変換も登録されていません。ですので、個別にフィルタを設定しています。
626

            
627
また反対に行をフェッチするときにも個別のフィルタを適用することができます。
628
フィルタを適用するには、
renamed dbi_options to dbi_o...
Yuki Kimoto authored on 2011-01-23
629
C<DBIx::Custom::Result>クラスのC<filter>メソッドを使用します。
630

            
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
631
    $result->filter(issue_year => 'year_to_tp');
632

            
633
頻繁に利用するのであれば、個別に登録するよりもC<apply_filter()>で登録
634
しておいたほうが便利でしょう。C<apply_filter()>は存在しない列に対しても
635
フィルタを適用できるからです。
636

            
637
    $dbi->apply_filter('book',
638
        'issue_year' => {out => 'tp_to_year', in => 'year_to_tp'}
639
    );
640

            
update pod
Yuki Kimoto authored on 2011-01-26
641
=head3 最終出力のためのフィルタリング C<end_filter()>
642

            
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
643
C<DBIx::Custom::Result>ではさらに最後にもう一度、フィルタを追加で
644
登録することができます。たとえばHTMLに出力したい場合に、Time::Piece
645
オブジェクトから読みやすい記述に変換することができます。
646
最後のフィルタを登録するには、C<end_filter()>を使用します。
647

            
648
    $result->end_filter(issue_date => sub {
649
        my $tp = shift;
650
        
651
        return '' unless $tp;
652
        return $tp->strftime('%Y/%m/%d %h:%m:%s (%a)');
653
    });
654

            
655
日付を見やすい形にフォーマットすることができます。
656

            
657
フィルタはフェッチを行う前に登録しておく必要があることに
658
注意してください。
659

            
660
    $result->filter(...);
661
    $result->end_filter(...);
662
    my $row = $result->fetch_hash_first;
663

            
update pod
Yuki Kimoto authored on 2011-01-26
664
=head3 列の情報を元にフィルタを適用する C<each_column()>
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
665

            
666
日付型の列は手動で設定しなくても、自動的に設定できると便利です。
667
このためにデータベースのテーブルの列のすべての情報を
668
順番に処理するためのC<each_column()>があります。
669

            
670
    $dbi->each_column(
671
        sub {
672
            my ($self, $table, $column, $info) = @_;
673
            
674
            my $type = $info->{TYPE_NAME};
675
            
676
            my $filter = $type eq 'DATE'     ? {out => 'tp_to_date', in => 'date_to_tp'}
677
                       : $type eq 'DATETIME' ? {out => 'tp_to_datetime', in => 'datetime_to_tp'}
678
                                             : undef;
679
            
680
            $self->apply_filter($table, $column, $filter)
681
              if $filter;
682
        }
683
    );
renamed dbi_options to dbi_o...
Yuki Kimoto authored on 2011-01-23
684

            
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
685
each_columnはコールバックを受け取ります。コールバックの引数は
686
順番にL<DBIx::Custom>オブジェクト、テーブル名、列名、列の情報です。
687
列の型名の情報をもとに自動的に、フィルタを適用しています。
688

            
689
ひとつの注意点としてコールバックの中から、コールバックの外側
690
の変数を参照しないように注意してください。each_columnは
691
高々1回だけ実行されるだけなので、ほとんどの場合問題ありませんが、
692
循環参照によるメモリリークが発生してしまう可能性を持っているからです。
renamed dbi_options to dbi_o...
Yuki Kimoto authored on 2011-01-23
693

            
694
=head2 5. タグ
updated document
Yuki Kimoto authored on 2011-01-20
695

            
update pod
Yuki Kimoto authored on 2011-01-26
696
=head3 タグの機能
updated document
Yuki Kimoto authored on 2011-01-20
697

            
update pod
Yuki Kimoto authored on 2011-01-26
698
L<DBIx::Custom>はSQLの中にタグを埋め込む機能を持っています。
updated document
Yuki Kimoto authored on 2011-01-20
699

            
update pod
Yuki Kimoto authored on 2011-01-26
700
    select * from book where {= title} and {like author};
updated document
Yuki Kimoto authored on 2011-01-20
701

            
update pod
Yuki Kimoto authored on 2011-01-26
702
{= title}と{like author}の部分がタグです。タグは次のような形式
703
を持ちます。
updated document
Yuki Kimoto authored on 2011-01-20
704

            
update pod
Yuki Kimoto authored on 2011-01-26
705
    {タグ名 引数1 引数2 ...}
706
    
707
タグはC<{>で始まり、C<}>で終わります。最初のC<{>とタグ名の間
708
には空白を挿入しないよう注意してください。
updated document
Yuki Kimoto authored on 2011-01-20
709

            
update pod
Yuki Kimoto authored on 2011-01-26
710
タグの機能のためにC<{>とC<}>は予約語になっています。
711
もし利用したい場合は直前に\をおいてエスケープを行う必要があります。
updated document
Yuki Kimoto authored on 2011-01-20
712

            
update pod
Yuki Kimoto authored on 2011-01-26
713
    select from book \\{ ... \\}
714

            
715
C<\>自体がPerlのエスケープ文字ですので、
716
エスケープする場合はC<\>が二つ必要になるという点に注意してください。
717

            
718
上記のタグはSQLが実行される前に次のSQLに展開されます。
719

            
720
    select * from book where title = ? and author like ?;
updated document
Yuki Kimoto authored on 2011-01-20
721

            
update pod
Yuki Kimoto authored on 2011-01-26
722
タグを含むSQLを実行するにはC<execute()>を使用します。
updated document
Yuki Kimoto authored on 2011-01-20
723

            
update pod
Yuki Kimoto authored on 2011-01-26
724
    my $sql = "select * from book where {= author} and {like title};"
725
    $dbi->execute($sql, param => {title => 'Perl', author => '%Ken%'});
updated document
Yuki Kimoto authored on 2011-01-20
726

            
update pod
Yuki Kimoto authored on 2011-01-26
727
C<param>オプションを使って、プレースホルダに埋め込みたい値を
728
ハッシュリファレンスで指定することができます。
updated document
Yuki Kimoto authored on 2011-01-20
729

            
update pod
Yuki Kimoto authored on 2011-01-26
730
他のメソッドと同様にC<execute()>においてもC<filter>を指定することができます。
731

            
732
    $dbi->execute($sql, param => {title => 'Perl', author => '%Ken%'}
733
                  filter => {title => 'to_something');
734

            
735
C<execute>のひとつの注意点としてはC<apply_filter()>で適用されたフィルタ
736
はデフォルトでは有効ではないということに注意してください。
737
C<apply_filter()>で適用されたフィルタを有効にするには、
738
C<table>を指定する必要があります。
739

            
740
    $dbi->execute($sql, param => {title => 'Perl', author => '%Ken%'}
741
                  table => ['book']);
742

            
743
=head2 タグ一覧
744

            
745
L<DBIx::Custom>では次のタグが使用可能です。
updated document
Yuki Kimoto authored on 2011-01-20
746

            
747
このようにタグを使ってSQL文を表現するのがL<DBIx::Custom>の
748
特徴です。以下のタグが利用可能です。
749

            
update pod
Yuki Kimoto authored on 2011-01-26
750
=head3 C<?>
751

            
752
C<?>タグは以下のように展開されます。
753

            
754
    {? NAME}    ->   ?
755

            
756
=head3 C<=>
757

            
758
C<=>タグは以下のように展開されます。
759

            
760
    {= NAME}    ->   NAME = ?
761

            
762
=head3 C<E<lt>E<gt>>
763

            
764
C<E<lt>E<gt>>タグは以下のように展開されます。
765

            
766
    {<> NAME}   ->   NAME <> ?
767

            
768
=head3 C<E<lt>>
769

            
770
C<E<lt>>タグは以下のように展開されます。
771

            
772
    {< NAME}    ->   NAME < ?
773

            
774
=head3 C<E<gt>>
775

            
776
C<E<gt>>タグは以下のように展開されます。
777

            
778
    {> NAME}    ->   NAME > ?
779

            
780
=head3 C<E<gt>=>
781

            
782
C<E<gt>=>タグは以下のように展開されます。
783

            
784
    {>= NAME}   ->   NAME >= ?
785

            
786
=head3 C<E<lt>=>
787

            
788
C<E<lt>=>タグは以下のように展開されます。
789

            
790
    {<= NAME}   ->   NAME <= ?
791

            
792
=head3 C<like>
793

            
794
C<like>タグは以下のように展開されます。
795

            
796
    {like NAME}   ->   NAME like ?
797

            
798
=head3 C<in>
799

            
800
C<in>タグは以下のように展開されます。プレースホルダの
801
数を引数で指定する必要があることに注意してください。
802

            
803
    {in NAME COUNT}   ->   NAME in [?, ?, ..]
804

            
805
=head3 C<insert_param>
806

            
807
C<insert_param>タグは以下のように展開されます。
808

            
updated document
Yuki Kimoto authored on 2011-01-20
809
    {insert_param NAME1 NAME2}   ->   (NAME1, NAME2) values (?, ?)
update pod
Yuki Kimoto authored on 2011-01-26
810

            
811
=head3 C<update_param>
812

            
813
C<update_param>タグは以下のように展開されます。
814

            
updated document
Yuki Kimoto authored on 2011-01-20
815
    {update_param NAME1 NAME2}   ->   set NAME1 = ?, NAME2 = ?
816

            
update pod
Yuki Kimoto authored on 2011-01-26
817
=head2 同名の列の扱い
updated document
Yuki Kimoto authored on 2011-01-20
818

            
update pod
Yuki Kimoto authored on 2011-01-26
819
同名の列を含むタグがある場合にも、SQLを実行することができます。
820
たとえば、二つの日付で比較しなければならない場合を
821
考えて見ましょう。
updated document
Yuki Kimoto authored on 2011-01-20
822

            
update pod
Yuki Kimoto authored on 2011-01-26
823
    my $sql = "select * from table where {> date} and {< date};";
updated document
Yuki Kimoto authored on 2011-01-20
824

            
update pod
Yuki Kimoto authored on 2011-01-26
825
このような場合は対応するパラメータの値を配列のリファレンスにします。
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
826

            
update pod
Yuki Kimoto authored on 2011-01-26
827
    my $dbi->execute($sql, param => {date => ['2010-10-01', '2012-02-10']});
828

            
829
=head2 タグの追加 C<register_tag()>
830

            
831
D<DBIx::Custom>ではタグを独自に追加することができます。
832
タグを追加するにはC<register_tag()>を使用します。
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
833

            
834
    $dbi->register_tag(
update pod
Yuki Kimoto authored on 2011-01-26
835
        '=' => sub {
836
            my $column = shift;
837
            
838
            return ["$column = ?", [$column]];
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
839
        }
840
    );
841

            
update pod
Yuki Kimoto authored on 2011-01-26
842
ここではデフォルトのC<=>タグがどのように実装されているかを示しています。
843
タグを登録する関数の引数はタグの中に書かれた引数になります。
844

            
845
    {タグ名 引数1 引数2}
846

            
847
C<=>タグの場合は
848

            
849
    {= title}
850

            
851
という形式ですから、サブルーチンにはtitleというひとつの列名がわたってきます。
852

            
853
サブルーチンの戻り値には次の形式の配列のリファレンスを返す必要があります。
854

            
855
    [
856
        展開後の文字列,
857
        [プレースホルダに埋め込みに利用する列名1, 列名2, ...]
858
    ]
859

            
860
一つ目の要素は展開後の文字列です。この例では
861

            
862
    'title = ?'
863

            
864
を返す必要があります。
865

            
866
二つ目の要素はプレースホルダに埋め込みに利用する列名を含む配列の
867
リファレンスです。今回の例では
868

            
869
    ['title']
870

            
871
を返す必要があります。複数のプレースホルダを含む場合は、この部分が
872
複数になります。C<insert_param>タグやC<update_param>タグは
873
この部分が実際複数になっています。
874

            
875
上記を合わせると
876

            
877
    ['title = ?', ['title']]
878
    
879
を返す必要があるということです。
880

            
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
881
タグの実装の他のサンプルはL<DBIx::Custom::Tag>のソースコード
882
をご覧になってみてください。
883

            
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
884
=head2 6. Where句の動的な生成
885

            
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
886
=head3 Where句の動的な生成 where()
887

            
888
複数の検索条件を指定して、検索を行いたい場合があります。
889
次の3つのケースのwhere句を考えてみましょう。
890
下記のようなwhere句が必要になります。
891

            
892
titleの値だけで検索したい場合
893

            
894
    where {= title}
895

            
896
authorの値だけで検索したい場合
897

            
898
    where {= author}
899

            
900
titleとauthorの両方の値で検索したい場合
901

            
902
    where {= title} and {=author}
903

            
904
L<DBIx::Custom>では動的なWhere句の生成をサポートしています。
905
まずC<where()>でL<DBIx::Custom::Where>オブジェクトを生成します。
906

            
907
    my $where = $dbi->where;
908

            
909
次にC<clause()>を使用してwhere句を記述します。
910

            
911
    $where->clause(
912
        ['and', '{= title'}, '{= author}']
913
    );
914

            
915
clauseの指定方法は次のようになります。
916

            
917
    ['or' あるいは 'and', タグ1, タグ2, タグ3]
918

            
919
第一引数にはorあるいはandを指定します。第二引数以降には
920
検索条件をタグを使って記述します。
921

            
922
C<clause>の指定は入れ子にすることもでき、さらに複雑な条件
923
を記述することもできます。
924

            
925
    ['and', 
926
      '{= title}', 
927
      ['or', '{= author}', '{like date}']
928
    ]
929

            
930
このようにC<clause>を設定した後にC<param>にパラメータを指定します。
931
    
932
    my $param => {title => 'Perl'};
933
    $where->param($param);
934

            
935
この例ではtitleだけがパラメータに含まれています。
936

            
937
この後C<to_string()>を実行すると$paramに含まれるパラメータを満たす
938
where句を生成することができます。
939

            
940
    my $where_clause = $where->to_string;
941

            
942
パラメータはtitleだけですので、次のようなwhere句が生成されます。
943

            
944
    where {= title}
945

            
946
またD<DBIx::Custom>は文字列の評価をオーバーロードして、C<to_string()>
947
を呼び出すようにしていますので、次のようにしてwhere句を生成することも
948
できます。
949

            
950
    my $where_clause = "$where";
951

            
952
これはSQLの中にwhere句を埋め込むときにとても役立つ機能です。
953

            
make delete() using where ob...
Yuki Kimoto authored on 2011-01-26
954
=head3 同一の列名を含む場合
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
955

            
make delete() using where ob...
Yuki Kimoto authored on 2011-01-26
956
タグの中に同一の名前を持つものが存在した場合でも動的に
957
where句を作成することができます。
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
958

            
make delete() using where ob...
Yuki Kimoto authored on 2011-01-26
959
たとえば、パラメータとして開始日付と終了日付を受け取ったことを
960
考えてみてください。
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
961

            
make delete() using where ob...
Yuki Kimoto authored on 2011-01-26
962
    my $param = {start_date => '2010-11-15', end_date => '2011-11-21'};
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
963

            
make delete() using where ob...
Yuki Kimoto authored on 2011-01-26
964
また開始日付と終了日付の片方だけや、どちらも受け取らない場合もあるかもしれません。
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
965

            
make delete() using where ob...
Yuki Kimoto authored on 2011-01-26
966
この場合は次のようなパラメータに変換することで対応することができます。
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
967

            
make delete() using where ob...
Yuki Kimoto authored on 2011-01-26
968
    my $p = {date => ['2010-11-15', '2011-11-21']};
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
969

            
make delete() using where ob...
Yuki Kimoto authored on 2011-01-26
970
値が配列のリファレンスになっていることに注目してください。このようにすれば
971
同名の列を含むタグに順番に埋め込むことができます。
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
972

            
make delete() using where ob...
Yuki Kimoto authored on 2011-01-26
973
    $where->clause(
974
        ['and', '{> date}', '{< date}']
975
    );
976
    $where->param($p);
977

            
978
また開始日付が存在しない場合は次のようなデータを作成します。
979

            
980
    my $p = {date => [$dbi->not_exists, '2011-11-21']};
981

            
982
L<DBIx::Custom>のC<not_exists>でDBIx::Custom::NotExistsオブジェクトを
983
取得できます。これは対応する値が存在しないことを示すためのものです。
984

            
985
また終了日付が存在しない場合は次のようなデータを作成します。
986

            
987
    my $p = {date => ['2010-11-15']};
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
988

            
make delete() using where ob...
Yuki Kimoto authored on 2011-01-26
989
どちらも存在しない場合は次のようなデータを作成します。
990

            
991
    my $p = {date => []};
992

            
993
少し難しいので一番簡単に作成できるロジックを示しておきます。
994

            
995
    my @date;
996
    push @date, exists $param->{start_date} ? $param->{start_date}
997
                                            : $dbi->not_exists;
998
    push @date, $param->{end_date} if exists $param->{end_date};
999
    my $p = {date => \@date};
1000

            
1001
=head3 C<select()>との連携
1002

            
1003
C<select()>との連携です。C<select()>のC<where>に直接渡すことが
1004
できます。
1005
    
1006
    my $where = $dbi->where;
1007
    $where->clause(...);
1008
    $where->param($param);
1009
    my $result = $dbi->select(table => 'book', where => $where);
1010

            
1011
あるいはC<update>、C<delete>と連携することが可能です。
1012

            
1013
=head3 C<execute()>との連携
1014

            
1015
C<execute()>との連携です。SQLを作成するときに埋め込むことができます。
1016

            
1017

            
1018
    my $where = $dbi->where;
1019
    $where->clause(...);
1020
    $where->param($param);
1021

            
1022
    my $sql = <<"EOS"
1023
    select * from book;
1024
    $where
1025
    EOS
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
1026

            
make delete() using where ob...
Yuki Kimoto authored on 2011-01-26
1027
    $dbi->execute($sql, param => $param);
added experimental not_exist...
Yuki Kimoto authored on 2011-01-26
1028

            
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
1029
=head2 7. パフォーマンスの改善
updated document
Yuki Kimoto authored on 2011-01-20
1030

            
1031
=head3 シュガーメソッドを使わない
1032

            
1033
もしC<insert()>メソッドを使用してインサートを実行した場合、
1034
必要なパフォーマンスを得られない場合があるかもしれません。
1035
C<insert()>メソッドは、SQL文とステートメントハンドルを
1036
毎回作成するためすこし遅いです。
1037

            
1038
そのような場合は、C<create_query()>メソッドによって
1039
クエリを用意しておくことができます。
1040
    
1041
    my $query = $dbi->create_query(
1042
        "insert into book {insert_param title author};"
1043
    );
1044

            
1045
戻り値はL<DBIx::Custom::Query>オブジェクトです。
1046
このオブジェクトはSQL文とパラメータバインド時の列名を
1047
保持しています。またステートメントハンドルも保持しています。
1048

            
1049
    {
1050
        sql     => 'insert into book (title, author) values (?, ?);',
1051
        columns => ['title', 'author'],
1052
        sth     => $sth
1053
    }
1054

            
1055
クエリオブジェクトを使って繰り返し実行するには次のようにします。
1056
    
1057
    my $inputs = [
1058
        {title => 'Perl',      author => 'Ken'},
1059
        {title => 'Good days', author => 'Mike'}
1060
    ];
1061
    
1062
    foreach my $input (@$inputs) {
1063
        $dbi->execute($query, $input);
1064
    }
1065

            
1066
C<execute>メソッドの第一引数にクエリオブジェトを渡すことができます。
1067
これはC<insert()>メソッドよりも高速です。
1068

            
removed experimental txn_sco...
Yuki Kimoto authored on 2011-01-24
1069
=head2 8. その他の機能
updated document
Yuki Kimoto authored on 2011-01-20
1070

            
1071
=head3 トランザクション
1072

            
1073
トランザクションを便利に利用するために、
1074
C<begin_work()>、C<commit()>、C<rollback()>
1075
という三つのメソッドが容易されています。
1076
これはL<DBI>の同名のメソッドと同じ機能を持ちます。
renamed dbi_options to dbi_o...
Yuki Kimoto authored on 2011-01-23
1077
fc
updated document
Yuki Kimoto authored on 2011-01-20
1078
    $dbi->begin_work;
1079
    
1080
    eval {
1081
        $dbi->update(...);
1082
        $dbi->update(...);
1083
    };
1084
    
1085
    if ($@) {
1086
        $dbi->rollback;
1087
    }
1088
    else {
1089
        $dbi->commit;
1090
    }
1091

            
updated pod
Yuki Kimoto authored on 2011-01-24
1092
=head3 結果クラスの変更
updated document
Yuki Kimoto authored on 2011-01-20
1093

            
1094
必要ならばC<select()>メソッドの結果クラスを変更することができます。
1095

            
1096
    package Your::Result;
1097
    use base 'DBIx::Custom::Result';
1098
    
1099
    sub some_method { ... }
1100

            
1101
    1;
1102
    
1103
    package main;
1104
    
1105
    use Your::Result;
1106
    
1107
    my $dbi = DBIx::Custom->connect(...);
1108
    $dbi->result_class('Your::Result');
1109

            
1110
=head3 ヘルパーメソッドの登録
1111

            
1112
ヘルパーメソッドを登録することができます。
1113

            
1114
    $dbi->helper(
1115
        update_or_insert => sub {
1116
            my $self = shift;
1117
            # do something
1118
        },
1119
        find_or_create   => sub {
1120
            my $self = shift;
1121
            # do something
1122
        }
1123
    );
1124

            
1125
<helper()>メソッドで登録したメソッドは
1126
L<DBIx::Custom>オブジェクトから直接呼び出すことができます。
1127

            
1128
    $dbi->update_or_insert;
1129
    $dbi->find_or_create;
1130

            
updated pod
Yuki Kimoto authored on 2011-01-24
1131
=head3 その他便利なメソッド
updated document
Yuki Kimoto authored on 2011-01-20
1132

            
1133
C<expand>メソッドを使用すると次のようなハッシュに含まれる
1134
テーブル名と列名を結合することができます。
1135

            
1136
    my %expanded = $dbi->expand(\%source);
1137

            
1138
以下のハッシュ
1139

            
1140
    {book => {title => 'Perl', author => 'Ken'}}
1141

            
1142
は次のように展開されます。
1143

            
1144
    ('book.title' => 'Perl', 'book.author' => 'Ken')
1145

            
1146
これはテーブル名を含むselect文で利用すると便利です。
1147

            
1148
    my $param = {title => 'Perl', author => '%Ken%'};
1149
    $dbi->execute(
1150
        'select * from book where {= book.title} && {like book.author};',
1151
        param => {$dbi->expand({book => $param})}
1152
    );
1153

            
1154
=cut