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-0.991
River stage zero No dependents
/ App::DBBrowser

NAME

App::DBBrowser database plugin documentation.

VERSION

Version 0.991

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.