1Padre::DB(3) User Contributed Perl Documentation Padre::DB(3)
2
3
4
6 Padre::DB - An ORLite-based ORM Database API
7
9 TO BE COMPLETED
10
12 This module implements access to the database that Padre is using to
13 store bits & pieces. It is using "ORLite" underneath, for an easy table
14 scheme discovery at runtime. See below to learn about how to update the
15 database scheme.
16
17 Updating database scheme
18 The database is created at runtime if it does not exist, but we are
19 relying on "Padre::DB::Migrate". To summarize "Padre::DB::Migrate":
20
21 · We provide scripts to update the database from one revision to
22 another.
23
24 · "Padre::DB" calls "Padre::DB::Migrate" to apply them in order,
25 starting from the current database revision.
26
27 Therefore, in order to update the database, you need to do the
28 following:
29
30 · Create a script share/timeline/migrate-$i.pl with $i the next
31 available integer. This script will look like this:
32
33 use strict;
34 use Padre::DB::Migrate::Patch;
35
36 # do some stuff on the base
37 do(<<'END_SQL');
38 <insert your sql statement here>
39 END_SQL
40
41 Of course, in case of dropping an existing table, you should make
42 sure that you don't loose data - that is, your script should
43 migrate existing data to the new scheme (unless the whole feature
44 is deprecated, of course).
45
46 · Update the user_revision in "Padre::DB"'s call to
47 "Padre::DB::Migrate" to read the new script number (i.e., the $i
48 that you have used to name your script in the timeline directory).
49
50 use Padre::DB::Migrate 0.01 {
51 [...]
52 user_revision => <your-revision-number>,
53 [...]
54 };
55
56 · Once this is done, you can try to load Padre's development and
57 check whether the table is updated correctly. Once again, check
58 whether data is correctly migrated from old scheme to new scheme
59 (if applicable).
60
61 Note that "Padre::DB::Migrate" is quiet by default. And if your SQL
62 statements are buggy, you will not see anything but the database
63 not being updated. Therefore, to debug what's going on, add the
64 "-DEBUG" flag to "Padre::DB::Migrate" call (add it as the last
65 parameter):
66
67 use Padre::DB::Migrate 0.01 {
68 [...]
69 }, '-DEBUG'
70
71 Congratulations! The database has been updated, and will be updated
72 automatically when users will run the new Padre version...
73
74 Accessing and using the database
75 Now that the database has been updated, you can start using it. Each
76 new table will have a "Padre::DB::YourTable" module created
77 automatically at runtime by "ORLite", providing you with the standard
78 methods described below (see METHODS).
79
80 Note: we prefer using underscore for table names instead of camel case.
81 "ORLite" is smart enough to convert underscore names to camel case
82 module names.
83
84 But what if you want to provide some particular methods? For example,
85 one can imagine that if you create a table "accessed_files" retaining
86 the path and the opening timestamp, you want to create a method
87 "most_recent()" that will return the last opened file.
88
89 In that case, that's quite easy, too:
90
91 · Create a standard "Padre::DB::YourTable" module where you will put
92 your method. Note that all standard methods described above will
93 still be available.
94
95 · Don't forget to "use Padre::DB::YourTable" in "Padre::DB", so that
96 other Padre modules will get access to all db tables by just using
97 "Padre::DB".
98
100 Those methods are automatically created for each of the tables (see
101 above). Note that the modules automatically created provide both class
102 methods and instance methods, where the object instances each represent
103 a table record.
104
105 dsn
106 my $string = Padre::DB->dsn;
107
108 The "dsn" accessor returns the DBI connection string used to connect to
109 the SQLite database as a string.
110
111 dbh
112 my $handle = Padre::DB->dbh;
113
114 To reliably prevent potential SQLite deadlocks resulting from multiple
115 connections in a single process, each ORLite package will only ever
116 maintain a single connection to the database.
117
118 During a transaction, this will be the same (cached) database handle.
119
120 Although in most situations you should not need a direct DBI connection
121 handle, the "dbh" method provides a method for getting a direct
122 connection in a way that is compatible with connection management in
123 ORLite.
124
125 Please note that these connections should be short-lived, you should
126 never hold onto a connection beyond your immediate scope.
127
128 The transaction system in ORLite is specifically designed so that code
129 using the database should never have to know whether or not it is in a
130 transation.
131
132 Because of this, you should never call the ->disconnect method on the
133 database handles yourself, as the handle may be that of a currently
134 running transaction.
135
136 Further, you should do your own transaction management on a handle
137 provided by the <dbh> method.
138
139 In cases where there are extreme needs, and you absolutely have to
140 violate these connection handling rules, you should create your own
141 completely manual DBI->connect call to the database, using the connect
142 string provided by the "dsn" method.
143
144 The "dbh" method returns a DBI::db object, or throws an exception on
145 error.
146
147 begin
148 Padre::DB->begin;
149
150 The "begin" method indicates the start of a transaction.
151
152 In the same way that ORLite allows only a single connection, likewise
153 it allows only a single application-wide transaction.
154
155 No indication is given as to whether you are currently in a transaction
156 or not, all code should be written neutrally so that it works either
157 way or doesn't need to care.
158
159 Returns true or throws an exception on error.
160
161 commit
162 Padre::DB->commit;
163
164 The "commit" method commits the current transaction. If called outside
165 of a current transaction, it is accepted and treated as a null
166 operation.
167
168 Once the commit has been completed, the database connection falls back
169 into auto-commit state. If you wish to immediately start another
170 transaction, you will need to issue a separate ->begin call.
171
172 Returns true or throws an exception on error.
173
174 rollback
175 The "rollback" method rolls back the current transaction. If called
176 outside of a current transaction, it is accepted and treated as a null
177 operation.
178
179 Once the rollback has been completed, the database connection falls
180 back into auto-commit state. If you wish to immediately start another
181 transaction, you will need to issue a separate ->begin call.
182
183 If a transaction exists at END-time as the process exits, it will be
184 automatically rolled back.
185
186 Returns true or throws an exception on error.
187
188 do
189 Padre::DB->do(
190 'insert into table ( foo, bar ) values ( ?, ? )', {},
191 \$foo_value,
192 \$bar_value,
193 );
194
195 The "do" method is a direct wrapper around the equivalent DBI method,
196 but applied to the appropriate locally-provided connection or
197 transaction.
198
199 It takes the same parameters and has the same return values and error
200 behaviour.
201
202 selectall_arrayref
203 The "selectall_arrayref" method is a direct wrapper around the
204 equivalent DBI method, but applied to the appropriate locally-provided
205 connection or transaction.
206
207 It takes the same parameters and has the same return values and error
208 behaviour.
209
210 selectall_hashref
211 The "selectall_hashref" method is a direct wrapper around the
212 equivalent DBI method, but applied to the appropriate locally-provided
213 connection or transaction.
214
215 It takes the same parameters and has the same return values and error
216 behaviour.
217
218 selectcol_arrayref
219 The "selectcol_arrayref" method is a direct wrapper around the
220 equivalent DBI method, but applied to the appropriate locally-provided
221 connection or transaction.
222
223 It takes the same parameters and has the same return values and error
224 behaviour.
225
226 selectrow_array
227 The "selectrow_array" method is a direct wrapper around the equivalent
228 DBI method, but applied to the appropriate locally-provided connection
229 or transaction.
230
231 It takes the same parameters and has the same return values and error
232 behaviour.
233
234 selectrow_arrayref
235 The "selectrow_arrayref" method is a direct wrapper around the
236 equivalent DBI method, but applied to the appropriate locally-provided
237 connection or transaction.
238
239 It takes the same parameters and has the same return values and error
240 behaviour.
241
242 selectrow_hashref
243 The "selectrow_hashref" method is a direct wrapper around the
244 equivalent DBI method, but applied to the appropriate locally-provided
245 connection or transaction.
246
247 It takes the same parameters and has the same return values and error
248 behaviour.
249
250 prepare
251 The "prepare" method is a direct wrapper around the equivalent DBI
252 method, but applied to the appropriate locally-provided connection or
253 transaction
254
255 It takes the same parameters and has the same return values and error
256 behaviour.
257
258 In general though, you should try to avoid the use of your own prepared
259 statements if possible, although this is only a recommendation and by
260 no means prohibited.
261
262 pragma
263 # Get the user_version for the schema
264 my $version = Padre::DB->pragma('user_version');
265
266 The "pragma" method provides a convenient method for fetching a pragma
267 for a database. See the SQLite documentation for more details.
268
270 Padre::DB is based on ORLite.
271
272 Documentation created by ORLite::Pod 0.10.
273
274 For general support please see the support section of the main project
275 documentation.
276
278 Adam Kennedy <adamk@cpan.org>
279
281 Copyright 2008-2011 The Padre development team as listed in Padre.pm.
282
283 This program is free software; you can redistribute it and/or modify it
284 under the same terms as Perl itself.
285
286 The full text of the license can be found in the LICENSE file included
287 with this module.
288
289
290
291perl v5.28.0 2011-08-16 Padre::DB(3)