NAME

DESCRIPTION

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:

$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

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

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

$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

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

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/