NAME

DBIO::MySQL::EV - Async MySQL/MariaDB storage for DBIO via EV::MariaDB

VERSION

version 0.900007

SYNOPSIS

# Schema setup
package MyApp::Schema;
use base 'DBIO::Schema';
__PACKAGE__->load_components(qw(MySQL));

# Async is opt-in per connection
my $schema = MyApp::Schema->connect(
    $dsn, $user, $pass,
    { async => 'ev' },
);

# Async queries return Futures
$schema->resultset('Artist')->all_async->then(sub {
    my @artists = @_;
    say $_->name for @artists;
});

# Concurrency, not batching: there is no pipeline() to bracket here
# (ADR 0009). Issue several *_async calls without awaiting between them and
# gather them -- each runs on its own pooled connection.
my @futures = map {
    $schema->resultset('Artist')->create_async({ name => $_ })
} @names;
Future->needs_all(@futures)->then(sub { ... });

# Sync methods still work (block the event loop)
my @all = $schema->resultset('Artist')->all;

DESCRIPTION

Async MySQL/MariaDB support for DBIO using EV::MariaDB, a non-blocking MariaDB client built on MariaDB's C client library. Bypasses DBI entirely for maximum performance.

This transport has no explicit pipeline mode. EV::MariaDB exposes no primitive to bracket a batch, so DBIO::MySQL::EV::Storage overrides none of core's _pipeline_enter / _pipeline_sync / _pipeline_exit seams and declares no pipeline transport capability. $storage->pipeline is refused: it returns a failed Future saying that DBIO::MySQL::EV::Storage does not support pipeline(), without taking a connection from the pool and without running the batch ("pipeline" in DBIO::Storage::Async, ADR 0009).

What this driver offers instead is concurrency, not batching: issue several *_async calls without awaiting between them and gather them with Future->needs_all. Each of those runs on its own pooled connection, so the statements overlap on the wire. EV::MariaDB does batch consecutive queries issued on a single connection (up to 64 in flight), but the pooled CRUD path takes a connection per call, so wire-level batching is not something this driver can promise.

Async is an explicit, per-connection choice (ADR 0030): you opt in at connect time with { async => 'ev' }:

my $schema = MyApp::Schema->connect(
    $dsn, $user, $pass,
    { async => 'ev' },
);

The ev mode resolves to DBIO::MySQL::EV::Storage (this distribution) and is registered by DBIO::MySQL::Storage (the sync driver, in the DBIO::MySQL distribution) with register_async_mode( ev => 'DBIO::MySQL::EV::Storage' ). Nothing in this distribution registers anything; the mapping deliberately lives on the driver storage, whose MRO the resolver walks. With { async = 'ev' }>, the *_async methods on the resulting storage run real non-blocking queries over EV::MariaDB.

A connection made from an DBIO::AccessBroker takes the same options beside the broker -- connect($broker, { async => 'ev', pool_size => 3 }): the transport declares the broker_connect_options capability ("transport_capabilities" in DBIO::MySQL::EV::Storage), so pool_size sizes its pool, and the broker is asked again for every pooled connection.

An EV::MariaDB parameter for the connections (charset, connect_timeout, ssl_ca, ...) belongs in the broker's answer ("_async_broker_conninfo" in DBIO::MySQL::EV::Storage). Given beside the broker, connect($broker, { async => 'ev', charset => ... }), such a parameter is not applied to any connection, and the transport refuses to be built with it rather than connect without it ("connect_info" in DBIO::MySQL::EV::Storage).

$storage->insert_async resolves with the returned-columns hashref (autoinc PK overlaid onto the supplied insert data), per ADR 0031 §3 -- MySQL has no RETURNING clause, so the EV storage assembles the hashref from LAST_INSERT_ID() on the pinned connection. select_async resolves with the raw row arrayrefs (cursor ->all shape) and select_single_async with a single row arrayref, matching the sync cursor shape. Backend Future ->then callbacks auto-wrap a plain return into a resolved Future (ADR 0031 §4), which is the native Future.pm behaviour.

EVENT LOOP COMPATIBILITY

EV::MariaDB uses the EV event loop. This works with:

SEE ALSO

DBIO::MySQL::EV::Storage, DBIO::MySQL::Storage, DBIO::Storage::Async.

ADRs 0030 and 0031 in the DBIO distribution's docs/adr/.

AUTHOR

DBIO Authors

COPYRIGHT AND LICENSE

Copyright (C) 2026 DBIO Authors

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