view release on metacpan or  search on metacpan

lib/DBIx/Class/Async/Storage/DBI.pm  view on Meta::CPAN

    # Execute raw SQL through the worker pool
    $storage->execute_all("UPDATE users SET last_login = ?", [ time ])
            ->then(sub {
                say "Bulk update complete.";
            });

    # Modern Async/Await iteration (Recommended)
    use Future::AsyncAwait;

    my $cursor = $schema->storage->cursor($rs);

    async sub process_all_users {
        while (my $row = await $cursor->next) {
            say "Streaming user: " . $row->name;
        }
        say "All users processed.";
    }

=head1 DESCRIPTION

This class provides a DBI-based storage backend for L<DBIx::Class::Async::Schema>.
It extends L<DBIx::Class::Async::Storage> and implements DBI-specific functionality
for managing database connections and operations in an asynchronous worker pool
environment.

Unlike traditional L<DBIx::Class::Storage::DBI>, this storage class does not
maintain database handles in the parent process. Instead, database handles are
managed by worker processes, allowing for non-blocking asynchronous database
operations using L<Future> objects.

This class is automatically instantiated when you connect to a database using
L<DBIx::Class::Async::Schema/connect> and generally does not need to be
instantiated directly.

=head1 METHODS

=head2 dbh

  my $dbh = $storage->dbh;

Returns C<undef> in async storage mode.

Unlike traditional L<DBIx::Class::Storage::DBI>, the async storage layer does
not maintain a database handle in the parent process. Instead, database handles
are held by worker processes in the background worker pool, which execute
queries asynchronously.

This method exists for API compatibility with standard L<DBIx::Class> storage
objects, but always returns C<undef> to indicate that direct database handle
access is not available in async mode.

  my $storage = $schema->storage;
  my $dbh = $storage->dbh;  # Always undef in async mode

  if (!defined $dbh) {
      say "Running in async mode - no direct DBH access";
  }

If you need to perform database operations, use the L<DBIx::Class::Async::ResultSet>
and L<DBIx::Class::Async::Row> methods which handle async execution transparently
through the worker pool.

=cut

sub dbh {
    my $self = shift;
    # In Async mode, the parent process doesn't hold a DBH.
    # The workers hold the DBHs.
    return undef;
}

=head2 cursor

  my $cursor = $storage->cursor($resultset);

Creates and returns a L<DBIx::Class::Async::Storage::DBI::Cursor> object
for asynchronously iterating through a ResultSet's rows.

The cursor provides a low-level interface for fetching rows one at a time
using Futures, which is useful for processing large result sets without
loading all rows into memory at once.

B<Arguments>

=over 4

=item * C<$resultset> - A L<DBIx::Class::Async::ResultSet> object

=back

B<Returns>

A L<DBIx::Class::Async::Storage::DBI::Cursor> object configured for the
given ResultSet.

  use Future::AsyncAwait;

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

  my $iter = async sub {
      while (my $row = await $cursor->next) {
          say $row->name;
      }
  };

  $iter->get;

The cursor respects the ResultSet's C<rows> attribute for batch fetching:

  my $rs = $schema->resultset('User')->search(undef, { rows => 50 });
  my $cursor = $storage->cursor($rs);  # Fetches 50 rows at a time

See L<DBIx::Class::Async::Storage::DBI::Cursor> for available cursor methods.

=cut

sub cursor {
    my ($self, $rs) = @_;