Newer Older
728 lines | 23.772kb
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

            
updated document
yuki-kimoto authored on 2010-10-22
5
DBIx::Custom::Guides::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>と同じように
11
L<DBI>のラッパクラスになっています。
12

            
13
L<DBIx::Custom>はO/Rマッパーではありません。O/Rマッパーは
14
便利ですが、O/Rマッパのたくさんの文法を覚える必要があります。
15
また、O/Rマッパによって生成されたSQLは非効率なことがあり、
16
生のSQLを発行しなければならないこともあります。
17

            
18
L<DBIx::Custom>はO/RマッパとL<DBI>の中間に位置するモジュールです。
19
L<DBIx::Custom>は柔軟なハッシュパラメータバインディングとフィルタリング
20
のシステムを提供します。またSQLを簡単に実行するための、
21
C<insert()>, C<update()>, C<delete()>,C<select()>などの
22
シュガーメソッドも提供します。
23

            
24
L<DBIx::Custom>はSQLを尊重します。SQLはとても複雑で、美しくはありません。
25
けれども、SQLはデファクトスタンダードな技術です。
26
ですので、データベースを学ぶすべての人はSQLを知っています。
27
あなたがすでにSQLを知っているなら、L<DBIx::Custom>を使って
28
何かを行うために覚えることはとても少ないです。
29

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

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

            
34
L<DBIx::Custom>オブジェクトを生成し、データベースに接続するには
35
C<connect()>メソッドを使用します。
36

            
37
    use DBIx::Custom;
38
    my $dbi = DBIx::Custom->connect(data_source => "dbi:mysql:database=dbname",
39
                                    user => 'ken', password => '!LFKD%$&');
40

            
deprecated DBIx::Custom::MyS...
root authored on 2010-11-26
41
B<Data sourceのサンプル:>
added experimental expand me...
yuki-kimoto authored on 2010-10-20
42

            
deprecated DBIx::Custom::MyS...
root authored on 2010-11-26
43
MySQL
added experimental expand me...
yuki-kimoto authored on 2010-10-20
44

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

            
deprecated DBIx::Custom::MyS...
root authored on 2010-11-26
48
SQLite
49

            
50
    "dbi:SQLite:dbname=$database"
51
    "dbi:SQLite:dbname=:memory:"
52

            
53
PostgreSQL
54

            
55
    "dbi:Pg:dbname=$dbname"
56

            
57
Oracle
58

            
59
    "dbi:Oracle:$dbname"
60
    "dbi:Oracle:host=$host;sid=$sid"
61

            
62
ODBC(Microsoft Access)
63

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

            
66
ODBC(SQL Server)
67

            
68
   "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
69

            
70
L<DBIx::Custom>はL<DBI>のラッパです。
71
L<DBI>オブジェクトはC<dbh>で取得することができます。
72

            
73
    my $dbh = $dbi->dbh;
74

            
75
データベースハンドル属性にはデフォルトで次のものが設定されます。
76
    
77
    $dbi->dbh->{RaiseError} = 1;
78
    $dbi->dbh->{PrintError} = 0;
79
    $dbi->dbh->{AutoCommit} = 1;
80

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

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

            
87
L<DBIx::Custom>は、
88
C<insert()>、C<update()>、C<delete()>、C<select()>
89
のようなシュガーメソッドを持っています。
90
小さなことを行うのであれば、SQL文を
91
作成する必要はありません。
92

            
93
=head3 C<insert()>
94

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

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

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

            
102
    my $sth = $dbh->prepare('insert into (title, author) values (?, ?);');
103
    $sth->execute('Perl', 'Ken');
104

            
105
=head3 C<update()>
106

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

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

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

            
115
    my $sth = $dbh->prepare(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
116
        'update book set title = ?, author = ? where id = ?;');
added experimental expand me...
yuki-kimoto authored on 2010-10-20
117
    $sth->execute('Perl', 'Ken', 5);
118

            
119
C<update>メソッドは安全のため
120
where句のないSQLを発行することを許可していません。
121
もしすべての行を更新したい場合は
122
C<update_all()>メソッドを使用してください。
123

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

            
127
=head3 C<delete()>
128

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

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

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

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
136
    my $sth = $dbh->prepare('delete from book where id = ?;');
added experimental expand me...
yuki-kimoto authored on 2010-10-20
137
    $sth->execute('Ken');
138

            
139
C<delete>メソッドは安全のため
140
where句のないSQLを発行することを許可していません。
141
もしすべての行を削除したい場合は
142
C<delete_all()>メソッドを使用してください。
143

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

            
146
=head3 C<select()>
147

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

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

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

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
154
    my $sth = $dbh->prepare('select * from book;);
added experimental expand me...
yuki-kimoto authored on 2010-10-20
155
    $sth->execute;
156

            
157
C<select()>メソッドの戻り値はL<DBIx::Custom::Result>
158
オブジェクトです。C<fetch>メソッドを使用して
159
行をフェッチすることができます。
160

            
161
    while (my $row = $result->fetch) {
162
        my $title  = $row->[0];
163
        my $author = $row->[1];
164
    }
165

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

            
168
    my $result = $dbi->select(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
169
        table  => 'book',
added experimental expand me...
yuki-kimoto authored on 2010-10-20
170
        column => [qw/author title/],
171
        where  => {author => 'Ken'}
172
    );
173

            
174
次のL<DBI>の操作と同じです。
175
    
176
    my $sth = $dbh->prepare(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
177
        'select author, title from book where author = ?;');
added experimental expand me...
yuki-kimoto authored on 2010-10-20
178
    $sht->execute('Ken');
179

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

            
182
    my $result = $dbi->select(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
183
        table    => ['book', 'rental'],
184
        column   => ['book.name as book_name']
185
        relation => {'book.id' => 'rental.book_id'}
added experimental expand me...
yuki-kimoto authored on 2010-10-20
186
    );
187

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

            
190
    my $sth = $dbh->prepare(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
191
        'select book.name as book_name from book, rental' .
192
        'where book.id = rental.book_id;');
added experimental expand me...
yuki-kimoto authored on 2010-10-20
193
    $sth->execute;
194

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

            
197
    my $result = $dbi->select(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
198
        table  => 'book',
added experimental expand me...
yuki-kimoto authored on 2010-10-20
199
        where  => {author => 'Ken'},
200
        append => 'order by price limit 5',
201
    );
202

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

            
205
    my $sth = $dbh->prepare(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
206
        'select * book where author = ? order by price limit 5;');
added experimental expand me...
yuki-kimoto authored on 2010-10-20
207
    $sth->execute;
208

            
209
C<append>オプションは、C<insert()>、C<update()>、C<update_all()>
210
C<delete()>、C<select>メソッドで使用することが
211
できます。
212

            
213
この後のフィルタリングの解説で詳しく扱いますが、値をフィルタリングしたい
214
場合はC<filter>オプションを使用することができます。
215

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

            
221
C<filter>オプションは、C<insert()>、C<update()>、C<update_all()>
222
C<delete()>、C<select>メソッドで使用することが
223
できます。
224

            
updated document
yuki-kimoto authored on 2010-10-21
225
C<select()>メソッドのC<where>オプションではハッシュの代わりに
226
タグを利用することもできます。これによって柔軟な
227
条件を指定することができます。
228

            
229
    # Select, more flexible where
230
    my $result = $dbi->select(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
231
        table  => 'book',
updated document
yuki-kimoto authored on 2010-10-21
232
        where  => ['{= author} and {like title}', 
233
                   {author => 'Ken', title => '%Perl%'}]
234
    );
235

            
236
タグについては以降で解説します。
237

            
added experimental expand me...
yuki-kimoto authored on 2010-10-20
238
=head2 3. 行のフェッチ
239

            
240
C<select()>メソッドの戻り値であるL<DBIx::Custom::Result>
241
には行をフェッチするためのさまざまなメソッドが
242
用意されています。
243
(このセクションの解説では「配列」は「配列のリファレンス」を
244
「ハッシュ」は「ハッシュのリファレンス」を意味しますので
245
注意してください。)
246

            
247
=head3 C<fetch>
248

            
249
一行フェッチして配列に格納します。
250

            
251
    while (my $row = $result->fetch) {
252
        my $author = $row->[0];
253
        my $title  = $row->[1];
254
    }
255

            
256
=head3 C<fetch_first>
257

            
258
一行だけフェッチして配列に格納します。
259

            
260
    my $row = $result->fetch_first;
261

            
262
フェッチが終わった後は、ステートメントハンドルからC<finish()>
263
メソッドが呼び出されてそれ以上フェッチできなくなります。
264

            
265
=head3 C<fetch_multi>
266

            
267
複数行をフェッチして配列の配列に格納します。
268

            
269
    while (my $rows = $result->fetch_multi(5)) {
270
        my $first_author  = $rows->[0][0];
271
        my $first_title   = $rows->[0][1];
272
        my $second_author = $rows->[1][0];
273
        my $second_value  = $rows->[1][1];
274
    }
275

            
276
=head3 C<fetch_all>
277

            
278
すべての行をフェッチして配列の配列に格納します。
279

            
280
    my $rows = $result->fetch_all;
281

            
282
=head3 C<fetch_hash>
283

            
284
一行フェッチしてハッシュに格納します。
285

            
286
    while (my $row = $result->fetch_hash) {
287
        my $title  = $row->{title};
288
        my $author = $row->{author};
289
    }
290

            
291
=head3 C<fetch_hash_first>
292

            
293
一行だけフェッチしてハッシュに格納します。
294

            
295
    my $row = $result->fetch_hash_first;
296

            
297
フェッチが終わった後は、ステートメントハンドルからC<finish()>
298
メソッドが呼び出されてそれ以上フェッチできなくなります。
299

            
300
=head3 C<fetch_hash_multi>
301

            
302
複数行をフェッチしてハッシュの配列に格納します。
303

            
304
    while (my $rows = $result->fetch_hash_multi(5)) {
305
        my $first_title   = $rows->[0]{title};
306
        my $first_author  = $rows->[0]{author};
307
        my $second_title  = $rows->[1]{title};
308
        my $second_author = $rows->[1]{author};
309
    }
310

            
311
=head3 C<fetch_all>
312

            
313
すべての行をフェッチしてハッシュの配列に格納します。
314

            
315
    my $rows = $result->fetch_hash_all;
316

            
updated document
yuki-kimoto authored on 2010-10-21
317
L<DBI>のステートメントハンドルに直接アクセスしたい場合は
added experimental expand me...
yuki-kimoto authored on 2010-10-20
318
<sth>を使用します。
319

            
320
    my $sth = $result->sth;
321

            
updated document
yuki-kimoto authored on 2010-10-21
322
=head2 4. ハッシュパラメタバインド
added experimental expand me...
yuki-kimoto authored on 2010-10-20
323

            
updated document
yuki-kimoto authored on 2010-10-21
324
L<DBIx::Custom>はハッシュパラメタバインドを提供します。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
325

            
updated document
yuki-kimoto authored on 2010-10-21
326
まず最初にL<DBI>による通常のパラメタバインドをご覧ください。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
327

            
328
    use DBI;
329
    my $dbh = DBI->connect(...);
330
    my $sth = $dbh->prepare(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
331
        "select * from book where author = ? and title like ?;"
added experimental expand me...
yuki-kimoto authored on 2010-10-20
332
    );
333
    $sth->execute('Ken', '%Perl%');
334

            
updated document
yuki-kimoto authored on 2010-10-21
335
これはデータベースシステムがSQLをキャッシュすることができ、
336
パラメータは自動的にクォートされるので、
337
パフォーマンス面でも、セキュリティ面でも
338
とても良い方法です。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
339

            
updated document
yuki-kimoto authored on 2010-10-21
340

            
341
L<DBIx::Custom>はこれを改善して、ハッシュで
342
パラメタを指定できるようにしました。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
343

            
344
    my $result = $dbi->execute(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
345
        "select * from book where {= author} and {like title};"
added experimental expand me...
yuki-kimoto authored on 2010-10-20
346
        param => {author => 'Ken', title => '%Perl%'}
347
    );
348

            
updated document
yuki-kimoto authored on 2010-10-21
349
C<{= author}>とC<{like title}>はタグと呼ばれます。
350
タグは内部ではプレースホルダを含む文字列に置き換えられます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
351

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
352
    select * from book where {= author} and {like title}
added experimental expand me...
yuki-kimoto authored on 2010-10-20
353

            
updated document
yuki-kimoto authored on 2010-10-21
354
という文は以下のSQLに置き換えられます。
355

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
356
    select * from book where author = ? and title like ?;
updated document
yuki-kimoto authored on 2010-10-21
357

            
358
このようにタグを使ってSQL文を表現するのがL<DBIx::Custom>の
359
特徴です。以下のタグが利用可能です。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
360

            
361
    [TAG]                       [REPLACED]
362
    {? NAME}               ->   ?
363
    {= NAME}               ->   NAME = ?
364
    {<> NAME}              ->   NAME <> ?
365
    
366
    {< NAME}               ->   NAME < ?
367
    {> NAME}               ->   NAME > ?
368
    {>= NAME}              ->   NAME >= ?
369
    {<= NAME}              ->   NAME <= ?
370
    
371
    {like NAME}            ->   NAME like ?
372
    {in NAME COUNT}        ->   NAME in [?, ?, ..]
373
    
374
    {insert_param NAME1 NAME2}   ->   (NAME1, NAME2) values (?, ?)
375
    {update_param NAME1 NAME2}   ->   set NAME1 = ?, NAME2 = ?
376

            
updated document
yuki-kimoto authored on 2010-10-21
377
これらの変換はL<DBIx::Custom::QueryBuilder>によって行われます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
378

            
updated document
yuki-kimoto authored on 2010-10-21
379
C<{>とC<}>は予約語です。これらの文字を使いたい場合は
380
「\」を使ってエスケープする必要があります。
381
'\'はPerlのエスケープ文字なので、
382
エスケープするためには'\\'と書く必要があることに注意
383
してください。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
384

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
385
    'select * from book \\{ something statement \\}'
added experimental expand me...
yuki-kimoto authored on 2010-10-20
386

            
updated document
yuki-kimoto authored on 2010-10-21
387
=head2 5. フィルタリング
388

            
389
=head3 パラメタバインド時のフィルタリング
added experimental expand me...
yuki-kimoto authored on 2010-10-20
390

            
updated document
yuki-kimoto authored on 2010-10-21
391
データベースに登録するデータをフィルタリングしたい場合
392
があります。たとえば、内部文字列で文字列を保持している場合は
393
データベースにデータを登録する前に、バイト文字列に変換する
394
必要があります。L<DBIx::Custom>のフィルタリングシステムは
395
あるデータを他のデータに変換するのを手助けしてくれます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
396

            
updated document
yuki-kimoto authored on 2010-10-21
397
フィルタリングを利用するにはまず、
398
C<register_filter()>メソッドを使用して
399
フィルタを登録しておく必要があります。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
400

            
401
    $dbi->register_filter(
402
        to_upper_case => sub {
403
            my $value = shift;
404
            return uc $value;
405
        }
406
    );
407

            
updated document
yuki-kimoto authored on 2010-10-21
408
デフォルトのフィルタとしてC<encode_utf8>とC<decode_utf8>
409
が登録されています。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
410

            
updated document
yuki-kimoto authored on 2010-10-21
411
登録されているフィルタはC<execute()>メソッドのC<filter>オプション
412
で指定することができます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
413

            
414
    my $result = $dbi->execute(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
415
        "select * from book where {= author} and {like title};"
added experimental expand me...
yuki-kimoto authored on 2010-10-20
416
        param  => {author => 'Ken', title => '%Perl%'},
417
        filter => {author => 'to_upper_case, title => 'encode_utf8'}
418
    );
419

            
updated document
yuki-kimoto authored on 2010-10-21
420
この例ではC<author>の値はバインドされるときに大文字に変換され、
421
C<title>の値はバイト文字列に変換されます。
422

            
423
C<filter>オプションは
424
C<insert()>、C<update()>、 C<update_all()>,
425
C<delete()>、C<select()>
426
メソッドにおいても使用することができます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
427

            
updated document
yuki-kimoto authored on 2010-10-21
428
    # insert() with filter option
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
429
    $dbi->insert(table  => 'book',
added experimental expand me...
yuki-kimoto authored on 2010-10-20
430
                 param  => {title => 'Perl', author => 'Ken'},
431
                 filter => {title => 'encode_utf8'});
432
    
updated document
yuki-kimoto authored on 2010-10-21
433
    # select() with filter option
added experimental expand me...
yuki-kimoto authored on 2010-10-20
434
    my $result = $dbi->select(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
435
        table  => 'book',
added experimental expand me...
yuki-kimoto authored on 2010-10-20
436
        column => [qw/author title/],
437
        where  => {author => 'Ken'},
438
        append => 'order by id limit 1',
439
        filter => {title => 'encode_utf8'}
440
    );
441

            
updated document
yuki-kimoto authored on 2010-10-21
442
C<filter>で指定されたフィルタはそれぞれのパラメータの値に働きますが、
443
すべてのパラメータのためのデフォルトのフィルタを設定することもできます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
444

            
445
    $dbi->default_bind_filter('encode_utf8');
446

            
updated document
yuki-kimoto authored on 2010-10-21
447
C<filter()>オプションで指定されたフィルタは、
448
デフォルトのフィルタを上書きます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
449
    
450
    $dbi->default_bind_filter('encode_utf8');
451
    $dbi->insert(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
452
        table  => 'book',
added experimental expand me...
yuki-kimoto authored on 2010-10-20
453
        param  => {title => 'Perl', author => 'Ken', price => 1000},
454
        filter => {author => 'to_upper_case', price => undef}
455
    );
456

            
updated document
yuki-kimoto authored on 2010-10-21
457
C<title>の値にはデフォルトのフィルタであるC<encode_utf8>が適用され
458
C<author>の値にはC<to_upper_case>が適用されます。
459
C<price>にはundefを設定しているのでフィルタが解除されます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
460

            
check arguments of connect m...
Yuki Kimoto authored on 2010-12-20
461
B<フィルタのサンプル>
462

            
463
MySQL
464

            
465
    # Time::Piece object to DATETIME format
466
    tp_to_datetime => sub {
467
        return shift->strftime('%Y-%m-%d %H:%M:%S');
468
    }
469
    
470
    # Time::Piece object to DATE format
471
    tp_to_date => sub {
472
        return shift->strftime('%Y-%m-%d');
473
    }
474
    
475
    # DATETIME to Time::Piece object
476
    datetime_to_tp => sub {
477
        return Time::Piece->strptime(shift, '%Y-%m-%d %H:%M:%S');
478
    }
479
    
480
    # DATE to Time::Piece object
481
    date_to_tp => sub {
482
        return Time::Piece->strptime(shift, '%Y-%m-%d');
483
    }
484

            
485
SQLite
486
    
487
    # Time::Piece object to DATETIME format
488
    tp_to_datetime => sub {
489
        return shift->strftime('%Y-%m-%d %H:%M:%S');
490
    }
491
    
492
    # Time::Piece object to DATE format
493
    tp_to_date => sub {
494
        return shift->strftime('%Y-%m-%d');
495
    }
496
    
497
    # DATETIME to Time::Piece object
498
    datetime_to_tp => sub {
499
        return Time::Piece->strptime(shift, $FORMATS->{db_datetime});
500
    }
501
    
502
    # DATE to Time::Piece object
503
    date_to_tp => sub {
504
        return Time::Piece->strptime(shift, $FORMATS->{db_date});
505
    }
506

            
updated document
yuki-kimoto authored on 2010-10-21
507
=head3 行のフェッチ時のフィルタリング
added experimental expand me...
yuki-kimoto authored on 2010-10-20
508

            
updated document
yuki-kimoto authored on 2010-10-21
509
行をフェッチするときのフィルタも設定することができます。
510
これはL<DBIx::Custom::Result>クラスのC<filter>メソッドを使って
511
行います。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
512

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
513
    my $result = $dbi->select(table => 'book');
added experimental expand me...
yuki-kimoto authored on 2010-10-20
514
    $result->filter({title => 'decode_utf8', author => 'to_upper_case'});
515

            
updated document
yuki-kimoto authored on 2010-10-21
516
フィルタはそれぞれの列の値に作用しますが、
517
すべての列のためのデフォルのトフィルタを設定することもできます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
518

            
519
    $dbi->default_fetch_filter('decode_utf8');
520

            
updated document
yuki-kimoto authored on 2010-10-21
521
C<filter>メソッドで設定されたフィルタはデフォルトのフィルタを上書きます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
522

            
523
    $dbi->default_fetch_filter('decode_utf8');
524
    my $result = $dbi->select(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
525
        table => 'book',
added experimental expand me...
yuki-kimoto authored on 2010-10-20
526
        columns => ['title', 'author', 'price']
527
    );
528
    $result->filter({author => 'to_upper_case', price => undef});
529

            
updated document
yuki-kimoto authored on 2010-10-21
530
C<title>の値にはデフォルトのフィルタであるC<decode_utf8>が適用され
531
C<author>の値にはC<to_upper_case>が適用されます。
532
C<price>にはundefを設定しているのでフィルタが解除されます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
533

            
updated document
yuki-kimoto authored on 2010-10-21
534
フェッチのためのフィルタにおいて、
535
たとえ、列名が大文字を含む場合であっても
536
列名は小文字であることに注意してください。
537
これはデータベースシステムに依存させないための要件です。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
538

            
updated document
yuki-kimoto authored on 2010-10-21
539
=head2 6. パフォーマンスの改善
added experimental expand me...
yuki-kimoto authored on 2010-10-20
540

            
updated document
yuki-kimoto authored on 2010-10-21
541
=head3 フィルタのチェックを無効にする
added experimental expand me...
yuki-kimoto authored on 2010-10-20
542

            
updated document
yuki-kimoto authored on 2010-10-21
543
フィルタのチェックがデフォルトでは有効になっています。
544
これは正しいフィルタ名が指定されているかどうかをチェック
545
するためのものですが、ときにはパフォーマンスに影響を
546
及ぼす可能性があります。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
547

            
updated document
yuki-kimoto authored on 2010-10-21
548
フィルタのチェックを無効にするにはC<filter_check>
549
に0を設定してください。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
550

            
551
    $dbi->filter_check(0);
552

            
updated document
yuki-kimoto authored on 2010-10-21
553
=head3 シュガーメソッドを使わない
added experimental expand me...
yuki-kimoto authored on 2010-10-20
554

            
updated document
yuki-kimoto authored on 2010-10-21
555
もしC<insert()>メソッドを使用してインサートを実行した場合、
556
必要なパフォーマンスを得られない場合があるかもしれません。
557
C<insert()>メソッドは、SQL文とステートメントハンドルを
558
毎回作成するためすこし遅いです。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
559

            
updated document
yuki-kimoto authored on 2010-10-21
560
そのような場合は、C<create_query()>メソッドによって
561
クエリを用意しておくことができます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
562
    
563
    my $query = $dbi->create_query(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
564
        "insert into book {insert_param title author};"
added experimental expand me...
yuki-kimoto authored on 2010-10-20
565
    );
566

            
updated document
yuki-kimoto authored on 2010-10-21
567
戻り値はL<DBIx::Custom::Query>オブジェクトです。
568
このオブジェクトはSQL文とパラメータバインド時の列名を
569
保持しています。またステートメントハンドルも保持しています。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
570

            
571
    {
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
572
        sql     => 'insert into book (title, author) values (?, ?);',
updated document
yuki-kimoto authored on 2010-10-21
573
        columns => ['title', 'author'],
574
        sth     => $sth
added experimental expand me...
yuki-kimoto authored on 2010-10-20
575
    }
576

            
updated document
yuki-kimoto authored on 2010-10-21
577
クエリオブジェクトを使って繰り返し実行するには次のようにします。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
578
    
579
    my $inputs = [
580
        {title => 'Perl',      author => 'Ken'},
581
        {title => 'Good days', author => 'Mike'}
582
    ];
583
    
584
    foreach my $input (@$inputs) {
585
        $dbi->execute($query, $input);
586
    }
587

            
updated document
yuki-kimoto authored on 2010-10-21
588
C<execute>メソッドの第一引数にクエリオブジェトを渡すことができます。
589
これはC<insert()>メソッドよりも高速です。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
590

            
updated document
yuki-kimoto authored on 2010-10-21
591
=head3 キャッシング
added experimental expand me...
yuki-kimoto authored on 2010-10-20
592

            
updated document
yuki-kimoto authored on 2010-10-21
593
C<execute()>メソッドはデフォルトでSQL文への解析結果をキャッシュします。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
594

            
595
    $dbi->cache(1);
596

            
updated document
yuki-kimoto authored on 2010-10-21
597
キャッシングはメモリ上で行われますが、C<cache_method()>
598
を使って変更することができます。これはキャッシュされるデータの保存と取得
599
のためのメソッドを定義するのに利用されます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
600

            
601
    $dbi->cache_method(sub {
602
        sub {
603
            my $self = shift;
604
            
605
            $self->{_cached} ||= {};
606
            
607
            # Set cache
608
            if (@_ > 1) {
609
                $self->{_cached}{$_[0]} = $_[1] 
610
            }
611
            
612
            # Get cache
613
            else {
614
                return $self->{_cached}{$_[0]}
615
            }
616
        }
617
    });
618

            
updated document
yuki-kimoto authored on 2010-10-21
619
最初の引数はL<DBIx::Custom>です。第二引数は、
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
620
"select * from book where {= title} and {= author};";
updated document
yuki-kimoto authored on 2010-10-21
621
のようなSQL文の源です。
622
第三引数は
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
623
{sql => "select * from book where title = ? and author = ?",
updated document
yuki-kimoto authored on 2010-10-21
624
 columns => ['title', 'author']}
625
のような解析後のデータです。これはハッシュリファレンスである必要
626
があります。
627
もし引数がふたつより大きい場合は、このメソッドはキャッシュを保存
628
するのに利用されます。そうでない場合はキャッシュを取得するのに
629
利用されます。
630

            
631
=head2 7. その他の機能
added experimental expand me...
yuki-kimoto authored on 2010-10-20
632

            
633
=head3 トランザクション
634

            
updated document
yuki-kimoto authored on 2010-10-21
635
トランザクションを便利に利用するために、
636
C<begin_work()>、C<commit()>、C<rollback()>
637
という三つのメソッドが容易されています。
638
これはL<DBI>の同名のメソッドと同じ機能を持ちます。
639

            
640
    $dbi->begin_work;
641
    
642
    eval {
643
        $dbi->update(...);
644
        $dbi->update(...);
645
    };
646
    
647
    if ($@) {
648
        $dbi->rollback;
649
    }
650
    else {
651
        $dbi->commit;
652
    }
added experimental expand me...
yuki-kimoto authored on 2010-10-20
653

            
updated document
yuki-kimoto authored on 2010-10-21
654
=head3 selectメソッドの結果クラスの変更
added experimental expand me...
yuki-kimoto authored on 2010-10-20
655

            
updated document
yuki-kimoto authored on 2010-10-21
656
必要ならばC<select()>メソッドの結果クラスを変更することができます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
657

            
658
    package Your::Result;
659
    use base 'DBIx::Custom::Result';
660
    
661
    sub some_method { ... }
662

            
663
    1;
664
    
665
    package main;
666
    
667
    use Your::Result;
668
    
669
    my $dbi = DBIx::Custom->connect(...);
670
    $dbi->result_class('Your::Result');
671

            
updated document
yuki-kimoto authored on 2010-10-21
672
=head3 L<DBIx::Custom::QueryBuilder>の機能の拡張
added experimental expand me...
yuki-kimoto authored on 2010-10-20
673

            
updated document
yuki-kimoto authored on 2010-10-21
674
新しいタグが欲しい場合はL<DBIx::Custom::QueryBuilder>の機能を拡張
675
することができます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
676

            
677
    my $dbi = DBIx::Custom->connect(...);
678
    $dbi->query_builder->register_tag_processor(
679
        name => sub {
680
           ...
681
        }
682
    );
683

            
updated document
yuki-kimoto authored on 2010-10-21
684
=head3 ヘルパーメソッドの登録
added experimental expand me...
yuki-kimoto authored on 2010-10-20
685

            
updated document
yuki-kimoto authored on 2010-10-21
686
ヘルパーメソッドを登録することができます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
687

            
688
    $dbi->helper(
689
        update_or_insert => sub {
690
            my $self = shift;
691
            # do something
692
        },
693
        find_or_create   => sub {
694
            my $self = shift;
695
            # do something
696
        }
697
    );
698

            
updated document
yuki-kimoto authored on 2010-10-21
699
<helper()>メソッドで登録したメソッドは
700
L<DBIx::Custom>オブジェクトから直接呼び出すことができます。
added experimental expand me...
yuki-kimoto authored on 2010-10-20
701

            
702
    $dbi->update_or_insert;
703
    $dbi->find_or_create;
704

            
updated document
yuki-kimoto authored on 2010-10-21
705
=head3 ユーティリティメソッド(実験的)
706

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

            
710
    my %expanded = $dbi->expand(\%source);
711

            
712
以下のハッシュ
713

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
714
    {book => {title => 'Perl', author => 'Ken'}}
updated document
yuki-kimoto authored on 2010-10-21
715

            
716
は次のように展開されます。
717

            
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
718
    ('book.title' => 'Perl', 'book.author' => 'Ken')
updated document
yuki-kimoto authored on 2010-10-21
719

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

            
722
    my $param = {title => 'Perl', author => '%Ken%'};
723
    $dbi->execute(
remove DBIx::Custom::Model
Yuki Kimoto authored on 2011-01-12
724
        'select * from book where {= book.title} && {like book.author};',
725
        param => {$dbi->expand({book => $param})}
updated document
yuki-kimoto authored on 2010-10-21
726
    );
727

            
added experimental expand me...
yuki-kimoto authored on 2010-10-20
728
=cut