/ 
DBIx-QuickDB-0.000035
River stage zero No dependents
/ DBIx::QuickDB::Driver

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 version_string { ... }
sub socket         { ... }
sub load_sql       { ... }
sub bootstrap      { ... }
sub connect_string { ... }
sub start_command  { ... }
sub shell_command  { ... }

# Implement if necessary
sub write_config { ... }
sub stop_sig { return $SIG }

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.

NOTE: connect will hide all DBI and driver specific environment variables when it establishes a connection. If you want any environment variables to be used you must set them in the $db->env_vars() hashref.

$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.

NOTE: run_command() will clear any DBI and driver specific environment variables before running any commands. If you want any of the vars to be set then you must set them in the $db->env_vars() hashref.

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.

$clone = $db->clone()
$clone = $db->clone(%params)

Create a copy of the database. This database should be identical, except it should not share any state changes moving forward, that means a new copy of all data, etc.

%data = $db->clone_data()

Data to use when cloning

$db->write_config()

no-op on the base class, used in cloning.

$sig = $db->stop_sig()

What signal to send to the database server to stop it. Default: 'TERM'.

$db->DESTROY

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

ENVIRONMENT VARIABLE HANDLING

All DBI and driver specific environment variables will be hidden Whenever a driver uses run_command() or when the connect() method is called. This is to prevent you from accidentally connecting to a real/production database unintentionally.

If there are DBI or driver specific env vars you want to be honored you must add them to the hashref returned by $db->env_vars. Any vars set in the env_vars hashref will be set during connect() and run_command().

ENVIRONMENT VARIABLE METHODS

$hashref = $db->env_vars()

Get the hashref of env vars to set whenever run_command(), connect(), do_in_env(), or mask_env_vars() are called.

You cannot replace te hashref, but you are free to add/remove keys.

@vars = $db->list_env_vars

This will return a list of all DBI and driver-specific environment variables. This is just a list of variable names, not their values.

The base class provides the following list, drivers may add more:

DBI_USER
DBI_PASS
DBI_DSN
$db->do_in_env(sub { ... })

This will execute the provided codeblock with the environment variables masked, and any vars listed in env_vars() will be set. Once the codeblock is complete the old environment vars will be unmaskd, even if an exception is thrown.

NOTE: The return value of the codeblock is ignored.

$old = $db->mask_env_vars
$db->unmask_env_vars($old)

These methods are used to mask/unmask DBI and driver specific environment variables.

The first method will completely clear any DBI/driver environment variables, then apply any variables in the env_vars() hash. The value returned is a hashref needed to unmask/restore the original environment variables later.

The second method will unmask/restore the original environment variables using the hashref returned by the first.

METHODS SUBCLASSES SHOULD PROVIDE

Drivers may override clone() or clone_data() to control cloning.

($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).

$string = Your::Driver::version_string()
$string = Your::Driver::version_string(\%PARAMS)
$string = Your::Driver->version_string()
$string = Your::Driver->version_string(\%PARAMS)
$string = $db->version_string()
$string = $db->version_string(\%PARAMS)

The default implementation returns 'unknown'.

This is complicated because it can be called as a function, a class method, or an object method. It can also optionally be called with a hashref of PARAMS that MAY be later used to construct an instance.

Lets assume your driver uses the start_my_db command to launch a database. Normally you default to the start_my_db found in the $PATH environment variable. Alternatively someone can pass in an alternative path to the binary with the 'launcher' parameter. Here is a good implementation:

use Scalar::Util qw/reftype/;

sub version_string {
    my $binary;

    # Go in reverse order assuming the last param hash provided is most important
    for my $arg (reverse @_) {
        my $type = reftype($arg) or next; # skip if not a ref
        next $type eq 'HASH'; # We have a hashref, possibly blessed

        # If we find a launcher we are done looping, we want to use this binary.
        $binary = $arg->{launcher} and last;
    }

    # If no args provided one to use we fallback to the default from $PATH
    $binary ||= DEFAULT_BINARY;

    # Call the binary with '-V', capturing and returning the output using backticks.
    return `$binary -V`;
}
$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 2020 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/