NAME

DBIx::QuickDB::Driver - Base class for DBIx::QuickDB drivers.

DESCRIPTION

Base class for DBIx::QuickDB drivers.

SYNOPSIS

package DBIx::QuickDB::Driver::MyDriver;
use strict;
use warnings;

use parent 'DBIx::QuickDB::Driver';

use DBIx::QuickDB::Util::HashBase qw{ ... };

sub viable { ... ? 1 : (0, "This driver will not work because ...") }

sub init {
    my $self = shift;

    $self->SUPER::init();

    ...
}

# Methods most drivers should implement

sub socket         { ... }
sub load_sql       { ... }
sub bootstrap      { ... }
sub connect_string { ... }
sub start_command  { ... }
sub shell_command  { ... }

1;

METHODS PROVIDED HERE

$bool = $db->autostart

True if this db was created with 'autostart' requested.

$bool = $db->autostop

True if this db was created with 'autostop' requested.

$db->cleanup

This will completely delete the database directory. BE CAREFUL.

$dbh = $db->connect()

$dbh = $db->connect($db_name)

$dbh = $db->connect($db_name, %connect_params)

Connect to the database server. If no %connect_params are specified then (AutoCommit => 1) will be used.

Behavior for an undef (or omitted) $db_name is driver specific.

This will use the username in username() and the password in password(). The connection string is defined by connect_string() which must be overriden in each driver subclass.

$path = $db->dir

Get the path to the database directory.

$db->init

This is called automatically during object construction. You SHOULD NOT call this directly, except in a subclass which overrides init().

$path = $db->log_file

If the database is running this will point to the log file. If the database is not yet running, or has been stopped, this will be undef.

$driver_name = $db->name

Get the short name of the driver ('DBIx::QuickDB::Driver::' has been stripped).

$pw = $db->password

$db->password($pw)

Get/Set the password to use when calling connect().

$pid = $db->pid

$db->pid($pid)

If the server is running then this will have the pid. If the server is stopped this will be undef.

NOTE: This will also be undef if the server is running independantly of this object, if the server is running, but this is undef, it means another object/process is in control of it.

$pid = $db->root_pid

This should contain the original pid of the process in which the instance was created.

$db->run_command(\@cmd)

$db->run_command(\@cmd, \%params)

($pid, $logfile) = $db->run_command(\@cmd, {no_wait => 1})

This will execute the command specified in @cmd. If the command fails an exception will be thrown. By default all output will be captured into log files and ignored. If the command fails the output will be attached to the exception. Normally this will block until the command exits. if verbose() is set then all output is always shown.

Normally there is no return value. If the 'no_wait' param is specified then the command will be run non-blocking and the pid and log file will be returned.

Allowed params:

no_log => bool

Show the output in realtime, do not redirect it.

no_wait => bool

Do not block, instead return the pid and log file to use later.

stdin => path_to_file

Run the command with the specified file is input.

$db->shell

Launch a database shell. This depends on the shell_command method, which drivers should provide. Not all driver may support this.

$bool = $db->should_cleanup

True if the instance was created with the 'cleanup' specification. If this is true then the database directory will be deleted when the program ends.

$db->start

Start the database. Most drivers will make this a no-op if the db is already running.

$db->stop

Stop the database. Most drivers will make this a no-op if the db is already stopped.

$user = $db->username

$db->username($user)

Get/set the username to use in connect().

$bool = $db->verbose

$db->verbose($bool)

If this is true then all output from run_command will be shown at all times.

$db->DESTROY

Used to stop the server and delete the data dir (if desired) when the program exits.

METHODS SUBCLASSES SHOULD PROVIDE

($bool, $why) = $db->viable()

($bool, $why) = $db->viable(\%spec)

This should check if it is possible to launch this db type on the current system with the given spec.

See "SPEC HASH" in DBIx::QuickDB for what might be in %spec.

The first return value is a simple boolean, true if the driver is viable, false if it is not. The second value should be an explanation as to why the driver is not viable (in cases where it is not).

$socket = $db->socket()

Unix Socket used to communicate with the db. If the db type does not use sockets (such as SQLite) then this can be skipped. NOTE: If you skip this you will need to override stop() and start() to account for it. See DBIx::QuickDB::Driver::SQLite for an example.

$db->load_sql($db_name, $file)

Load the specified sql file into the specified db. It is possible that $db_name will be undef in some drivers.

$db->bootstrap()

Initialize the database server and create the 'quickdb' database.

$string = $db->connect_string()

$string $db->connect_string($db_name)

String to pass into DBI->connect.

Example: "dbi:Pg:dbname=$db_name;host=$socket"

@cmd = $db->start_command()

Command used to start the server.

@cmd = $db->shell_command()

Command used to launch a shell into the database.

SOURCE

The source code repository for DBIx-QuickDB can be found at https://github.com/exodist/DBIx-QuickDB/.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright 2018 Chad Granum <exodist7@gmail.com>.

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

See http://dev.perl.org/licenses/