1Padre::DB(3) User Contributed Perl Documentation Padre::DB(3)
2
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 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 • We provide scripts to update the database from one revision to
22 another.
23 • "Padre::DB" calls "Padre::DB::Migrate" to apply them in order,
25 starting from the current database revision.
26 Therefore, in order to update the database, you need to do the
28 following:
29 • Create a script share/timeline/migrate-$i.pl with $i the next
31 available integer. This script will look like this:
32 use strict;
34 use Padre::DB::Migrate::Patch;
35 # do some stuff on the base
37 do(<<'END_SQL');
38 <insert your sql statement here>
39 END_SQL
40 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 • 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 use Padre::DB::Migrate 0.01 {
51 [...]
52 user_revision => <your-revision-number>,
53 [...]
54 };
55 • 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 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 use Padre::DB::Migrate 0.01 {
68 [...]
69 }, '-DEBUG'
70 Congratulations! The database has been updated, and will be updated
72 automatically when users will run the new Padre version...
73 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 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 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 In that case, that's quite easy, too:
90 • 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 • 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 dsn
106 my $string = Padre::DB->dsn;
107 The "dsn" accessor returns the DBI connection string used to connect to
109 the SQLite database as a string.
110 dbh
112 my $handle = Padre::DB->dbh;
113 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 During a transaction, this will be the same (cached) database handle.
119 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 Please note that these connections should be short-lived, you should
126 never hold onto a connection beyond your immediate scope.
127 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 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 Further, you should do your own transaction management on a handle
137 provided by the <dbh> method.
138 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 The "dbh" method returns a DBI::db object, or throws an exception on
145 error.
146 begin
148 Padre::DB->begin;
149 The "begin" method indicates the start of a transaction.
151 In the same way that ORLite allows only a single connection, likewise
153 it allows only a single application-wide transaction.
154 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 Returns true or throws an exception on error.
160 commit
162 Padre::DB->commit;
163 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 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 Returns true or throws an exception on error.
173 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 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 If a transaction exists at END-time as the process exits, it will be
184 automatically rolled back.
185 Returns true or throws an exception on error.
187 do
189 Padre::DB->do(
190 'insert into table ( foo, bar ) values ( ?, ? )', {},
191 \$foo_value,
192 \$bar_value,
193 );
194 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 It takes the same parameters and has the same return values and error
200 behaviour.
201 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 It takes the same parameters and has the same return values and error
208 behaviour.
209 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 It takes the same parameters and has the same return values and error
216 behaviour.
217 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 It takes the same parameters and has the same return values and error
224 behaviour.
225 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 It takes the same parameters and has the same return values and error
232 behaviour.
233 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 It takes the same parameters and has the same return values and error
240 behaviour.
241 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 It takes the same parameters and has the same return values and error
248 behaviour.
249 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 It takes the same parameters and has the same return values and error
256 behaviour.
257 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 pragma
263 # Get the user_version for the schema
264 my $version = Padre::DB->pragma('user_version');
265 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 Documentation created by ORLite::Pod 0.10.
273 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 This program is free software; you can redistribute it and/or modify it
284 under the same terms as Perl itself.
285 The full text of the license can be found in the LICENSE file included
287 with this module.
288perl v5.32.1 2021-01-27 Padre::DB(3)