/ 
DBIx-QuickORM-0.000020
⭐ Starred 0 / DBIx::QuickORM::Manual::Connections

NAME

DBIx::QuickORM::Manual::Connections - A guide to the connection lifecycle in DBIx::QuickORM.

DESCRIPTION

A DBIx::QuickORM::Connection is the live link between your code and the database: it holds the DBI handle, a connection-local copy of the schema, the transaction stack, and the per-connection row cache. This guide covers how you obtain a connection, how it is reconnected, why connections cannot cross a fork, and how the underlying database link is configured.

GETTING A CONNECTION

An DBIx::QuickORM::ORM owns the primary connection to its database. You do not construct a connection directly; you ask the ORM for one.

my $con = $orm->connection;

connection is a memoized singleton: it builds the connection on first use and returns the same object every time after that. There is no need to cache the result yourself - call $orm->connection wherever you need it and you will get the one shared connection.

Most of the time you do not even need to call it explicitly. The ORM proxies the common entry point for you:

my $handle = $orm->handle('users');   # same as $orm->connection->handle('users')

If you want a brand new, independent connection instead of the shared one, call connect:

my $con = $orm->connect;   # a fresh DBIx::QuickORM::Connection, not cached

The quick() interface returns an already-connected DBIx::QuickORM::Connection directly, so you can start querying immediately without building an ORM by hand - see DBIx::QuickORM::Manual::QuickStart.

RECONNECTING

There are two distinct "reconnect" operations, and they behave differently.

Connection->reconnect (in-place)

$con->reconnect;

This swaps out the underlying DBI handle for a fresh one on the same connection object. The connection object itself - and therefore its row cache, schema, and the transaction stack - is preserved. The same $con reference remains valid. This is what you use after a fork (see below), and it is what auto_retry uses internally to recover from a dropped link.

ORM->reconnect (drop and rebuild)

my $con = $orm->reconnect;

This drops the ORM's cached connection entirely and builds a new one from scratch, returning it. The old connection object - along with its row cache - is discarded. Any references you were holding to the previous connection now point at the old, orphaned object, so re-fetch via $orm->connection.

To drop the cached connection without immediately rebuilding it, use $orm->disconnect; the next call to $orm->connection will build a fresh one lazily.

In short: $con->reconnect keeps everything except the dbh, while $orm->reconnect throws the whole connection (and its cache) away and starts over.

FORK SAFETY

A connection records the PID it was established under, and a DBI handle cannot be shared across processes. After a fork the child and parent would otherwise stomp on the same socket. To prevent this, the connection checks the PID before performing work and throws an exception if it is used from a process other than the one that created it.

The fix in a forked child is to reconnect in place:

my $pid = fork // die "fork failed: $!";
if ($pid == 0) {
    # child
    $con->reconnect;   # gives the child its own dbh, keeps the cache
    ...
    exit 0;
}

$con->reconnect marks the inherited handle InactiveDestroy when it belongs to another process (so the child does not tear down the parent's socket), then opens a new handle owned by the child. Each process must do this for itself before issuing queries.

If you want forked queries managed for you rather than forking by hand, see DBIx::QuickORM::Manual::Async.

AUTO-RETRY FOR TRANSIENT FAILURES

Network blips and dropped connections happen. auto_retry runs a block, retrying it if it throws, and reconnects in place between attempts when the handle is no longer responding:

my $result = $con->auto_retry(sub { ... });
my $result = $con->auto_retry($count => sub { ... });

auto_retry cannot be used inside a transaction (a half-applied transaction cannot be safely retried). For the transactional case use auto_retry_txn, which wraps the retried block in a transaction for you. Both are documented in detail in DBIx::QuickORM::Manual::Transactions.

CONFIGURING THE CONNECTION

How the DBI handle is actually built is defined by the DBIx::QuickORM::DB object behind the ORM. There are two ways to specify it.

Credentials

Provide the pieces and let the ORM call DBI->connect for you:

dsn

The DBI DSN string. When omitted it is built from the dialect and the connection coordinates (host/port/socket and db_name).

user
pass

Credentials passed through to DBI->connect.

attributes

A hashref of DBI attributes. Sensible defaults (RaiseError, PrintError, AutoCommit, AutoInactiveDestroy) are filled in for you.

dbi_driver

The DBI driver name associated with the database.

A connect callback

Alternatively, supply a connect coderef that returns a fresh DBI handle. When present it is used instead of the DSN-based path, giving you full control over how the handle is opened (custom drivers, connection pools, extra setup, and so on):

connect => sub { DBI->connect($dsn, $user, $pass, \%attrs) },

Each new handle - whether for the first connection, a reconnect, or a forked child - is produced the same way: via your callback if you provided one, otherwise via DBI->connect with the resolved DSN and credentials. See DBIx::QuickORM::DB for the full set of configuration attributes.

SEE ALSO

DBIx::QuickORM::Connection

The connection object itself: transactions, handles, async/aside/forked queries, and the state operations backing the row cache.

DBIx::QuickORM::ORM

The owner of the primary connection.

DBIx::QuickORM::DB

The database connection definition.

DBIx::QuickORM::Manual::Transactions

Transactions, savepoints, and automatic retry.

DBIx::QuickORM::Manual::Caching

The per-connection row cache that reconnecting in place preserves and that $orm->reconnect discards.

DBIx::QuickORM::Manual::QuickStart

The quick() interface that hands back a ready connection.

DBIx::QuickORM::Manual

The documentation hub.

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/