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 = Foo::Bar->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 = Foo::Bar->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 ORLite's connection
123 management.
124 Please note that these connections should be short-lived, you should
126 never hold onto a connection beyond the 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 transaction.
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
142 connect 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 Foo::Bar->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 Foo::Bar->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 Foo::Bar->do('insert into table (foo, bar) values (?, ?)', {},
190 $foo_value,
191 $bar_value,
192 );
193 The "do" method is a direct wrapper around the equivalent DBI method,
195 but applied to the appropriate locally-provided connection or
196 transaction.
197 It takes the same parameters and has the same return values and error
199 behaviour.
200 "selectall_arrayref"
202 The "selectall_arrayref" method is a direct wrapper around the
203 equivalent DBI method, but applied to the appropriate locally-provided
204 connection or transaction.
205 It takes the same parameters and has the same return values and error
207 behaviour.
208 "selectall_hashref"
210 The "selectall_hashref" method is a direct wrapper around the
211 equivalent DBI method, but applied to the appropriate locally-provided
212 connection or transaction.
213 It takes the same parameters and has the same return values and error
215 behaviour.
216 "selectcol_arrayref"
218 The "selectcol_arrayref" method is a direct wrapper around the
219 equivalent DBI method, but applied to the appropriate locally-provided
220 connection or transaction.
221 It takes the same parameters and has the same return values and error
223 behaviour.
224 "selectrow_array"
226 The "selectrow_array" method is a direct wrapper around the equivalent
227 DBI method, but applied to the appropriate locally-provided connection
228 or transaction.
229 It takes the same parameters and has the same return values and error
231 behaviour.
232 "selectrow_arrayref"
234 The "selectrow_arrayref" method is a direct wrapper around the
235 equivalent DBI method, but applied to the appropriate locally-provided
236 connection or transaction.
237 It takes the same parameters and has the same return values and error
239 behaviour.
240 "selectrow_hashref"
242 The "selectrow_hashref" method is a direct wrapper around the
243 equivalent DBI method, but applied to the appropriate locally-provided
244 connection or transaction.
245 It takes the same parameters and has the same return values and error
247 behaviour.
248 "prepare"
250 The "prepare" method is a direct wrapper around the equivalent DBI
251 method, but applied to the appropriate locally-provided connection or
252 transaction
253 It takes the same parameters and has the same return values and error
255 behaviour.
256 In general though, you should try to avoid the use of your own prepared
258 statements if possible, although this is only a recommendation and by
259 no means prohibited.
260 "pragma"
262 # Get the user_version for the schema
263 my $version = Foo::Bar->pragma('user_version');
264 The "pragma" method provides a convenient method for fetching a pragma
266 for a database. See the SQLite documentation for more details.
267
269 Padre::DB is based on ORLite 1.18.
270 Documentation created by ORLite::Pod 0.06.
272 For general support please see the support section of the main project
274 documentation.
275
277 Copyright 2008-2010 The Padre development team as listed in Padre.pm.
278 This program is free software; you can redistribute it and/or modify it
280 under the same terms as Perl itself.
281 The full text of the license can be found in the LICENSE file included
283 with this module.
284perl v5.12.1 2010-06-11 Padre::DB(3)