The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
App-DBBrowser-1.060_03
River stage zero No dependents
14 ++
/ App::DBBrowser::DB

NAME

App::DBBrowser::DB - Database plugin documentation.

VERSION

Version 1.060_03

DESCRIPTION

A database plugin provides the database specific methods. App::DBBrowser considers a module whose name matches /^App::DBBrowser::DB::[^:']+\z/ and which is located in one of the @INC directories as a database plugin. Plugins with the name App::DBBrowser::DB::$database_driver should be for general use of $database_driver databases.

The user can add an installed database plugin to the available plugins in the option menu (db-browser -h) by selecting DB and then DB Plugins.

A suitable database plugin provides the methods named in this documentation.

METHODS

Required methods

new

The constructor method.

Arguments

A reference to a hash. The hash entries are:

        app_dir             # path to the application directoriy
        home_dir            # path to the home directory
        plugin              # name of the database plugin
        add_metadata        # true or false

        # SQLite only:
        sqlite_search       # if true, don't use cached database names
        db_cache_file       # path to the file with the cached database names
        dirs_sqlite         # dirs to search for SQLite databases
return

The object.

driver

Arguments

none

return

The name of the DBI database driver used by the plugin.

databases

Arguments

A reference to a hash. If databases uses the method db_handle, this hash reference can be passed to db_handle as the second argument. See "db_handle" for more info about the passed hash reference.

return

Returns two array references: the first refers to the array of "user-databases" the second to the "system-databases" (if any).

If the option add_metadata is true, both - "user-databases" and "system-databases" - are used else only the "user-databases" are used.

db_handle

db-browser expects the attribute RaiseError to be enabled.

Arguments

The database name and a reference to a hash of hashes.

The hash of hashes provides the settings gathered from the option Database settings. Which Database settings are available depends on the methods arguments, env_variables and attributes.

For example the hash of hashes held by $connect_parameter for a mysql plugin could look like this:

    $connect_parameter = {
        use_env_var => {
            DBI_HOST => 1,
            DBI_USER => 0,
            DBI_PASS => 0,
        },
        arguments => {
            host => undef,
            pass => undef,
            user => 'db_user_name',
            port => undef
        },
        attributes => {
            mysql_enable_utf8 => 1
        },
        required => {
            port => 0,
            user => 1,
            pass => 1,
            host => 1
        },
        secret => {
            port => 0,
            host => 0,
            pass => 1,
            user => 0
        },
    };
return

Database handle.

Optional methods

schemas

Arguments

The database handle and the database name.

return

Returns the "user-schemas" as an array-reference and the "system-schemas" (if any) as an array-reference.

If the option add_metadata is true, both - "user-schemas" and "system-schemas" - are used else only the "user-schemas" are used.

DB configuration methods

If the database driver is SQLite only set_attributes is used.

read_arguments

Arguments

none

return

A reference to an array of hashes. The hashes have two or three key-value pairs:

    { name => 'string', prompt => 'string', keep_secret => true/false }

name holds the field name for example like "user" or "host".

The value of prompt is used as the prompt string, when the user is asked for the data. The prompt entry is optional. If prompt doesn't exist, the value of name is used instead.

If keep_secret is true, the user input should not be echoed to the terminal. Also the data is not stored in the plugin configuration file if keep_secret is true.

An example read_arguments method:

    sub read_arguments {
        my ( $self ) = @_;
        return [
            { name => 'host', prompt => "Host",     keep_secret => 0 },
            { name => 'port', prompt => "Port",     keep_secret => 0 },
            { name => 'user', prompt => "User",     keep_secret => 0 },
            { name => 'pass', prompt => "Password", keep_secret => 1 },
        ];
    }

The information returned by the method read_arguments is used to build the entries of the db-browser options Fields and Login Data.

env_variables

Arguments

none

return

A reference to an array of environment variables.

An example env_variables method:

    sub env_variables {
        my ( $self ) = @_;
        return [ qw( DBI_DSN DBI_HOST DBI_PORT DBI_USER DBI_PASS ) ];
    }

See the db-browser option ENV Variables.

set_attributes

Arguments

none

return

A reference to an array of hashes. The hashes have three or four key-value pairs:

    { name => 'string', prompt => 'string', default_index => index, avail_values => [ value_1, value_2, value_3, ... ] }

The value of name is the name of the database connection attribute.

The value of prompt is used as the prompt string. The prompt entry is optional. If prompt doesn't exist, the value of name is used instead.

avail_values holds the available values for that attribute as an array reference.

The avail_values array entry of the index position default_index is used as the default value.

Example form the plugin App::DBBrowser::DB::SQLite:

    sub set_attributes {
        my ( $self ) = @_;
        return [
            { name => 'sqlite_unicode',             default_index => 1, avail_values => [ 0, 1 ] },
            { name => 'sqlite_see_if_its_a_number', default_index => 1, avail_values => [ 0, 1 ] },
        ];
    }

set_attributes determines the database handle attributes offered in the db-browser option DB Options.

For SQLite/mysql/Pg the following methods are already built in.

Whether passed column names are already quoted or not depends on how db-browser was configured.

regexp_sql

Arguments

Column name, $do_not_match_regexp (true/false), $case_sensitive (true/false).

Use the placeholder instead of the string which should match or not match the regexp.

return

The sql regexp substatement.

Example (mysql):

    sub regexp_sql {
        my ( $self, $col, $do_not_match_regexp, $case_sensitive ) = @_;
        if ( $do_not_match_regexp ) {
            return ' '. $col . ' NOT REGEXP ?'        if ! $case_sensitive;
            return ' '. $col . ' NOT REGEXP BINARY ?' if   $case_sensitive;
        }
        else {
            return ' '. $col . ' REGEXP ?'            if ! $case_sensitive;
            return ' '. $col . ' REGEXP BINARY ?'     if   $case_sensitive;
        }
    }

concatenate

Arguments

A reference to an array of strings.

return

The sql substatement which concatenates the passed strings.

Example (Pg):

    sub concatenate {
        my ( $self, $arg ) = @_;
        return join( ' || ', @$arg );
    }

epoch_to_datetime

Arguments

The column name and the interval.

The interval is 1 (seconds), 1000 (milliseconds) or 1000000 (microseconds).

return

The sql epoch to datetime substatement.

Example (mysql):

    sub epoch_to_datetime {
        my ( $self, $col, $interval ) = @_;
        return "FROM_UNIXTIME($col/$interval,'%Y-%m-%d %H:%i:%s')";
    }

epoch_to_date

Arguments

The column name and the interval.

The interval is 1 (seconds), 1000 (milliseconds) or 1000000 (microseconds).

return

The sql epoch to date substatement.

Example (mysql):

    sub epoch_to_date {
        my ( $self, $col, $interval ) = @_;
        return "FROM_UNIXTIME($col/$interval,'%Y-%m-%d')";
    }

truncate

Arguments

The column name and the precision (int).

return

The sql truncate substatement.

Example (mysql):

    sub truncate {
        my ( $self, $col, $precision ) = @_;
        return "TRUNCATE($col,$precision)";
    }

bit_length

Arguments

The column name.

return

The sql bit length substatement.

Example (Pg):

The sql bit length substatement.

    sub bit_length {
        my ( $self, $col ) = @_;
        return "BIT_LENGTH($col)";
    }

char_length

Arguments

The column name.

return

The sql char length substatement.

Example (Pg):

    sub char_length {
        my ( $self, $col ) = @_;
        return "CHAR_LENGTH($col)";
    }

AUTHOR

Matthäus Kiem <cuer2s@gmail.com>

LICENSE AND COPYRIGHT

Copyright 2012-2018 Matthäus Kiem.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For details, see the full text of the licenses in the file LICENSE.