/ 
DBIx-QuickORM-0.000019
River stage zero No dependents
⭐ Starred 0 GitHub stars
/ DBIx::QuickORM::Connection

NAME

DBIx::QuickORM::Connection - ORM connection to database.

DESCRIPTION

This module is the primary interface when using the ORM to connect to a database. This contains the database connection itself, a clone of the original schema along with any connection specific changes (temp tables, etc). You use this class to interact with the database, manage transactions, and get DBIx::QuickORM::Handle objects that can be used to make queries against the database.

SYNOPSIS

use My::Orm qw/orm/;

# Get a connection to the orm
# Note: This will return the same connection each time, no need to cache it yourself.
my $orm = orm('my_orm');

# Do something to all rows in the 'people' table.
my $people_handle = $orm->handle('people');
for my $person ($people_handle->all) {
    ...
}

# Find all people with the surname 'smith' and print their first names.
my $smith_handle = $people_handle->where({surname => 'smith'});
for my $person ($handle->all) {
    print $person->field('first_name') . "\n"
}

# Do a transaction that is managed by the ORM.
$con->txn(sub {
    my $txn = shift;

    ...

    if (good()) {
        # Can call commit or rollback manually. Or, if all is good just let
        # the sub exit and the transaction will commit itself.
        $txn->commit; # This will exit the subroutine
    }
    else {
        # Can call rollback manually, or if the sub exits due to an
        # exception being thrown, rollback will happen automatically.
        $txn->rollback; # This will exit the subroutine
    }
});

METHODS

HANDLE OPERATIONS

See DBIx::QuickORM::Handle for more information on handles

$h = $con->handle(...)

Get an DBIx::QuickORM::Handle object with that operates on this connection. Any argument accepted by the new() or handle() methods on DBIx::QuickORM::Handle can be provided here as arguments.

$h = $con->async(@handle_constructor_args)
$h = $con->aside(@handle_constructor_args)
$h = $con->forked(@handle_constructor_args)
$h = $con->all(@handle_constructor_args)
$h = $con->iterator(@handle_constructor_args)
$h = $con->any(@handle_constructor_args)
$h = $con->first(@handle_constructor_args)
$h = $con->one(@handle_constructor_args)
$h = $con->count(@handle_constructor_args)
$h = $con->delete(@handle_constructor_args)

These are convenience methods that simply proxy to handle objects:

my $h = $con->handle(@handle_constructor_args)->NAME();

See the methods in DBIx::QuickORM::Handle for more info.

$h = $con->by_id(@handle_constructor_args, $method_arg)
$h = $con->iterate(@handle_constructor_args, $method_arg)
$h = $con->insert(@handle_constructor_args, $method_arg)
$h = $con->vivify(@handle_constructor_args, $method_arg)
$h = $con->update(@handle_constructor_args, $method_arg)
$h = $con->update_or_insert(@handle_constructor_args, $method_arg)
$h = $con->find_or_insert(@handle_constructor_args, $method_arg)

These are convenience methods that simply proxy to handle objects:

my $h = $con->handle(@handle_constructor_args)->NAME($method_arg);

See the methods in DBIx::QuickORM::Handle for more info.

$rows_arrayref = $con->by_ids($source, @ids)

Fetch rows in the specified source by their ids.

NOTE: If all the specified rows are already cached, no DB query will occur.

$source can be a table name, or any object that implements DBIx::QuickORM::Role::Source.

@ids contains one or more row primary keys. The keys may be a scalar value such as 12 if the primary key is a single column. If the source has a compound primary key you may provide an arrayref with all the key field values, or a hashref with the field => val pairs.

An arrayref of DBIx::QuickORM::Row objects will be returned.

This is a convenience method that boild down to this:

$con->handle($source)->by_ids(@ids);

TRANSACTION MANAGEMENT

$txn = $con->transaction(sub { my $txn = shift; ... })
$txn = $con->txn(sub { my $txn = shift; ... })
$txn = $con->transaction(%params)
$txn = $con->txn(%params)

This will start a transaction or create a savepoint to emulate nested transactions. Call to this method can be nested.

$con->txn(sub {
    $con->txn(sub { ... }); # Nested! uses savepoints
});

If an action sub is provided then the transaction will be started, and the action sub will be executed. If the action sub returns then the transaction will be commited. If the action sub throws an exception the transaction will be rolled back.

You can also manually commit/rollback which will exit the action subroutine.

$txn->commmit;
$txn->rollback;

If you need to start a transaction that is not limited to a single subroutine, you can call this method without an action sub, it will return an DBIx::QuickORM::Connection::Transaction instance that can be used to commmit or rollback the transaction when you are ready. If the object falls completely out of scope and is destroyed then the transaction will be rolled back.

All possible arguments:

my $txn = $con->txn(
    # Action sub for this transaction, transaction ends when sub does.
    action => sub { my $txn = shift; ... },

    # Used to force a transaction even if there are aside or forked queries running.
    force        => $BOOL, # Basically a combination of the next 2 options
    ignore_aside => $BOOL, # Allow a transaction even if an aside query is active
    ignore_forks => $BOOL, # Allow a transaction even if a forked query is active

    # Things to run at the end of the transaction.
    on_fail       => sub { ... }, # Only runs if the txn is rolled back
    on_success    => sub { ... }, # Only runs if the txn is commited
    on_completion => sub { ... }, # Runs whent he txn is done regardless of status.

    # Same as above, except you are adding them to a direct parent txn (if one exists, otherwise they are no-ops)
    on_parent_fail       => sub { ... },
    on_parent_success    => sub { ... },
    on_parent_completion => sub { ... },

    # Same as above, except they are applied to the root transaction, no
    # matter how deeply nested it is.
    on_root_fail       => sub { ... },
    on_root_success    => sub { ... },
    on_root_completion => sub { ... },
);

An DBIx::QuickORM::Connection::Transaction instance is always returned. If an action callback was provided then the instance will already be complete, but you can check and see what the status was. If you did not provide an action callback then the txn will be "live" and you can use the instance to commit it or roll it back.

$bool_or_txn = $con->in_transaction
$bool_or_txn = $con->in_txn

Returns true if there is a transaction active. If the transaction is managed by DBIx::QuickORM then the DBIx::QuickORM::Connection::Transaction object will be returned.

$txn = $con->current_transaction
$txn = $con->current_txn

Return the current DBIx::QuickORM::Connection::Transaction if one is active.

Note: Do not use this to check for a transaction, it will return false if there is a transaction that is not managed by DBIx::QuickORM.

$con->auto_retry_txn(sub { my $txn = shift; ... })
$con->auto_retry_txn(\%params, sub { my $txn = shift; ... })
$con->auto_retry_txn(%params, action => sub { my $txn = shift; ... })

Run the specified action in a transaction, retry if an exception is thrown.

Run the subroutine is a convenience method that boild down to:

$con->auto_retry(sub { $con->txn(sub { ... }) });

count => $NUM can be used to specify a maximum number of retries, the default is 1.

All other params are passed to txn().

UTILITY

$db = $con->db

Shortcut for $con->orm->db.

This returns an DBIx::QuickORM::DB object.

$dbh = $con->dbh

Shortcut for $con->orm->dbh.

Returns the $dbh object used for this connection.

$dbh = $con->aside_dbh

Shortcut for $con->orm->db->new_db.

Returns a completely new and independant $dbh connected to the database.h

$res = $con->auto_retry(sub { ... })
$res = $con->auto_retry($count, sub { ... })

Run the provided sub multiple times until it succeeds or the count is exceeded.

Default count is 1.

An exception will be thrown if it never succeeds.

Cannot be used inside a transaction.

Returns whatever the provided coderef returns, scalar context is always assumed.

$class = $con->default_handle_class

Get the default handle class for this connection. Default is DBIx::QuickORM::Handle.

$bool = $con->default_internal_txn

Used by handles to know if they should default to allowing internal transactions, that is temporary transactions the handles use under the hood without the user necessarily being aware of them.

$class = $con->default_sql_builder

Default SQL Builder class to use. Normally DBIx::QuickORM::SQLBuilder::SQLAbstract.

$dialect = $con->dialect

Returns the DBIx::QuickORM::Dialect subclass for the connection.

$manager = $con->manager

Returns the DBIx::QuickORM::RowManager subclass to use for managing cache and other row state.

$orm = $con->orm

Returns the DBIx::QuickORM::ORM object associated with this connection.

$pid = $con->pid

Retusn the PID the connection is associated with.

$schema = $con->schema

Returns the DBIx::QuickORM::Schema object for this connection. This is a deep clone of the one from the DBIx::QuickORM::ORM's schema object, with connections pecific changes such as local tables being added.

Modifying this will NOT modify the schema in the root ORM object.

$source = $con->source

Returns the soure object. The source object should implement the DBIx::QuickORM::Role::Source role. It will usually be an DBIx::QuickORM::Schema::Table instance, but could also be an DBIx::QuickORM::Join or other object implementing the role.

This is NOT like calling source() from DBIx::Class, you cannot use the source directly to make queries, look at the handle() method instead.

SANITY CHECKS

These are sanity checks that will throw exceptions if invalid conditions are detected.

$con->pid_check

Throws an exception if the current PID does not match the connections PID.

$con->async_check

Throws an exception if there is an async query running.

$con->pid_and_async_check

Throws an exception if the PID does not match, or if there is an async query running.

INTERNAL STATE MANAGEMENT

$con->set_async($async)

Change state to be inside an async query, argument must be an DBIx::QuickORM::STH::Async instance.

$con->clear_async($async)

Change state to be outside of an async query. The argument must be an DBIx::QuickORM::STH::Async instance, and it must be the same object as the one returned by in_async().

$obj = $con->in_async

Returns the active DBIx::QuickORM::STH::Async object if there is an active async query. Returns undef if there is no active async query.

$con->add_aside($aside)
$con->asides
$con->clear_aside($aside)

Used to add or clear 'aside' queries.

$con->add_fork($fork)
$con->forks
$con->clear_fork($fork)

Used to add or clear 'forked' queries.

$con->reconnect

Used to reconnect after forking.

$arrayref = $con->transactions

For internal use only.

ROW STATE MANAGEMENT

$bool = $con->state_does_cache

Check if the current rowmanager handles caching of rows.

$row = $con->state_cache_lookup($source, $pk)

Find an in-cache row by source and primary key. Source can be a table name or object that implements DBIx::QuickORM::Role::Source.

The primary key should be a hashref:

{pk_field1 => $pk_val1, pk_field2 => $pk_val2, ... }
$con->state_delete_row(...)
$con->state_insert_row(...)
$con->state_select_row(...)
$con->state_update_row(...)
$con->state_vivify_row(...)
$con->state_invalidate(...)

These are shortcuts for:

$self->manager->METHOD(connection => $self, ...);

SOURCE

The source code repository for DBIx-QuickORM can be found at http://github.com/exodist/DBIx-QuickORM/.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

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

See http://dev.perl.org/licenses/