/ 
App-DBBrowser-0.990
River stage zero No dependents
/ App::DBBrowser

NAME

App::DBBrowser database plugin documentation.

VERSION

Version 0.990

DESCRIPTION

The API described below is new a may be changed.

A database plugin provides the database specific methods. App::DBBrowser considers a module whose name matches the regex pattern /^App::DBBrowser::DB::[\w_]+\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.

Column names passed as arguments are already quoted with the DBI quote_identifier method.

METHODS

new

The constructor method.

Arguments

A reference to a hash. The hash entries are:

app_dir             # path application directoriy
db_plugin           # name of the database plugin
metadata            # true or false

                    # ask     use environment variable    don't ask
login_mode_host     # 0       1                           2
login_mode_port     # 0       1                           2
login_mode_user     # 0       1
login_mode_pass     # 0       1


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

The object.

db_driver

Arguments

none

return

The DBI database driver name used by the plugin.

driver_prefix

Arguments

none

return

The driver-private prefix.

available_databases

Arguments

A reference to a hash. If available_databases uses the get_db_handle method, the hash reference can be passed to get_db_handle as the second argument.

return

If the option metadata is true, available_databases returns the "user-databases" as an array-reference and the "system-databases" (if any) as an array-reference.

If the option metadata is not true, available_databases returns only the "user-databases" as an array-reference.

get_db_handle

Arguments

The database name and a hash reference with connection data.

The hash reference provides the settings from the option Database settings.

The hash entry attributes holds connection attributes as a hash reference.

{
    host       => 'host',
    port       => 'port',
    user       => 'user',
    attributes => {
        key => value,
        ...
    },
    ...
}
return

Database handle.

get_schema_names

Arguments

The database handle and the database name.

return

If the option metadata is true, get_schema_names returns the "user-schemas" as an array-reference and the "system-schemas" (if any) as an array-reference.

If the option metadata is not true, get_schema_names returns only the "user-schemas" as an array-reference.

get_table_names

Arguments

The database handle and the schema name.

return

If the option metadata is true, get_table_names returns the "user-tables" as an array-reference and the "system-tables" (if any) as an array-reference.

If the option metadata is not true, get_table_names returns only the "user-tables" as an array-reference.

column_names_and_types

The method column_names_and_types is optional.

Arguments

Database handle, database name, schema name, available tables as an array reference.

return

Two hash references - one for the column names and one for the column types:

$col_names = {
    table_1 => [ column_1_name, column_2_name, ... ],
    table_2 => [ column_1_name, column_2_name, ... ],
    ...
}

$col_types = {
    table_1 => [ column_1_type, column_2_type, ... ],
    table_2 => [ column_1_type, column_2_type, ... ],
    ...
}

primary_and_foreign_keys

The method primary_and_foreign_keys is optional.

Arguments

Database handle, database name, schema name, available tables as an array reference.

return

Two hash references - one for the primary keys and one for the foreign keys:

$primary_keys = {
    table_1 => [ 'primary_key_col_1' [ , ... ] ],
    table_2 => [ 'primary_key_col_1' [ , ... ] ],
    ...
};

$foreign_keys = {
    table_1 => {
        fk_name_1 => {
            foreign_key_col   => [ 'foreign_key_col_1' [ , ... ] ],
            reference_table   => 'Reference_table',
            reference_key_col => [ 'reference_key_col_1' [ , ... ] ],
        fk_name_2 => {
            ...
        }
    table_2 => {
        ...
    }
};

sql_regexp

Arguments

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

return

The sql regexp substatement.

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

sub sql_regexp {
    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 form the plugin App::DBBrowser::DB::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 form the plugin App::DBBrowser::DB::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 form the plugin App::DBBrowser::DB::mysql:

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

truncate

Arguments

The column name and the precision (int).

return

The sql truncate substatement.

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

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

bit_length

Arguments

The column name.

return

The sql bit length substatement.

Example form the plugin App::DBBrowser::DB::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 form the plugin App::DBBrowser::DB::Pg:

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

CREDITS

Thanks to the Perl-Community.de and the people form stackoverflow for the help.

AUTHOR

Matthäus Kiem <cuer2s@gmail.com>

LICENSE AND COPYRIGHT

Copyright 2012-2014 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.