view release on metacpan or  search on metacpan

lib/FusqlFS/Backend/Base.pm  view on Meta::CPAN

Input: %options.
Output: $backend_base_instance.

This method does a lot of initialization work, including DBI connection
initialization and setup of different inner variables, data representation
layer setup etc., so do not override and redefine it unless you really know
what you are doing. And if you really need to override it, consider calling it
with C<$class-E<gt>SUPER::new(...)> at some point to avoid unnecessary work.

If you need to do some initialization work, consider overriding L</init> method
which is created to be overridden and redefined.

=cut
sub new
{
    return $FusqlFS::Artifact::instance if $FusqlFS::Artifact::instance;

    my $class = shift;
    my %options = @_;
    my $dsn = 'DBI:'.$class->dsn(@options{qw(host port database)});
    my $debug = $options{debug}||0;
    my $fnsep = $options{fnsep}||'.';
    my $format = $options{format}||'';

    $Carp::Verbose = $debug > 3;
    my $self = {
        subpackages => {},
        limit       => 0 + ($options{limit}||0),
        charset     => $options{charset}||'',
        fnsep       => $fnsep,
        fnsplit     => qr/[$fnsep]/,
        connect     => sub () {
                           DBI->connect($dsn, @options{qw(user password)},
                           {
                               PrintError  => $debug > 0,
                               PrintWarn   => $debug > 1,
                               ShowErrorStatement => $debug > 2,
                               HandleError => sub { carp(shift); },
                           }) or die "Failed to connect to $dsn: $DBI::err $DBI::state $DBI::errstr";
                       },
    };
    $self->{dbh} = $self->{connect}();

    ($self->{dumper}, $self->{loader}) = FusqlFS::Formatter->init($format);
    $self->{namemap} = $options{namemap};

    bless $self, $class;

    $FusqlFS::Artifact::instance = $self;
    $self->init();
    return $self;
}

=item connect, disconnect, reconnect

These methods can be used to control database connection in runtime.
Please use them instead of direct DBH object access via $fusqlh->{dbh},
as they make some more work, than simple database {dis,re}connection.

They use credentials, provided on first backend object initialization
with L</new> method above, so no parameters are required.

C<connect> establish new database connection and reinitializes backend.
Backend reinitialization is required, because some backends make some
query preparation, linked to current database connection.

C<disconnect> drops database connection, and C<reconnect> drops database
connection is it's active (checked with L<DBI::ping> method) and
then establish connection anew. This method is used in C<HUP>
signal handler to reset database connection.

=cut
sub connect
{
    my $self = shift;
    $self->{dbh} = $self->{connect}();
    $self->init();
}

sub disconnect
{
    $_[0]->{dbh}->disconnect();
}

sub reconnect
{
    my $self = shift;
    $self->disconnect() if $self->{dbh}->ping();
    $self->connect();
}

=item by_path

Returns L<FusqlFS::Entry> entry by path.

Input: $path, $leaf_absent=undef.
Output: $entry_instance.

See L<FusqlFS::Entry> for detailed description. This method is just a
convenient way of constructing C<FusqlFS::Entry>'s instance as you don't need
to pass first C<$fs> argument to it.

=cut
sub by_path
{
    return FusqlFS::Entry->new(@_);
}

=item dsn

Compose DSN string for the L<DBI/connect> method.

Input: $host, $port, $database.
Output: $dsn.

This method composes basic database type agnostic DSN string, e.g. without any
database driver prefix. You should override this method to prepend it with DBD
prefix like `Pg:' or `mysql:' or modify it in some other way as needed.

=begin testing dsn