<html><head><title>Footprintless::Plugin::Database::AbstractProvider</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
BODY {
background: white;
color: black;
font-family: arial,sans-serif;
margin: 0;
padding: 1ex;
}
A:link, A:visited {
background: transparent;
color: #006699;
}
A[href="#POD_ERRORS"] {
background: transparent;
color: #FF0000;
}
DIV {
border-width: 0;
}
DT {
margin-top: 1em;
margin-left: 1em;
}
.pod { margin-right: 20ex; }
.pod PRE {
background: #eeeeee;
border: 1px solid #888888;
color: black;
padding: 1em;
white-space: pre;
}
.pod H1 {
background: transparent;
color: #006699;
font-size: large;
}
.pod H1 A { text-decoration: none; }
.pod H2 A { text-decoration: none; }
.pod H3 A { text-decoration: none; }
.pod H4 A { text-decoration: none; }
.pod H2 {
background: transparent;
color: #006699;
font-size: medium;
}
.pod H3 {
background: transparent;
color: #006699;
font-size: medium;
font-style: italic;
}
.pod H4 {
background: transparent;
color: #006699;
font-size: medium;
font-weight: normal;
}
.pod IMG {
vertical-align: top;
}
.pod .toc A {
text-decoration: none;
}
.pod .toc LI {
line-height: 1.2em;
list-style-type: none;
}
/*]]>*/-->
</style>
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.32,
using Pod::Simple::PullParser v3.32,
under Perl v5.025000 at Thu Jan 11 14:46:34 2018 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<div class='indexgroup'>
<ul class='indexList indexList1'>
<li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
<li class='indexItem indexItem1'><a href='#VERSION'>VERSION</a>
<li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
<li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
<ul class='indexList indexList2'>
<ul class='indexList indexList3'>
<li class='indexItem indexItem3'><a href='#query'>query</a>
<li class='indexItem indexItem3'><a href='#row_handler'>row_handler</a>
<li class='indexItem indexItem3'><a href='#row_mapper'>row_mapper</a>
</ul>
</ul>
<li class='indexItem indexItem1'><a href='#ENTITIES'>ENTITIES</a>
<li class='indexItem indexItem1'><a href='#CONSTRUCTORS'>CONSTRUCTORS</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#new(%24entity%2C_%24coordinate%2C_%25options)'>new($entity, $coordinate, %options)</a>
</ul>
<li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#backup(%24to%2C_%5B%25options%5D)'>backup($to, [%options])</a>
<li class='indexItem indexItem2'><a href='#begin_transaction()'>begin_transaction()</a>
<li class='indexItem indexItem2'><a href='#client(%5B%25options%5D)'>client([%options])</a>
<li class='indexItem indexItem2'><a href='#commit_transaction()'>commit_transaction()</a>
<li class='indexItem indexItem2'><a href='#connect()'>connect()</a>
<li class='indexItem indexItem2'><a href='#disconnect()'>disconnect()</a>
<li class='indexItem indexItem2'><a href='#execute(%24query)'>execute($query)</a>
<li class='indexItem indexItem2'><a href='#get_schema()'>get_schema()</a>
<li class='indexItem indexItem2'><a href='#query(%24query%2C_%24row_handler%2C_%25options)'>query($query, $row_handler, %options)</a>
<li class='indexItem indexItem2'><a href='#query_for_list(%24query%2C_%5B%24row_mapper%2C%5D_%25options)'>query_for_list($query, [$row_mapper,] %options)</a>
<li class='indexItem indexItem2'><a href='#query_for_map(%24query%2C_%5B%24row_mapper%2C%5D_%25options)'>query_for_map($query, [$row_mapper,] %options)</a>
<li class='indexItem indexItem2'><a href='#query_for_scalar(%24query%2C_%24row_mapper)'>query_for_scalar($query, $row_mapper)</a>
<li class='indexItem indexItem2'><a href='#restore(%24from%2C_%25options)'>restore($from, %options)</a>
<li class='indexItem indexItem2'><a href='#rollback_transaction()'>rollback_transaction()</a>
</ul>
<li class='indexItem indexItem1'><a href='#AUTHOR'>AUTHOR</a>
<li class='indexItem indexItem1'><a href='#COPYRIGHT_AND_LICENSE'>COPYRIGHT AND LICENSE</a>
<li class='indexItem indexItem1'><a href='#SEE_ALSO'>SEE ALSO</a>
</ul>
</div>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>Footprintless::Plugin::Database::AbstractProvider - A base class for database providers</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="VERSION"
>VERSION</a></h1>
<p>version 1.04</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> my $db = $footprintless->db('dev.db');
$db->execute('create table foo ( id int, name varchar(16) )');
my $rows_inserted = $db->execute(
q[
insert into foo (id, name) values
(1, 'foo'),
(2, 'bar')
]);
my $name_of_1 = $db->query_for_scalar(
{
sql => 'select id, name from foo where id = ?',
parameters => [1]
},
sub {
my ($id, $name) = @_;
return $name;
});
my $rows_count = $db->query_for_scalar('select count(*) from foo');</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>Provides a base class implementing the common abstractions. Other providers should extend this class and override methods as desired.</p>
<p>There are a few core concepts used for the execute, and query methods. They are</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="query"
>query</a></h3>
<p>A string containing a sql statement, or a hashref with a required <code>sql</code> entry containing the sql statement and an optional <code>parameters</code> entry contianing a list of values for the placeholders of the prepared statement. For example:</p>
<pre> {
sql => 'select name, phone from employees where dept = ? and title = ?',
parameters => [$dept, $title]
}</pre>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="row_handler"
>row_handler</a></h3>
<p>A callback that will be called once for each row. It will be passed the list of values requested in the query. This callback does not return anything.</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="row_mapper"
>row_mapper</a></h3>
<p>A callback that will be called once for each row. It will be passed the list of values requested in the query. It must return a value that will be <i>collected</i> by the <code>query_for_xxx</code> method according to that methods behavior.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="ENTITIES"
>ENTITIES</a></h1>
<p>A simple deployment:</p>
<pre> db => {
provider => 'mysql',
schema => 'my_table',
port => 3306,
username => $properties->{db.username},
pasword => $properties->{db.password}
}</pre>
<p>A more complex situation, perhaps tunneling over ssh to your prod database:</p>
<pre> db => {
provider => 'postgres',
database => 'my_database',
schema => 'my_table',
hostname => 'my.production.server',
port => 5432,
username => $properties->{db.username},
pasword => $properties->{db.password},
tunnel_hostname => 'my.bastion.host'
}</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="CONSTRUCTORS"
>CONSTRUCTORS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="new($entity,_$coordinate,_%options)"
>new($entity, $coordinate, %options)</a></h2>
<p>Constructs a new database provider instance. Should be called on a subclass. Subclasses should <i>NOT</i> override this method, rather, override <code>_init</code>. See <a href="http://search.cpan.org/perldoc?Footprintless%3A%3AMixableBase" class="podlinkpod"
>Footprintless::MixableBase</a> for details.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS"
>METHODS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="backup($to,_[%options])"
>backup($to, [%options])</a></h2>
<p>Will backup the database to <code>$to</code>. The allowed values for <code>$to</code> are:</p>
<p>- Another instance of the same provider to pipe to the <code>restore</code> method - A callback method to call with each <i>chunk</i> of the backup - A <code>GLOB</code> to write to - A filename to write to</p>
<p>The options are determined by the implementation.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="begin_transaction()"
>begin_transaction()</a></h2>
<p>Begins a transaction.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="client([%options])"
>client([%options])</a></h2>
<p>Will open an interactive client connected to the database.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="commit_transaction()"
>commit_transaction()</a></h2>
<p>Commits the current transaction.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="connect()"
>connect()</a></h2>
<p>Opens a connection to the database.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="disconnect()"
>disconnect()</a></h2>
<p>Closes the current connection to the database.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="execute($query)"
>execute($query)</a></h2>
<p>Executes <code>$query</code> and returns the number of rows effected.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="get_schema()"
>get_schema()</a></h2>
<p>Returns the configured schema name.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="query($query,_$row_handler,_%options)"
>query($query, $row_handler, %options)</a></h2>
<p>Executes <code>$query</code> and calls <code>$row_handler</code> once for each row. Does not return anything. If you do not set the <code>hash</code> option, the <code>$row_handler</code> gets the field data in the <code>@_</code> array (see <code>hash</code> option below).</p>
<p>The following options may be set:</p>
<dl>
<dt><a name="column_info"
><code>column_info</code></a></dt>
<dd>
<p>To get column information, set this option to an array ref - when the query is executed, before the <code>$row_handler</code> is called for the first time, the array will be populated with the column information, the indexed by result column. This array may be empty if the underlying driver does not support column information.</p>
<p>Each item in the array will be a hash containing the following properties if the driver does not support a field it will be missing:</p>
<dl>
<dt><a name="name"
><code>name</code></a></dt>
<dd>
<p>The column name</p>
<dt><a name="type"
><code>type</code></a></dt>
<dd>
<p>The SQL type identified by number - these are supposedly cataloged as part of the ISO/IEC 9075 type registry - but I would not know because this particular spec seems to be a particularly well guarded secret (I could not get it for free on the internet). I suggest looking directly at the <code>type_name</code> and <code>type_info</code> properties instead of worrying about this.</p>
<dt><a name="type_name"
><code>type_name</code></a></dt>
<dd>
<p>The SQL type identified by name.</p>
<dt><a name="type_info"
><code>type_info</code></a></dt>
<dd>
<p>A single <code>type_info</code> hash describing the type for the column as described at http://search.cpan.org/~timb/DBI-1.637/DBI.pm#type_info</p>
<dt><a name="column_size"
><code>column_size</code></a></dt>
<dd>
<p>The precision of the column. For numeric types, this is the number of digits (does not include sign, decimal point, or even exponent digits). For character based types, this is the number of bytes which may or may not correspond to the number of characters.</p>
<dt><a name="scale"
><code>scale</code></a></dt>
<dd>
<p>An integer indicating "scale" or <code>undef</code> for types where scale is not used.</p>
<dt><a name="nullable"
><code>nullable</code></a></dt>
<dd>
<p>Indicates whether or not we can assign this column to null - <code>undef</code> if the nullability is unknown. Otherwise this may be evaluated a boolean.</p>
</dd>
</dl>
<dt><a name="hash"
><code>hash</code></a></dt>
<dd>
<p>Set this to a true value to get the parameters to the <code>$row_handler</code> to be set up suitable for a hash assignment. The actual parameters are an array, but will now come as: column-name-1 => field-1, column-name-2 => field-2...</p>
<dt><a name="no_fetch"
><code>no_fetch</code></a></dt>
<dd>
<p>Set this to a true value to skip the fetching of data from a result set - this is useful for "queries" that have no result set and would throw an exception when we attempt to fetch a row (i.e. <code>ALTER SESSION</code> queries).</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="query_for_list($query,_[$row_mapper,]_%options)"
>query_for_list($query, [$row_mapper,] %options)</a></h2>
<p>Executes <code>$query</code> and calls <code>$row_mapper</code> once for each row. <code>$row_mapper</code> is expected to return a scalar representing the row. All of the returned scalars will be collected into a list and returned. When called in list context, a list is returned. In scalar context, an arrayref is returned. If <code>$row_mapper</code> is not supplied, each rows values will be returned as an arrayref (or as hashref if the <code>hash</code> option is selected). For information about the <code>options</code>, see the <code>query()</code> method - being that they are the same options.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="query_for_map($query,_[$row_mapper,]_%options)"
>query_for_map($query, [$row_mapper,] %options)</a></h2>
<p>Executes <code>$query</code> and calls <code>$row_mapper</code> once for each row. <code>$row_mapper</code> is expected to return a hashref with a single key/value pair. All of the returned hashrefs will be collected into a single hash and returned. When called in list context, a hash is returned. In scalar context, a hashref is returned. If <code>$row_mapper</code> is not supplied, each rows values will be returned as a hashref using the first value as the key, and the whole rows arrayref as the value (or as hashref if the <code>hash</code> option is selected). For information about the <code>options</code>, see the <code>query()</code> method - being that they are the same options..</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="query_for_scalar($query,_$row_mapper)"
>query_for_scalar($query, $row_mapper)</a></h2>
<p>Executes <code>$query</code> and calls <code>$row_mapper</code> once for the first row of the result set. <code>$row_mapper</code> is expected to return a scalar representing the row. If <code>$row_mapper</code> is not supplied, the first value from the first row is returned. This can be useful for queries like <code>select count(*) from foo</code>.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="restore($from,_%options)"
>restore($from, %options)</a></h2>
<p>Will restore the database from <code>$from</code>. The allowed values for <code>$from</code> are:</p>
<p>- Another instance of the same provider to pipe from the <code>backup</code> method - A hashref containing a <code>command</code> key whose value is a command to pipe input from - A <code>GLOB</code> to read from - A filename to read from</p>
<p>The options are determined by the implementation.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="rollback_transaction()"
>rollback_transaction()</a></h2>
<p>Rolls back the current transaction.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Lucas Theisen <lucastheisen@pastdev.com></p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_AND_LICENSE"
>COPYRIGHT AND LICENSE</a></h1>
<p>This software is copyright (c) 2016 by Lucas Theisen.</p>
<p>This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SEE_ALSO"
>SEE ALSO</a></h1>
<p>Please see those modules/websites for more information related to this module.</p>
<ul>
<li><a href="http://search.cpan.org/perldoc?Footprintless%3A%3APlugin%3A%3ADatabase" class="podlinkpod"
>Footprintless::Plugin::Database</a></li>
<li><a href="http://search.cpan.org/perldoc?DBI" class="podlinkpod"
>DBI</a></li>
<li><a href="http://search.cpan.org/perldoc?Footprintless" class="podlinkpod"
>Footprintless</a></li>
<li><a href="http://search.cpan.org/perldoc?Footprintless%3A%3AMixableBase" class="podlinkpod"
>Footprintless::MixableBase</a></li>
<li><a href="http://search.cpan.org/perldoc?Footprintless%3A%3APlugin%3A%3ADatabase" class="podlinkpod"
>Footprintless::Plugin::Database</a></li>
<li><a href="http://search.cpan.org/perldoc?Footprintless%3A%3APlugin%3A%3ADatabase%3A%3ACsvProvider" class="podlinkpod"
>Footprintless::Plugin::Database::CsvProvider</a></li>
<li><a href="http://search.cpan.org/perldoc?Footprintless%3A%3APlugin%3A%3ADatabase%3A%3AMySqlProvider" class="podlinkpod"
>Footprintless::Plugin::Database::MySqlProvider</a></li>
<li><a href="http://search.cpan.org/perldoc?Footprintless%3A%3APlugin%3A%3ADatabase%3A%3APostgreSqlProvider" class="podlinkpod"
>Footprintless::Plugin::Database::PostgreSqlProvider</a></li>
</ul>
<!-- end doc -->
</body></html>