Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 233 lines (164 sloc) 8.715 kb
0dfcc3e @kawanet first drop
authored
1 NAME
5a8820c @kawanet pod updated
authored
2 SQL::Pico - Prebuilt Raw SQL Statement Builder
0dfcc3e @kawanet first drop
authored
3
4 SYNOPSIS
690f4dd @kawanet bind() supports multiple statements
authored
5 use SQL::Pico ();
6
0dfcc3e @kawanet first drop
authored
7 $dbh = DBI->connect(...);
5a8820c @kawanet pod updated
authored
8 $sp = SQL::Pico->new->dbh($dbh);
9 $quoted = $sp->quote($val); # $dbh->quote($val)
10 $quoted = $sp->quote_identifier($key); # $dbh->quote_identifier($key)
0dfcc3e @kawanet first drop
authored
11
5a8820c @kawanet pod updated
authored
12 $select = $sp->bind("SELECT * FROM ?? WHERE id = ?", $table, $id);
3280aa2 @kawanet synpsis simplified
authored
13
5a8820c @kawanet pod updated
authored
14 $where = join(" AND " => $sp->bind("?? = ?", %hash));
15 $select = $sp->bind("SELECT * FROM mytbl WHERE ???", $where);
690f4dd @kawanet bind() supports multiple statements
authored
16
5a8820c @kawanet pod updated
authored
17 $keys = join(", " => $sp->quote_identifier(keys %hash));
18 $vals = join(", " => $sp->quote(values %hash));
19 $insert = $sp->bind("INSERT INTO mytbl (???) VALUES (???)", $keys, $vals);
690f4dd @kawanet bind() supports multiple statements
authored
20
5a8820c @kawanet pod updated
authored
21 $sets = join(", " => $sp->bind("?? = ?", %hash));
22 $update = $sp->bind("UPDATE mytbl SET ??? WHERE id = ?", $sets, $id);
690f4dd @kawanet bind() supports multiple statements
authored
23
5a8820c @kawanet pod updated
authored
24 $in = join(", " => $sp->quote(@list));
25 $delete = $sp->bind("DELETE mytbl WHERE id IN (???)", $in);
0dfcc3e @kawanet first drop
authored
26
27 DESCRIPTION
5a8820c @kawanet pod updated
authored
28 This provides a simple but safe way to build raw SQL statements without
29 learning any other languages than Perl and SQL. "SQL::Pico" is
30 lightweight and doesn't require any non-core modules except for DBI.
690f4dd @kawanet bind() supports multiple statements
authored
31
5a8820c @kawanet pod updated
authored
32 "SQL::Pico"'s "bind()" method generates a SQL statement which
33 placeholders are filled with immediate values bound. This makes you free
34 from handling bind values and calling "prepare()". See "RECIPES" section
35 below.
36
37 Why "Prebuilt" SQL?
38 Because SQL is the most simplest language to comunicate with RDBMS.
39
40 The most of ORM modules and something *SQL::Builder*-ish modules would
41 have required you to understand its complex class structure or dialectal
42 DSL.
43
44 This module simply provides just one of new method, "bind()", which
45 allows you to build SQL statements using placeholders, as well as
46 "quote()" and "quote_identifier()" methods which are wrappers for
47 "DBI"'s methods with the same name you already know.
48
49 The most of modern Web applications would not cache prepared $sth
50 instances though they would cache a connected $dbh instance. It means
51 you don't need to worry about its performance (dis)advantage when you
52 don't use bind values at "execute()".
0dfcc3e @kawanet first drop
authored
53
54 METHODS
55 new(PARAMETERS)
690f4dd @kawanet bind() supports multiple statements
authored
56 This creates a "SQL::Pico" instance.
0dfcc3e @kawanet first drop
authored
57
5a8820c @kawanet pod updated
authored
58 $sp = SQL::Pico->new;
0dfcc3e @kawanet first drop
authored
59
60 This accepts key/value pair(s) as its initial parameters. Only "dbh"
61 parameter is available at this module.
62
5a8820c @kawanet pod updated
authored
63 $sp = SQL::Pico->new(dbh => $dbh);
0dfcc3e @kawanet first drop
authored
64
65 dbh(DBHANDLE)
5a8820c @kawanet pod updated
authored
66 This is an accessor to specify a "DBI" instance.
0dfcc3e @kawanet first drop
authored
67
5a8820c @kawanet pod updated
authored
68 $sp = SQL::Pico->new;
69 $sp->dbh($dbh);
0dfcc3e @kawanet first drop
authored
70
71 The setter returns the current "SQL::Pico" instance for you to chain
72 method calls.
73
74 $quoted = SQL::Pico->new->dbh($dbh)->quote($val);
75
5a8820c @kawanet pod updated
authored
76 Please note that quoting formats for literals and identifiers depend on
77 RDBMS server you connect. For example, a literal string "Don't" would be
78 quoted as 'Don''t' in a server, as well as 'Don\'t', "Don't", etc. in
79 others.
80
81 This supports SQL-92 Standard's quoting format, per default, under
82 DBD::NullP driver which is included in "DBI" distribution. You could
83 specify a "DBI" instance to make string quoted properly for your RDBMS
84 server.
690f4dd @kawanet bind() supports multiple statements
authored
85
0dfcc3e @kawanet first drop
authored
86 quote(LITERAL)
690f4dd @kawanet bind() supports multiple statements
authored
87 This calls "DBI"'s "quote()" method internally.
0dfcc3e @kawanet first drop
authored
88
5a8820c @kawanet pod updated
authored
89 $quoted = $sp->quote($val); # $dbh->quote($val)
0dfcc3e @kawanet first drop
authored
90
91 This doesn't accept literal's data type specified at its second
92 argument. The other difference to original is that this accept multiple
93 arguments and returns them quoted.
94
5a8820c @kawanet pod updated
authored
95 @list = $sp->quote(@vals); # multiple quotes at once
690f4dd @kawanet bind() supports multiple statements
authored
96
0dfcc3e @kawanet first drop
authored
97 quote_identifier(IDENTIFIER)
690f4dd @kawanet bind() supports multiple statements
authored
98 This calls "DBI"'s "quote_identifier()" method internally.
0dfcc3e @kawanet first drop
authored
99
5a8820c @kawanet pod updated
authored
100 $quoted = $sp->quote_identifier($key); # $dbh->quote_identifier($key)
0dfcc3e @kawanet first drop
authored
101
102 Multiple arguments are allowed as well.
103
5a8820c @kawanet pod updated
authored
104 @list = $sp->quote_identifier(@keys); # multiple quotes at once
690f4dd @kawanet bind() supports multiple statements
authored
105
0dfcc3e @kawanet first drop
authored
106 bind(SQL, VALUES...)
690f4dd @kawanet bind() supports multiple statements
authored
107 This builds a SQL statement by using placeholders with bind values.
0dfcc3e @kawanet first drop
authored
108
5a8820c @kawanet pod updated
authored
109 $sql = $sp->bind("SELECT * FROM ?? WHERE id = ?", $table, $id);
0dfcc3e @kawanet first drop
authored
110
5a8820c @kawanet pod updated
authored
111 Note that this returns a SQL statement built with values bound at the
690f4dd @kawanet bind() supports multiple statements
authored
112 method prior to "DBI"'s <execute()> method called.
113
114 Three types of placeholders are allowed at the first argument:
115
116 Single character of "?" represents a placeholder for a literal which
117 will be escaped by "quote()".
118
119 Double characters of "??" represents a placeholder for an identifier
120 which will be escaped by "quote_identifier()".
121
122 Triple characters of "???" represents a placeholder for a raw SQL string
123 which will not be escaped.
124
5a8820c @kawanet pod updated
authored
125 $hash = {"category" => "foo", "price" => "100"};
126 @list = $sp->bind("?? = ?", %$hash);
690f4dd @kawanet bind() supports multiple statements
authored
127 $where = join(" AND ", @list);
128 $select = "SELECT * FROM mytable WHERE $where";
129
5a8820c @kawanet pod updated
authored
130 # SELECT * FROM mytable WHERE "category" = 'foo' AND "price" = '100'
131 # Note that the order of key/value pairs vary.
0dfcc3e @kawanet first drop
authored
132
5a8820c @kawanet pod updated
authored
133 In list context, this returns a list of strings repeatedly built with
134 parameters following.
0dfcc3e @kawanet first drop
authored
135
136 FUNCTIONS
137 In addition to the OO style described above, this also supports the
5a8820c @kawanet pod updated
authored
138 functional style below by exporting three shortcut functions: "v()",
139 "k()" and "sql()" per default.
0dfcc3e @kawanet first drop
authored
140
690f4dd @kawanet bind() supports multiple statements
authored
141 use SQL::Pico; # functions exported
142
0dfcc3e @kawanet first drop
authored
143 v(LITERAL)
144 This is a shortcut for "quote()" method which quotes a literal, e.g.
145 string, number, etc.
146
147 $quoted = v("string"); # quotes literal
5a8820c @kawanet pod updated
authored
148 @quoted = v("foo", "bar", "100"); # multiple literals
0dfcc3e @kawanet first drop
authored
149
150 k(IDENTIFIER)
151 This is a shortcut for "quote_identifier()" method which quotes an
152 identifier, e.g. table name, column name, etc.
153
154 $quoted = k("table_name"); # quotes identifier
5a8820c @kawanet pod updated
authored
155 @quoted = k("category", "name", "price"); # multiple identifiers
0dfcc3e @kawanet first drop
authored
156
157 sql(SQL, VALUES...)
158 This is a shortcut for "bind()" method which builds a SQL statement by
159 using placeholders with bind values.
160
5a8820c @kawanet pod updated
authored
161 $select = sql("SELECT * FROM ?? WHERE id = ?", $table, $id);
0dfcc3e @kawanet first drop
authored
162
690f4dd @kawanet bind() supports multiple statements
authored
163 dbh(DBHANDLE)
5a8820c @kawanet pod updated
authored
164 Call "dbh()" class method to specify the database handle for those
165 "v()", "k()" and "sql()" functions above.
0dfcc3e @kawanet first drop
authored
166
167 $dbh = DBI->connect(...);
168 SQL::Pico->dbh($dbh);
169
690f4dd @kawanet bind() supports multiple statements
authored
170 Note that "dbh()" method is not exported.
171
5a8820c @kawanet pod updated
authored
172 RECIPES
173 The recipes show which "DBI" methods would follow SQL statements built
174 by "sql()" function.
175
176 # fetch a single record as a hahsref
177 $sql = sql("SELECT * FROM mytable WHERE id = ?", $id);
178 $hash = $dbh->selectrow_hashref($sql);
179
180 # fetch multiple records as an arrayref of hashrefs
181 $in = join(", " => v(@list));
182 $sql = sql("SELECT * FROM mytable WHERE id IN (???)", $in);
183 $array = $dbh->selectall_arrayref($sql, {Slice=>{}});
184
185 # fetch a list of a single column as an arrayref
186 $sql = sql("SELECT id FROM mytable WHERE price < ?", $price);
187 $array = $dbh->selectcol_arrayref($sql);
188
189 # fetch a list of a pair column as an arrayref then a hashref
190 $sql = sql("SELECT id, name FROM mytable WHERE price < ?", $price);
191 $array = $dbh->selectall_arrayref($sql);
192 $hash = +{ map { $_->[0] => $_->[1] } @$array };
193
194 # check a record exists as a scalar
195 $sql = sql("SELECT count(*) FROM mytable WHERE id = ?", $id);
196 $exist = $dbh->selectrow_array($sql);
197
198 # count total number of records as a scalar
199 $sql = sql("SELECT count(*) FROM mytable WHERE price < ?", $price);
200 $count = $dbh->selectrow_array($sql);
201
202 # insert a record with a hashref
203 $keys = join(", " => k(keys %$hash));
204 $vals = join(", " => v(values %$hash));
205 $sql = sql("INSERT INTO mytable (???) VALUES (???)", $keys, $vals);
206 $dbh->do($sql) or die "insert failed";
207
208 # update a record with a hashref
209 $sets = join(", " => sql("?? = ?", %$hash));
210 $sql = sql("UPDATE mytable SET ??? WHERE id = ?", $sets, $id);
211 $dbh->do($sql) or die "update failed";
212
213 # delete a record
214 $sql = sql("DELETE mytable WHERE id = ?", $id);
215 $dbh->do($sql) or die "delete failed";
216
0dfcc3e @kawanet first drop
authored
217 AUTHOR
218 Yusuke Kawasaki http://www.kawa.net/
219
220 COPYRIGHT
221 The following copyright notice applies to all the files provided in this
222 distribution, including binary files, unless explicitly noted otherwise.
223
224 Copyright 2012 Yusuke Kawasaki
225
226 LICENSE
227 This library is free software; you can redistribute it and/or modify it
228 under the same terms as Perl itself.
229
690f4dd @kawanet bind() supports multiple statements
authored
230 SEE ALSO
231 DBI executes SQL statements built by the module.
232
Something went wrong with that request. Please try again.