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

ATTRIBUTES

These are accessed via read-only accessors of the same name.

orm

The DBIx::QuickORM::ORM object this connection belongs to.

dbh

The DBI database handle for this connection.

dialect

The DBIx::QuickORM::Dialect subclass instance for this connection.

pid

The PID the connection was established under.

schema

The connection-local DBIx::QuickORM::Schema (a clone of the ORM's schema).

transactions

Arrayref forming the active transaction/savepoint stack. Internal use only.

manager

The DBIx::QuickORM::RowManager instance managing row cache and state.

in_async

The active DBIx::QuickORM::STH::Async object, if an async query is running.

asides

Hashref of active "aside" queries.

forks

Hashref of active "forked" queries.

default_sql_builder

Default SQL builder, normally DBIx::QuickORM::SQLBuilder::SQLAbstract.

default_internal_txn

Boolean default for whether handles may use internal transactions.

default_handle_class

Default handle class, normally DBIx::QuickORM::Handle.

PUBLIC METHODS

$con->init

Object construction hook invoked by Object::HashBase. Establishes the database handle, dialect, schema, and row manager. Not called directly.

$con->set_async($async)

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

$con->add_aside($aside)

Register an "aside" query.

$con->add_fork($fork)

Register a "forked" query.

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

$con->clear_aside($aside)

Clear a previously registered "aside" query.

$con->clear_fork($fork)

Clear a previously registered "forked" query.

$con->pid_and_async_check

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

$con->pid_check

Throws an exception if the current PID does not match the connection's PID.

$con->async_check

Throws an exception if there is an async query running.

$db = $con->db

Shortcut for $con->orm->db. Returns an DBIx::QuickORM::DB object.

$dbh = $con->aside_dbh

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

$con->reconnect

Used to reconnect after forking.

$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. Calls 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.

This is a convenience method that boils 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().

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

$source = $con->source($in, %params)

Resolve $in to an object implementing DBIx::QuickORM::Role::Source. $in may be such an object, a scalar reference (treated as literal SQL), or a table name looked up in the schema. Croaks on failure unless no_fatal => 1 is passed, in which case it returns undef.

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

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

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

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

Note: unlike source(), handle() does not accept a scalar reference (literal SQL) directly; passing one throws. Build the source first and pass the object:

$con->handle($con->source(\$sql))->all;

$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 boils down to this:

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

$bool = $con->state_does_cache

Check if the current row manager 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 https://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 https://dev.perl.org/licenses/