NAME

FusqlFS::Backend::Base - base FusqlFS class for database backend implementations

SYNOPSIS

    use FusqlFS::Backend::PgSQL;
    use parent 'FusqlFS::Backend::Base';

    use FusqlFS::Backend::PgSQL::Tables;
    use FusqlFS::Backend::PgSQL::Views;
    use FusqlFS::Backend::PgSQL::Sequences;
    use FusqlFS::Backend::PgSQL::Roles;

    sub init
    {
        my $self = shift;
        $self->{subpackages} = {
            tables    => new FusqlFS::Backend::PgSQL::Tables(),
            views     => new FusqlFS::Backend::PgSQL::Views(),
            sequences => new FusqlFS::Backend::PgSQL::Sequences(),
            roles     => new FusqlFS::Backend::PgSQL::Roles(),
        };
    }

    sub dsn
    {
        my $self = shift;
        return 'Pg:'.$shift->SUPER::dsn(@_);
    }

    1;

DESCRIPTION

This is the base abstract class and start point for any FusqlFS database backend implementation. The instance of this class's subclass is a "root" of fusqlfs file system.

You start your backend implementation by subclassing FusqlFS::Backend::Base and overriding some methods as described in "SYNOPSIS".

See "METHODS" section for detailed description of what you should and should not override.

You should define subpackages instance variable among other operations in order for your backend class to be usable. The value of this property must be a hashref which describes root of fusqlfs subsystem: its keys will be file names, and values will be these files' content (well, the values are usually FusqlFS::Artifact instances interfacing to different database artifacts, so "file" here means not only plain file, but directories, symlinks and pseudopipes as well).

See also FusqlFS::Entry to learn how this instance variable is used, how file paths are mapped to backend objects and how file type is determined.

METHODS

new

Class constructor.

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 $class->SUPER::new(...) at some point to avoid unnecessary work.

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

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 "new" method above, so no parameters are required.

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

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

by_path

Returns FusqlFS::Entry entry by path.

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

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

dsn

Compose DSN string for the "connect" in DBI 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.

init

Abstract method called after main initialization work in "new" is done.

No data is passed to this method, except for class instance reference as first argument, and all data returned from it are ignored.

This is an abstract method called as instance method after "new" is done all initialization work and you should override it if you have some additional initialization work to do. You will override it most times, actually.

destroy

Destroy instance state variable.

The FusqlFS::Backend::Base class is a singleton. It is initialized only once and every subsequent call to "new" method returns the same class instance, stored in inner state variable.

Sometimes you really need to reset this instance and reinitialize this singleton. If this is the case, use this method.

Do it only if you really understand all the sequences and you don't have any other way to do the thing you want to do.