-
-
09 Nov 2013 05:08:58 UTC
- Distribution: Padre
- Module version: 1.00
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Clone repository
- Issues
- Testers (31 / 43 / 71)
- Kwalitee
Bus factor: 3- % Coverage
- License: perl_5
- Perl: v5.11.0
- Activity
24 month- Tools
- Download (1.88MB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 46 contributors- Gabor Szabo
- Aaron Trevena (TEEJAY)
-
Adam Kennedy (ADAMK)
- Ahmad Zawawi أحمد محمد زواوي (AZAWAWI)
- Andrew Shitov
- Alexandr Ciornii (CHORNY)
- Amir E. Aharoni - אמיר א. אהרוני
- Blake Willmarth (BLAKEW)
-
BlueT - Matthew Lien - 練喆明 (BLUET)
- Breno G. de Oliveira (GARU)
- Brian Cassidy (BRICAS)
-
Burak Gürsoy (BURAK)
-
Cezary Morga (THEREK)
- Chris Dolan (CHRISDOLAN)
-
Claudio Ramirez (NXADM)
- Dirk De Nijs (ddn123456)
- Enrique Nell (ENELL)
-
Fayland Lam (FAYLAND)
- Gabriel Vieira (GABRIELMAD)
-
Gábor Szabó - גאבור סבו (SZABGAB)
- György Pásztor (GYU)
-
Heiko Jansen (HJANSEN)
-
Jérôme Quelin (JQUELIN)
-
Kaare Rasmussen (KAARE)
- Keedi Kim - 김도형 (KEEDI)
-
Kenichi Ishigaki - 石垣憲一 (ISHIGAKI)
-
Kevin Dawson (BOWTIE)
- Kjetil Skotheim (KJETIL)
- Marcela Mašláňová (mmaslano)
-
Marek Roszkowski (EviL)
-
Mark Grimes
- Max Maischein (CORION)
- Olivier MenguE<eacute> (DOLMEN)
- Omer Zak - עומר זק
- Paco Alguacil (PacoLinux)
-
Patrick Donelan (PDONELAN)
- Paweł Murias (PMURIAS)
- Petar Shangov (PSHANGOV)
- Peter Lavender (PLAVEN)
-
Ryan Niebur (RSN)
- Sebastian Willing (SEWI)
- Shlomi Fish - שלומי פיש (SHLOMIF)
- Simone Blandino (SBLANDIN)
-
Steffen Müller (TSEE)
- Zeno Gantner (ZENOG)
- Chuanren Wu
- Dependencies
- Algorithm::Diff
- App::cpanminus
- B::Deparse
- CGI
- Capture::Tiny
- Class::Adapter
- Class::Inspector
- Class::XSAccessor
- Cwd
- DBD::SQLite
- DBI
- Data::Dumper
- Debug::Client
- Devel::Dumpvar
- Devel::Refactor
- Encode
- ExtUtils::MakeMaker
- ExtUtils::Manifest
- File::Basename
- File::Copy::Recursive
- File::Find::Rule
- File::Glob
- File::HomeDir
- File::Path
- File::Remove
- File::ShareDir
- File::Spec
- File::Spec::Functions
- File::Temp
- File::Which
- File::pushd
- FindBin
- Getopt::Long
- HTML::Entities
- HTML::Parser
- IO::Scalar
- IO::Socket
- IO::String
- IPC::Open2
- IPC::Open3
- IPC::Run
- JSON::XS
- LWP
- LWP::UserAgent
- List::MoreUtils
- List::Util
- Module::Build
- Module::CoreList
- Module::Manifest
- Module::Starter
- ORLite
- ORLite::Migrate
- POD2::Base
- POSIX
- PPI
- PPIx::EditorTools
- PPIx::Regexp
- Params::Util
- Parse::ErrorString::Perl
- Parse::ExuberantCTags
- Pod::Abstract
- Pod::Functions
- Pod::POM
- Pod::Perldoc
- Pod::Simple
- Pod::Simple::XHTML
- Probe::Perl
- Sort::Versions
- Storable
- Template::Tiny
- Term::ReadLine
- Text::Balanced
- Text::Diff
- Text::FindIndent
- Text::Patch
- Time::HiRes
- URI
- Wx
- Wx::Perl::ProcessStream
- Wx::Scintilla
- YAML::Tiny
- threads
- threads::shared
- version
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
Padre::DB - An ORLite-based ORM Database API
SYNOPSIS
TO BE COMPLETED
DESCRIPTION
This module implements access to the database that Padre is using to store bits & pieces. It is using
ORLite
underneath, for an easy table scheme discovery at runtime. See below to learn about how to update the database scheme.Updating database scheme
The database is created at runtime if it does not exist, but we are relying on
Padre::DB::Migrate
. To summarizePadre::DB::Migrate
:We provide scripts to update the database from one revision to another.
Padre::DB
callsPadre::DB::Migrate
to apply them in order, starting from the current database revision.
Therefore, in order to update the database, you need to do the following:
Create a script share/timeline/migrate-$i.pl with
$i
the next available integer. This script will look like this:use strict; use Padre::DB::Migrate::Patch; # do some stuff on the base do(<<'END_SQL'); <insert your sql statement here> END_SQL
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).
Update the user_revision in
Padre::DB
's call toPadre::DB::Migrate
to read the new script number (i.e., the$i
that you have used to name your script in the timeline directory).use Padre::DB::Migrate 0.01 { [...] user_revision => <your-revision-number>, [...] };
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).
Note that
Padre::DB::Migrate
is quiet by default. And if your SQL statements are buggy, you will not see anything but the database not being updated. Therefore, to debug what's going on, add the-DEBUG
flag toPadre::DB::Migrate
call (add it as the last parameter):use Padre::DB::Migrate 0.01 { [...] }, '-DEBUG'
Congratulations! The database has been updated, and will be updated automatically when users will run the new Padre version...
Accessing and using the database
Now that the database has been updated, you can start using it. Each new table will have a
Padre::DB::YourTable
module created automatically at runtime byORLite
, providing you with the standard methods described below (see METHODS).Note: we prefer using underscore for table names instead of camel case.
ORLite
is smart enough to convert underscore names to camel case module names.But what if you want to provide some particular methods? For example, one can imagine that if you create a table
accessed_files
retaining the path and the opening timestamp, you want to create a methodmost_recent()
that will return the last opened file.In that case, that's quite easy, too:
Create a standard
Padre::DB::YourTable
module where you will put your method. Note that all standard methods described above will still be available.Don't forget to
use Padre::DB::YourTable
inPadre::DB
, so that other Padre modules will get access to all db tables by just usingPadre::DB
.
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.
dsn
my $string = Padre::DB->dsn;
The
dsn
accessor returns the DBI connection string used to connect to the SQLite database as a string.dbh
my $handle = Padre::DB->dbh;
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.
During a transaction, this will be the same (cached) database handle.
Although in most situations you should not need a direct DBI connection handle, the
dbh
method provides a method for getting a direct connection in a way that is compatible with connection management in ORLite.Please note that these connections should be short-lived, you should never hold onto a connection beyond your immediate scope.
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.
Because of this, you should never call the ->disconnect method on the database handles yourself, as the handle may be that of a currently running transaction.
Further, you should do your own transaction management on a handle provided by the <dbh> method.
In cases where there are extreme needs, and you absolutely have to violate these connection handling rules, you should create your own completely manual DBI->connect call to the database, using the connect string provided by the
dsn
method.The
dbh
method returns a DBI::db object, or throws an exception on error.begin
Padre::DB->begin;
The
begin
method indicates the start of a transaction.In the same way that ORLite allows only a single connection, likewise it allows only a single application-wide transaction.
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.
Returns true or throws an exception on error.
commit
Padre::DB->commit;
The
commit
method commits the current transaction. If called outside of a current transaction, it is accepted and treated as a null operation.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.
Returns true or throws an exception on error.
rollback
The
rollback
method rolls back the current transaction. If called outside of a current transaction, it is accepted and treated as a null operation.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.
If a transaction exists at END-time as the process exits, it will be automatically rolled back.
Returns true or throws an exception on error.
do
Padre::DB->do( 'insert into table ( foo, bar ) values ( ?, ? )', {}, \$foo_value, \$bar_value, );
The
do
method is a direct wrapper around the equivalent DBI method, but applied to the appropriate locally-provided connection or transaction.It takes the same parameters and has the same return values and error behaviour.
selectall_arrayref
The
selectall_arrayref
method is a direct wrapper around the equivalent DBI method, but applied to the appropriate locally-provided connection or transaction.It takes the same parameters and has the same return values and error behaviour.
selectall_hashref
The
selectall_hashref
method is a direct wrapper around the equivalent DBI method, but applied to the appropriate locally-provided connection or transaction.It takes the same parameters and has the same return values and error behaviour.
selectcol_arrayref
The
selectcol_arrayref
method is a direct wrapper around the equivalent DBI method, but applied to the appropriate locally-provided connection or transaction.It takes the same parameters and has the same return values and error behaviour.
selectrow_array
The
selectrow_array
method is a direct wrapper around the equivalent DBI method, but applied to the appropriate locally-provided connection or transaction.It takes the same parameters and has the same return values and error behaviour.
selectrow_arrayref
The
selectrow_arrayref
method is a direct wrapper around the equivalent DBI method, but applied to the appropriate locally-provided connection or transaction.It takes the same parameters and has the same return values and error behaviour.
selectrow_hashref
The
selectrow_hashref
method is a direct wrapper around the equivalent DBI method, but applied to the appropriate locally-provided connection or transaction.It takes the same parameters and has the same return values and error behaviour.
prepare
The
prepare
method is a direct wrapper around the equivalent DBI method, but applied to the appropriate locally-provided connection or transactionIt takes the same parameters and has the same return values and error behaviour.
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.
pragma
# Get the user_version for the schema my $version = Padre::DB->pragma('user_version');
The
pragma
method provides a convenient method for fetching a pragma for a database. See the SQLite documentation for more details.SUPPORT
Padre::DB is based on ORLite.
Documentation created by ORLite::Pod 0.10.
For general support please see the support section of the main project documentation.
AUTHOR
Adam Kennedy <adamk@cpan.org>
COPYRIGHT
Copyright 2008-2013 The Padre development team as listed in Padre.pm.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
Module Install Instructions
To install Padre, copy and paste the appropriate command in to your terminal.
cpanm Padre
perl -MCPAN -e shell install Padre
For more information on module installation, please visit the detailed CPAN module installation guide.