/ 
DBIx-Class-Async-0.09
/ DBIx::Class::Async::Schema

NAME

DBIx::Class::Async::Schema - Asynchronous Schema for DBIx::Class::Async

VERSION

Version 0.09

SYNOPSIS

use DBIx::Class::Async::Schema;

# Connect with async options
my $schema = DBIx::Class::Async::Schema->connect(
    'dbi:mysql:database=test',  # DBI connect string
    'username',                 # Database username
    'password',                 # Database password
    { RaiseError => 1 },        # DBI options
    {                           # Async options
        schema_class => 'MyApp::Schema',
        workers      => 4,
    }
);

# Get a resultset
my $users_rs = $schema->resultset('User');

# Asynchronous operations
$users_rs->search({ active => 1 })->all->then(sub {
    my ($active_users) = @_;
    foreach my $user (@$active_users) {
        say "Active user: " . $user->name;
    }
});

# Disconnect when done
$schema->disconnect;

DESCRIPTION

DBIx::Class::Async::Schema provides an asynchronous schema class that mimics the DBIx::Class::Schema API but performs all database operations asynchronously using Future objects.

This class acts as a bridge between the synchronous DBIx::Class API and the asynchronous backend provided by DBIx::Class::Async. It manages connection pooling, result sets, and transaction handling in an asynchronous context.

CONSTRUCTOR

connect

my $schema = DBIx::Class::Async::Schema->connect(
    $dsn,           # Database DSN
    $user,          # Database username
    $password,      # Database password
    $db_options,    # Hashref of DBI options
    $async_options, # Hashref of async options
);

Connects to a database and creates an asynchronous schema instance.

Parameters

The first four parameters are standard DBI connection parameters. The fifth parameter is a hash reference containing asynchronous configuration:

schema_class (required)

The name of the DBIx::Class schema class to use (e.g., 'MyApp::Schema').

workers

Number of worker processes (default: 4).

connect_timeout

Connection timeout in seconds (default: 10).

max_retries

Maximum number of retry attempts for failed operations (default: 3).

Returns

A new DBIx::Class::Async::Schema instance.

Throws

  • Croaks if schema_class is not provided.

  • Croaks if the schema class cannot be loaded.

  • Croaks if the async instance cannot be created.

METHODS

resultset

my $rs = $schema->resultset('User');

Returns a result set for the specified source/table.

Parameters
$source_name

Name of the result source (table) to get a result set for.

Returns

A DBIx::Class::Async::ResultSet object.

Throws

Croaks if $source_name is not provided.

source

my $source = $schema->source('User');

Returns the result source object for the specified source/table.

Parameters
$source_name

Name of the result source (table).

Returns

A DBIx::Class::ResultSource object.

Notes

Sources are cached internally after first lookup to avoid repeated database connections.

sources

my @source_names = $schema->sources;

Returns a list of all available source/table names.

Returns

Array of source names (strings).

Notes

This method creates a temporary synchronous connection to the database to fetch the source list.

storage

my $storage = $schema->storage;

Returns a storage object for compatibility with DBIx::Class.

Returns

A DBIx::Class::Async::Storage object.

Notes

This storage object does not provide direct database handle access since operations are performed asynchronously by worker processes.

txn_do

$schema->txn_do(sub {
    my $txn_schema = shift;
    # Perform async operations within transaction
    return $txn_schema->resultset('User')->create({
        name  => 'Alice',
        email => 'alice@example.com',
    });
})->then(sub {
    my ($result) = @_;
    # Transaction committed successfully
})->catch(sub {
    my ($error) = @_;
    # Transaction rolled back
});

Executes a code reference within a database transaction.

Parameters
$code

Code reference to execute within the transaction. The code receives the schema instance as its first argument.

@args

Additional arguments to pass to the code reference.

Returns

A Future that resolves to the return value of the code reference if the transaction commits, or rejects with an error if the transaction rolls back.

Throws

  • Croaks if the first argument is not a code reference.

txn_scope_guard

my $guard = $schema->txn_scope_guard;
# Perform async operations
$guard->commit;  # or rolls back if $guard goes out of scope

Returns a transaction scope guard for manual transaction management.

Returns

A DBIx::Class::Async::TxnGuard object.

Notes

If the guard object goes out of scope without an explicit commit, the transaction will be rolled back automatically.

set_default_context

$schema->set_default_context;

Sets the default context for the schema.

Returns

The schema object itself (for chaining).

Notes

This is a no-op method provided for compatibility with DBIx::Class.

clone

my $cloned_schema = $schema->clone;

Creates a clone of the schema with a fresh worker pool.

Returns

A new DBIx::Class::Async::Schema instance with fresh connections.

Notes

The cloned schema shares no state with the original and has its own worker processes and source cache.

disconnect

$schema->disconnect;

Disconnects all worker processes and cleans up resources.

Notes

This method is called automatically when the schema object is destroyed, but it's good practice to call it explicitly when done with the schema.

AUTOLOAD

The schema uses AUTOLOAD to delegate unknown methods to the underlying DBIx::Class::Async instance. This allows direct access to async methods like search, find, create, etc., without going through a resultset.

Example:

# These are equivalent:
$schema->find('User', 123);
$schema->resultset('User')->find(123);

Methods that are not found in the schema or the async instance will throw an error.

DESTROY

The schema's destructor automatically calls disconnect to clean up worker processes and other resources.

SEE ALSO

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/DBIx-Class-Async

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/DBIx-Class-Async/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc DBIx::Class::Async::Schema

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (C) 2026 Mohammad Sajid Anwar.

This program is free software; you can redistribute it and / or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License.By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you,you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement,then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.