NAME

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

VERSION

Version 0.999

DESCRIPTION

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.

PLUGIN API VERSION

This documentation describes the plugin API version 1.3.

New in 1.3:

- method column_names_and_types is not optional (required in union and join ).

New in 1.2:

- the former object attribute "metadata" is now called "add_metadata".

- the SQLite directories are passed directly to the available_databases method (see $connect_parameter) instead to the constructor new.

Supported plugin API versions: 1.3, 1.2, 1.1.

Support for the version 1.1 and 1.2 will be removed soon.

METHODS

new

The constructor method.

Arguments

A reference to a hash. The hash entries are:

        app_dir             # path to the application directoriy
        home_dir
        db_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

return

The object.

plugin_api_version

Arguments

none

return

The version of the plugin-API to which the plugin refers.

See "PLUGIN API VERSION" for the plugin API version described by this documentation.

db_driver

Arguments: none
return: The name of the DBI database driver used by the plugin.

driver_prefix

Arguments: none
return: The driver-private prefix.

Example for the database driver Pg:

    sub driver_prefix {
        return 'pg';
    }

login_data

Arguments

none

return

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

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

name holds the name of the login data for example like "user" or "host".

The value of prompt is used as the prompt string, when the user is asked for the login data.

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

An example login_data method:

    sub login_data {
        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 method login_data is used to build the entries of the db-browser options DB Login Mode and DB Login Data.

connect_attributes

Arguments

none

return

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

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

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

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

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

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

    sub connect_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 ] },
        ];
    }

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. See "get_db_handle" for more info about the passed hash reference.

return

If the object attribute add_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 object attribute add_metadata is not true, available_databases returns only the "user-databases" as an array-reference.

get_db_handle

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.

    $connect_parameter = {
        attributes => {
            connect_attribute => chosen value,
            connect_attribute => chosen value,
            ...
        },
        login_mode => {         # ask   use environment variable   don't ask
            name => 0, 1 or 2,  # 0     1                          2
            name => 0, 1 or 2,  # 0     1                          2
            ...
        },
        login_data => {
            name => user input,
            name => user input,
            ...
        },
        keep_secret = {
            name => true or false,
            name => true or false,
            ...
        },
        dir_sqlite => [     # array reference with directories where to search for SQLite databases
            /path/dir,
            ...
        ]
    };

If login_mode is set to 1, the name of the used environment variable is the uppercase of "name" prefixed with "DBI_".

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

    $connect_parameter = {
        login_data => {
            host => undef,
            pass => undef,
            user => 'db_user_name',
            port => undef
        },
        attributes => {
            mysql_enable_utf8 => 1
        },
        login_mode => {
            port => 2,      # don't ask
            user => 1,      # use the environment variable DBI_USER if available
            pass => 1,      # use the environment variable DBI_PASS if available
            host => 2       # don't ask
        },
        keep_secret => {
            port => 0,
            host => 0,
            pass => 1,
            user => 0
        },
    };

return

Database handle.

get_schema_names

Arguments

The database handle and the database name.

return

If the object attribute add_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 object attribute add_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 object attribute add_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 object attribute add_metadata is not true, get_table_names returns only the "user-tables" as an array-reference.

column_names_and_types

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).

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

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')";
    }

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

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.

To install App::DBBrowser, copy and paste the appropriate command in to your terminal.

cpanm

cpanm App::DBBrowser

CPAN shell

perl -MCPAN -e shell
install App::DBBrowser

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

DESCRIPTION

PLUGIN API VERSION

METHODS

new

plugin_api_version

db_driver

driver_prefix

login_data

connect_attributes

available_databases

get_db_handle

get_schema_names

get_table_names

column_names_and_types

primary_and_foreign_keys

sql_regexp

concatenate

epoch_to_datetime

epoch_to_date

truncate

bit_length

char_length

CREDITS

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions