=pod

=head1 NAME

App::DBBrowser database plugin documentation.

=head1 VERSION

Version 0.049_06

=head1 DESCRIPTION

A database plug-in provides the database specific methods. C<App::DBBrowser> considers a modules which name match the
repex pattern C</^App::DBBrowser::DB::[\w-]+\.pm\z/> and is located in one of the C<@INC> directories as database
plugins. The user can add such a database plugin to the available plugins in the option menu (C<db-browser -h>) by
selecting "Database" und then "DB Plugin". A suitable database plugin provides the methods named in this documentation.

=head1 METHODS

=head2 db_driver

=over

=item Argument

none

=item Return

The C<DBI> database driver used by the plugin.

=item Example

Example from the C<Pg> plugin:

    sub db_driver {
        my ( $self ) = @_;
        return $self->{db_driver};
    }

=back

=head2 available_databases

=over

=item Argument

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

=item Return

If the option metadata is true, C<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, C<available_databases> returns only the user-databases as an array-reference.

=item Example

Example from the C<mysql> plugin:

    sub available_databases {
        my ( $self, $connect_arg ) = @_;
        return \@ARGV if @ARGV;
        my @regex_system_db = ( '^mysql$', '^information_schema$', '^performance_schema$' );
        my $stmt = "SELECT schema_name FROM information_schema.schemata";
        if ( ! $self->{metadata} ) {
            $stmt .= " WHERE " . join( " AND ", ( "schema_name NOT REGEXP ?" ) x @regex_system_db );
        }
        $stmt .= " ORDER BY schema_name";
        my $info_database = 'information_schema';
        print $self->{clear_screen};
        print "DB: $info_database\n";
        my $dbh = $self->get_db_handle( $info_database, $connect_arg );
        my $databases = $dbh->selectcol_arrayref( $stmt, {}, $self->{metadata} ? () : @regex_system_db );
        $dbh->disconnect(); #
        if ( $self->{metadata} ) {
            my $regexp = join '|', @regex_system_db;
            my $user_db   = [];
            my $system_db = [];
            for my $database ( @{$databases} ) {
                if ( $database =~ /(?:$regexp)/ ) {
                    push @$system_db, $database;
                }
                else {
                    push @$user_db, $database;
                }
            }
            return $user_db, $system_db;
        }
        else {
            return $databases;
        }
    }
    
=back

=head2 get_db_handle

=over

=item Arguments

The database name and a hash reference with connection data.

Keys matching the regexp /^\Q$db_driver\E_/ are connection attributes.

=item Return

Database handle.

=item Example

Example from the C<mysql> plugin:

    sub get_db_handle {
        my ( $self, $db, $connect_arg ) = @_;
        $connect_arg = {} if ! defined $connect_arg; #
        my $db_driver = $self->{db_driver};
        my $obj_db_cred = App::DBBrowser::DB_Credentials->new( { connect_arg => $connect_arg } );
        my $host   = $obj_db_cred->get_login( 'host', $self->{login_mode_host} );
        my $port   = $obj_db_cred->get_login( 'port', $self->{login_mode_port} );
        my $user   = $obj_db_cred->get_login( 'user', $self->{login_mode_user} );
        my $passwd = $obj_db_cred->get_login( 'pass', $self->{login_mode_pass} );
        my $dsn  = "dbi:$db_driver:dbname=$db";
        $dsn .= ";host=$host" if length $host;
        $dsn .= ";port=$port" if length $port;
        my %db_arg = map { $_ => $connect_arg->{$_} } grep { /^\Q$db_driver\E_/i } keys %$connect_arg;
        my $dbh = DBI->connect( $dsn, $user, $passwd, {
            PrintError => 0,
            RaiseError => 1,
            AutoCommit => 1,
            ShowErrorStatement => 1,
            %db_arg,
        } ) or die DBI->errstr;
        return $dbh;
    }
  
=back

=cut