NAME

Acrux::DBI - Database independent interface for Acrux applications

SYNOPSIS

    use Acrux::DBI;

DESCRIPTION

Database independent interface for Acrux applications

new

    my $dbi = Acrux::DBI->new( $db_url );
    my $dbi = Acrux::DBI->new( $db_url, { ... options ... });
    my $dbi = Acrux::DBI->new( $db_url, ... options ...);

Build new Acrux::DBI object

Options:

autoclean

This options turns on auto disconnecting on DESTROY phase

See also list of default options in "options"

METHODS

This class implements the following methods

begin

    $dbi->begin;
    # ...
    $dbi->commit; # ..or $dbi->rollback

This is a transaction method!

This method marks the starting point for the start of a transaction

    $dbi->begin;
    $dbi->query('insert into test values (?)', 'Foo');
    $dbi->query('insert into test values (?)', 'Bar');
    $dbi->commit;

See slso "transaction", "commit", "rollback"

cache

    my $cache = $dbi->cache;

Returns the Mojo::Cache object

cachekey

    my $cachekey = $dbi->cachekey;

Returns the key name of the cached connect (See "connect_cached")

cleanup

    $dbi = $dbi->cleanup;

This internal method to cleanup database handler

commit

    $dbi->begin;
    # ...
    $dbi->commit;

This is a transaction method!

This method accepts all changes to the database and marks the end point for the transaction to complete

See also "begin", "rollback"

connect

    my $dbi = $dbi->connect;
    die $dbi->error if $dbi->error;

This method makes a connection to the database

connect_cached

    my $dbi = $dbi->connect_cached;
    die $dbi->error if $dbi->error;

This method makes a cached connection to the database. See "connect_cached" in DBI for details

database

    my $database = $dbi->database;

This method returns the database that will be used for generating the connection DSN This will be used as "path" in Mojo::URL

Default: none

dbh

    my $dbh = $dbi->dbh;

Returns database handle used for all queries

disconnect

    my $dbi = $dbi->disconnect;

This method disconnects from the database

driver

    my $driver = $dbi->driver;

This is the "scheme" in Mojo::URL that will be used for generating the connection DSN

Default: sponge

dsn

    my $dsn = $dbi->dsn;
    my $dsn = $dbi->dsn('DBI:SQLite::memory:');

This method generates the connection DSN and returns it or returns already generated earley.

dump

    my $dump = $dbi->dump;
    my $dump = $dbi->dump(name => 'schema');

This method returns instance of Acrux::DBI::Dump class that you can use to change your database schema more easily

    # Load SQL dump file and import schema to database
    $dbi->dump->from_file('/tmp/schema.sql')->poke('foo');

See Acrux::DBI::Dump for details

err

    my $err = $dbi->err;

This method just returns $DBI::err value

errstr

    my $errstr = $dbi->errstr;

This method just returns $DBI::errstr value

error

    my $error = $dbi->error;

Returns error string if occurred any errors while working with database

    $dbi = $dbi->error( "error text" );

Sets new error message and returns object

host

    my $host = $dbi->host;

This is the "host" in Mojo::URL that will be used for generating the connection DSN

Default: localhost

options

    my $options = $dbi->options;

This method returns options that will be used for generating the connection DSN

Default: all passed options to constructor merged with system defaults:

    RaiseError  => 0,
    PrintError  => 0,
    PrintWarn   => 0,

password

    my $password = $dbi->password;

This is the "password" in Mojo::URL that will be used for generating the connection DSN

default: none

ping

    $dbi->ping ? 'OK' : 'Database session is expired';

Checks the connection to database

port

    my $port = $dbi->port;

This is the "port" in Mojo::URL that will be used for generating the connection DSN

Default: none

query

    my $res = $dbi->query('select * from test');
    my $res = $dbi->query('insert into test values (?, ?)', @values);

Execute a blocking statement and return a Acrux::DBI::Res object with the results. You can also append a 'bind_callback' to perform binding value manually:

    my $res = $dbi->query('insert into test values (?, ?)', {
        bind_callback => sub {
            my $sth = shift;
            $sth->bind_param( ... );
          }
      });

rollback

    $dbi->begin;
    # ...
    $dbi->rollback;

This is a transaction method!

This method discards all changes to the database and marks the end point for the transaction to complete

See also "begin", "commit"

transaction

    my $tx = $dbi->transaction;

Begin transaction and return Acrux::DBI::Tx object, which will automatically roll back the transaction unless "commit" in Acrux::DBI::Tx has been called before it is destroyed

    # Insert rows in a transaction
    eval {
      my $tx = $dbi->transaction;
      $dbi->query( ... );
      $dbi->query( ... );
      $tx->commit;
    };
    say $@ if $@;

url

    my $url = $dbi->url;
    $dbi = $dbi->url('sqlite:///tmp/test.db?sqlite_unicode=1');
    $dbi = $dbi->url('sqlite:///./test.db?sqlite_unicode=1'); # '/./' will be removed
    $dbi = $dbi->url('postgres://foo:pass@localhost/mydb?PrintError=1');
    $dbi = $dbi->url('mysql://foo:pass@localhost/test?mysql_enable_utf8=1');

Database connect url

The database connection URL from which all other attributes can be derived. "url" must be specified before the first call to "connect" is made, otherwise it will have no effect on setting the defaults.

For using SQLite databases with files relative to current directory you cat use '/./' prefix:

    # '/./' will be removed automatically
    $dbi = $dbi->url('sqlite:///./test.db?sqlite_unicode=1');

Default: "sponge://"

username

    my $username = $dbi->username;

This is the "username" in Mojo::URL that will be used for generating the connection DSN

default: none

userinfo

    my $userinfo = $dbi->userinfo;

This is the "userinfo" in Mojo::URL that will be used for generating the connection DSN

default: none

HISTORY

See Changes file

TO DO

See TODO file

SEE ALSO

Mojo::mysql, Mojo::Pg, Mojo::DB::Connector, CTK::DBI, DBI

AUTHOR

Serż Minus (Sergey Lepenkov) https://www.serzik.com <abalama@cpan.org>

COPYRIGHT

Copyright (C) 1998-2024 D&D Corporation. All Rights Reserved

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See LICENSE file and https://dev.perl.org/licenses/

cpanm Acrux::DBI

perl -MCPAN -e shell
install Acrux::DBI