.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Padre::DB 3pm"
.TH Padre::DB 3pm "2014-09-11" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Padre::DB \- An ORLite\-based ORM Database API
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\s-1TO BE COMPLETED\s0
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements access to the database that Padre is using to
store bits & pieces. It is using \f(CW\*(C`ORLite\*(C'\fR underneath, for an easy table
scheme discovery at runtime. See below to learn about how to update the
database scheme.
.SS "Updating database scheme"
.IX Subsection "Updating database scheme"
The database is created at runtime if it does not exist, but we are
relying on \f(CW\*(C`Padre::DB::Migrate\*(C'\fR. To summarize \f(CW\*(C`Padre::DB::Migrate\*(C'\fR:
.IP "\(bu" 4
We provide scripts to update the database from one revision to
another.
.IP "\(bu" 4
\&\f(CW\*(C`Padre::DB\*(C'\fR calls \f(CW\*(C`Padre::DB::Migrate\*(C'\fR to apply them in order,
starting from the current database revision.
.PP
Therefore, in order to update the database, you need to do the
following:
.IP "\(bu" 4
Create a script \fIshare/timeline/migrate\-$i.pl\fR with \f(CW$i\fR the next
available integer. This script will look like this:
.Sp
.Vb 2
\&        use strict;
\&        use Padre::DB::Migrate::Patch;
\&
\&        # do some stuff on the base
\&        do(<<\*(AqEND_SQL\*(Aq);
\&        <insert your sql statement here>
\&        END_SQL
.Ve
.Sp
Of course, in case of dropping an existing table, you should make sure
that you don't loose data \- that is, your script should migrate existing
data to the new scheme (unless the whole feature is deprecated, of
course).
.IP "\(bu" 4
Update the user_revision in \f(CW\*(C`Padre::DB\*(C'\fR's call to \f(CW\*(C`Padre::DB::Migrate\*(C'\fR to
read the new script number (i.e., the \f(CW$i\fR that you have used to name your
script in the \fItimeline\fR directory).
.Sp
.Vb 5
\&        use Padre::DB::Migrate 0.01 {
\&            [...]
\&                user_revision => <your\-revision\-number>,
\&            [...]
\&        };
.Ve
.IP "\(bu" 4
Once this is done, you can try to load Padre's development and check
whether the table is updated correctly. Once again, check whether data
is correctly migrated from old scheme to new scheme (if applicable).
.Sp
Note that \f(CW\*(C`Padre::DB::Migrate\*(C'\fR is quiet by default. And if your \s-1SQL\s0
statements are buggy, you will not see anything but the database not
being updated. Therefore, to debug what's going on, add the \f(CW\*(C`\-DEBUG\*(C'\fR
flag to \f(CW\*(C`Padre::DB::Migrate\*(C'\fR call (add it as the \fBlast\fR parameter):
.Sp
.Vb 3
\&        use Padre::DB::Migrate 0.01 {
\&            [...]
\&        }, \*(Aq\-DEBUG\*(Aq
.Ve
.PP
Congratulations! The database has been updated, and will be updated
automatically when users will run the new Padre version...
.SS "Accessing and using the database"
.IX Subsection "Accessing and using the database"
Now that the database has been updated, you can start using it. Each new
table will have a \f(CW\*(C`Padre::DB::YourTable\*(C'\fR module created automatically
at runtime by \f(CW\*(C`ORLite\*(C'\fR, providing you with the standard methods
described below (see \s-1METHODS\s0).
.PP
Note: we prefer using underscore for table names instead of camel case.
\&\f(CW\*(C`ORLite\*(C'\fR is smart enough to convert underscore names to camel case
module names.
.PP
But what if you want to provide some particular methods? For example,
one can imagine that if you create a table \f(CW\*(C`accessed_files\*(C'\fR retaining
the path and the opening timestamp, you want to create a method
\&\f(CW\*(C`most_recent()\*(C'\fR that will return the last opened file.
.PP
In that case, that's quite easy, too:
.IP "\(bu" 4
Create a standard \f(CW\*(C`Padre::DB::YourTable\*(C'\fR module where you will put your
method. Note that all standard methods described above will \fBstill\fR be
available.
.IP "\(bu" 4
Don't forget to \f(CW\*(C`use Padre::DB::YourTable\*(C'\fR in \f(CW\*(C`Padre::DB\*(C'\fR, so that
other Padre modules will get access to all db tables by just using
\&\f(CW\*(C`Padre::DB\*(C'\fR.
.SH "METHODS"
.IX Header "METHODS"
Those methods are automatically created for each of the tables (see
above). Note that the modules automatically created provide both class
methods and instance methods, where the object instances each represent
a table record.
.SS "dsn"
.IX Subsection "dsn"
.Vb 1
\&  my $string = Padre::DB\->dsn;
.Ve
.PP
The \f(CW\*(C`dsn\*(C'\fR accessor returns the \s-1DBI\s0 connection string used to connect
to the SQLite database as a string.
.SS "dbh"
.IX Subsection "dbh"
.Vb 1
\&  my $handle = Padre::DB\->dbh;
.Ve
.PP
To reliably prevent potential SQLite deadlocks resulting from multiple
connections in a single process, each ORLite package will only ever
maintain a single connection to the database.
.PP
During a transaction, this will be the same (cached) database handle.
.PP
Although in most situations you should not need a direct \s-1DBI\s0 connection
handle, the \f(CW\*(C`dbh\*(C'\fR method provides a method for getting a direct
connection in a way that is compatible with connection management in
ORLite.
.PP
Please note that these connections should be short-lived, you should
never hold onto a connection beyond your immediate scope.
.PP
The transaction system in ORLite is specifically designed so that code
using the database should never have to know whether or not it is in a
transation.
.PP
Because of this, you should \fBnever\fR call the \->disconnect method
on the database handles yourself, as the handle may be that of a
currently running transaction.
.PP
Further, you should do your own transaction management on a handle
provided by the <dbh> method.
.PP
In cases where there are extreme needs, and you \fBabsolutely\fR have to
violate these connection handling rules, you should create your own
completely manual \s-1DBI\-\s0>connect call to the database, using the connect
string provided by the \f(CW\*(C`dsn\*(C'\fR method.
.PP
The \f(CW\*(C`dbh\*(C'\fR method returns a DBI::db object, or throws an exception on
error.
.SS "begin"
.IX Subsection "begin"
.Vb 1
\&  Padre::DB\->begin;
.Ve
.PP
The \f(CW\*(C`begin\*(C'\fR method indicates the start of a transaction.
.PP
In the same way that ORLite allows only a single connection, likewise
it allows only a single application-wide transaction.
.PP
No indication is given as to whether you are currently in a transaction
or not, all code should be written neutrally so that it works either way
or doesn't need to care.
.PP
Returns true or throws an exception on error.
.SS "commit"
.IX Subsection "commit"
.Vb 1
\&  Padre::DB\->commit;
.Ve
.PP
The \f(CW\*(C`commit\*(C'\fR method commits the current transaction. If called outside
of a current transaction, it is accepted and treated as a null operation.
.PP
Once the commit has been completed, the database connection falls back
into auto-commit state. If you wish to immediately start another
transaction, you will need to issue a separate \->begin call.
.PP
Returns true or throws an exception on error.
.SS "rollback"
.IX Subsection "rollback"
The \f(CW\*(C`rollback\*(C'\fR method rolls back the current transaction. If called outside
of a current transaction, it is accepted and treated as a null operation.
.PP
Once the rollback has been completed, the database connection falls back
into auto-commit state. If you wish to immediately start another
transaction, you will need to issue a separate \->begin call.
.PP
If a transaction exists at END-time as the process exits, it will be
automatically rolled back.
.PP
Returns true or throws an exception on error.
.SS "do"
.IX Subsection "do"
.Vb 5
\&  Padre::DB\->do(
\&      \*(Aqinsert into table ( foo, bar ) values ( ?, ? )\*(Aq, {},
\&      \e$foo_value,
\&      \e$bar_value,
\&  );
.Ve
.PP
The \f(CW\*(C`do\*(C'\fR method is a direct wrapper around the equivalent \s-1DBI\s0 method,
but applied to the appropriate locally-provided connection or transaction.
.PP
It takes the same parameters and has the same return values and error
behaviour.
.SS "selectall_arrayref"
.IX Subsection "selectall_arrayref"
The \f(CW\*(C`selectall_arrayref\*(C'\fR method is a direct wrapper around the equivalent
\&\s-1DBI\s0 method, but applied to the appropriate locally-provided connection
or transaction.
.PP
It takes the same parameters and has the same return values and error
behaviour.
.SS "selectall_hashref"
.IX Subsection "selectall_hashref"
The \f(CW\*(C`selectall_hashref\*(C'\fR method is a direct wrapper around the equivalent
\&\s-1DBI\s0 method, but applied to the appropriate locally-provided connection
or transaction.
.PP
It takes the same parameters and has the same return values and error
behaviour.
.SS "selectcol_arrayref"
.IX Subsection "selectcol_arrayref"
The \f(CW\*(C`selectcol_arrayref\*(C'\fR method is a direct wrapper around the equivalent
\&\s-1DBI\s0 method, but applied to the appropriate locally-provided connection
or transaction.
.PP
It takes the same parameters and has the same return values and error
behaviour.
.SS "selectrow_array"
.IX Subsection "selectrow_array"
The \f(CW\*(C`selectrow_array\*(C'\fR method is a direct wrapper around the equivalent
\&\s-1DBI\s0 method, but applied to the appropriate locally-provided connection
or transaction.
.PP
It takes the same parameters and has the same return values and error
behaviour.
.SS "selectrow_arrayref"
.IX Subsection "selectrow_arrayref"
The \f(CW\*(C`selectrow_arrayref\*(C'\fR method is a direct wrapper around the equivalent
\&\s-1DBI\s0 method, but applied to the appropriate locally-provided connection
or transaction.
.PP
It takes the same parameters and has the same return values and error
behaviour.
.SS "selectrow_hashref"
.IX Subsection "selectrow_hashref"
The \f(CW\*(C`selectrow_hashref\*(C'\fR method is a direct wrapper around the equivalent
\&\s-1DBI\s0 method, but applied to the appropriate locally-provided connection
or transaction.
.PP
It takes the same parameters and has the same return values and error
behaviour.
.SS "prepare"
.IX Subsection "prepare"
The \f(CW\*(C`prepare\*(C'\fR method is a direct wrapper around the equivalent
\&\s-1DBI\s0 method, but applied to the appropriate locally-provided connection
or transaction
.PP
It takes the same parameters and has the same return values and error
behaviour.
.PP
In general though, you should try to avoid the use of your own prepared
statements if possible, although this is only a recommendation and by
no means prohibited.
.SS "pragma"
.IX Subsection "pragma"
.Vb 2
\&  # Get the user_version for the schema
\&  my $version = Padre::DB\->pragma(\*(Aquser_version\*(Aq);
.Ve
.PP
The \f(CW\*(C`pragma\*(C'\fR method provides a convenient method for fetching a pragma
for a database. See the SQLite documentation for more details.
.SH "SUPPORT"
.IX Header "SUPPORT"
\&\fBPadre::DB\fR is based on ORLite.
.PP
Documentation created by ORLite::Pod 0.10.
.PP
For general support please see the support section of the main
project documentation.
.SH "AUTHOR"
.IX Header "AUTHOR"
Adam Kennedy <adamk@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2013 The Padre development team as listed in Padre.pm.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.