Footprintless::Database::AbstractProvider

- NAME
- VERSION
- SYNOPSIS
- DESCRIPTION
  - query
  - row_handler
  - row_mapper
- ENTITIES
- CONSTRUCTORS
  - new($entity, $coordinate, %options)
- METHODS
  - backup($to, [%options])
  - begin_transaction()
  - client([%options])
  - commit_transaction()
  - connect()
  - disconnect()
  - execute($query)
  - get_schema()
  - query($query, $row_handler)
  - query_for_list($query, [$row_mapper])
  - query_for_map($query, $row_mapper)
  - query_for_scalar($query, $row_mapper)
  - restore($from, %options)
  - rollback_transaction()
- AUTHOR
- COPYRIGHT AND LICENSE
- SEE ALSO

# NAME

Footprintless::Database::AbstractProvider - A base class for database providers

# VERSION

version 0.01

# SYNOPSIS

        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');

# DESCRIPTION

Provides a base class implementing the common abstractions. Other providers should extend this class and override methods as desired.

There are a few core concepts used for the execute, and query methods. They are

### query

A string containing a sql statement, or a hashref with a required `sql` entry containing the sql statement and an optional `parameters` entry contianing a list of values for the placeholders of the prepared statement. For example:

        {
            sql => 'select name, phone from employees where dept = ? and title = ?',
            parameters => [$dept, $title]
        }

### row_handler

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.

### row_mapper

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 collected by the `query_for_xxx` method according to that methods behavior.

# ENTITIES

A simple deployment:

        db => {
            provider => 'mysql',
            schema => 'my_table',
            port => 3306,
            username => $properties->{db.username},
            pasword => $properties->{db.password}
        }

A more complex situation, perhaps tunneling over ssh to your prod database:

        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'
        }

# CONSTRUCTORS

## new($entity, $coordinate, %options)

Constructs a new database provider instance. Should be called on a subclass. Subclasses should NOT override this method, rather, override `_init`. See Footprintless::MixableBase for details.

# METHODS

## backup($to, [%options])

Will backup the database to `$to`. The allowed values for `$to` are:

- Another instance of the same provider to pipe to the `restore` method - A callback method to call with each chunk of the backup - A `GLOB` to write to - A filename to write to

The options are determined by the implementation.

## begin_transaction()

Begins a transaction.

## client([%options])

Will open an interactive client connected to the database.

## commit_transaction()

Commits the current transaction.

## connect()

Opens a connection to the database.

## disconnect()

Closes the current connection to the database.

## execute($query)

Executes `$query` and returns the number of rows effected.

## get_schema()

Returns the configured schema name.

## query($query, $row_handler)

Executes `$query` and calls `$row_handler` once for each row. Does not return anything.

## query_for_list($query, [$row_mapper])

Executes `$query` and calls `$row_mapper` once for each row. `$row_mapper` 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 `$row_mapper` is not supplied, each rows values will be returned as an arrayref.

## query_for_map($query, $row_mapper)

Executes `$query` and calls `$row_mapper` once for each row. `$row_mapper` 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 `$row_mapper` 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.

## query_for_scalar($query, $row_mapper)

Executes `$query` and calls `$row_mapper` once for the first row of the result set. `$row_mapper` is expected to return a scalar representing the row. If `$row_mapper` is not supplied, the first value from the first row is returned. This can be useful for queries like `select count(*) from foo`.

## restore($from, %options)

Will restore the database from `$from`. The allowed values for `$from` are:

- Another instance of the same provider to pipe from the `backup` method - A hashref containing a `command` key whose value is a command to pipe input from - A `GLOB` to read from - A filename to read from

The options are determined by the implementation.

## rollback_transaction()

Rolls back the current transaction.

# AUTHOR

Lucas Theisen <lucastheisen@pastdev.com>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Lucas Theisen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

# SEE ALSO

Please see those modules/websites for more information related to this module.

- Footprintless::Database::DatabasePlugin
- DBI
- Footprintless
- Footprintless::MixableBase
- Footprintless::Database::DatabasePlugin
- Footprintless::Database::CsvProvider
- Footprintless::Database::MySqlProvider
- Footprintless::Database::PostgreSqlProvider