App::DBBrowser::DB - Database plugin documentation.
Version 1.055
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.
App::DBBrowser
/^App::DBBrowser::DB::[^:']+\z/
@INC
App::DBBrowser::DB::$database_driver
$database_driver
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.
db-browser -h
A suitable database plugin provides the methods named in this documentation.
Column names passed as arguments to plugin methods are already quoted with the DBI quote_identifier method.
DBI
quote_identifier
This documentation describes the plugin API version 1.5.
1.5
Supported plugin API version: 1.5.
The constructor method.
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
The object.
none
The version of the plugin-API to which the plugin refers.
See "PLUGIN API VERSION" for the plugin API version described by this documentation.
The name of the DBI database driver used by the plugin.
The driver-private prefix.
Example for the database driver Pg:
Pg
sub driver_prefix { return 'pg'; }
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".
name
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.
prompt
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.
keep_secret
An example read_arguments method:
read_arguments
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.
db-browser
A reference to an array of environment variables.
An example environment_variables method:
environment_variables
sub environment_variables { my ( $self ) = @_; return [ qw( DBI_DSN DBI_HOST DBI_PORT DBI_USER DBI_PASS ) ]; }
See the db-browser option ENV Variables.
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.
avail_values
The avail_values array entry of the index position default_index is used as the default value.
default_index
Example form the plugin App::DBBrowser::DB::SQLite:
App::DBBrowser::DB::SQLite
sub choose_arguments { 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 ] }, ]; }
choose_arguments determines the database handle attributes with predefined values offered in the db-browser option DB Options.
choose_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.
available_databases
get_db_handle
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 add_metadata is not true, available_databases returns only the "user-databases" as an array-reference.
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 = { use_env_var => { env_var => true or false, env_var => true or false, ... }, chosen_arg => { attribute => chosen value, attribute => chosen value, ... }, required => { name => true or false, name => true or false, ... }, read_arg => { 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, ... ] };
For example for the plugin mysql the hash of hashes held by $connect_parameter could look like this:
mysql
$connect_parameter
$connect_parameter = { use_env_var => { DBI_HOST => 1, DBI_USER => 0, DBI_PASS => 0, }, read_arg => { host => undef, pass => undef, user => 'db_user_name', port => undef }, chosen_arg => { mysql_enable_utf8 => 1 }, required => { port => 0, user => 1, pass => 1, host => 1 }, keep_secret => { port => 0, host => 0, pass => 1, user => 0 }, };
Database handle.
The database handle and the database name.
If 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.
get_schema_names
If add_metadata is not true, get_schema_names returns only the "user-schemas" as an array-reference.
The database handle and the schema name.
If 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.
get_table_names
If add_metadata is not true, get_table_names returns only the "user-tables" as an array-reference.
The primary-key-autoincrement statement.
sub primary_key_auto { return "SERIAL PRIMARY KEY"; }
Database handle, database name, schema name, available tables as an array reference.
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, ... ], ... }
The method primary_and_foreign_keys is optional.
primary_and_foreign_keys
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 => { ... } };
Column name, $do_not_match_regexp (true/false), $case_sensitive (true/false).
$do_not_match_regexp
$case_sensitive
Use the placeholder instead of the string which should match or not match the regexp.
The sql regexp substatement.
Example form the plugin App::DBBrowser::DB::mysql:
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; } }
A reference to an array of strings.
The sql substatement which concatenates the passed strings.
Example form the plugin App::DBBrowser::DB::Pg:
App::DBBrowser::DB::Pg
sub concatenate { my ( $self, $arg ) = @_; return join( ' || ', @$arg ); }
The column name and the interval.
The interval is 1 (seconds), 1000 (milliseconds) or 1000000 (microseconds).
The sql epoch to datetime substatement.
sub epoch_to_datetime { my ( $self, $col, $interval ) = @_; return "FROM_UNIXTIME($col/$interval,'%Y-%m-%d %H:%i:%s')"; }
The sql epoch to date substatement.
sub epoch_to_date { my ( $self, $col, $interval ) = @_; return "FROM_UNIXTIME($col/$interval,'%Y-%m-%d')"; }
The column name and the precision (int).
The sql truncate substatement.
sub truncate { my ( $self, $col, $precision ) = @_; return "TRUNCATE($col,$precision)"; }
The column name.
The sql bit length substatement.
sub bit_length { my ( $self, $col ) = @_; return "BIT_LENGTH($col)"; }
The sql char length substatement.
sub char_length { my ( $self, $col ) = @_; return "CHAR_LENGTH($col)"; }
Matthäus Kiem <cuer2s@gmail.com>
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.
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.