1Padre::DB(3)          User Contributed Perl Documentation         Padre::DB(3)
2
3
4

NAME

6       Padre::DB - An ORLite-based ORM Database API
7

SYNOPSIS

9       TO BE COMPLETED
10

DESCRIPTION

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

METHODS

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

SUPPORT

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

AUTHOR

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.32.1                      2021-01-27                      Padre::DB(3)
Impressum