NAME

DBIO::MySQL::EV::Storage - Async MySQL/MariaDB storage driver using EV::MariaDB

VERSION

version 0.900007

DESCRIPTION

The native ev async transport for MySQL/MariaDB (core ADR 0030 / 0031): a thin transport over EV::MariaDB, a non-blocking client that speaks the MariaDB C client library directly. No DBI, no DBD::MySQL, just raw MariaDB performance.

It resolves as the ev async mode of DBIO::MySQL::Storage (registered there via register_async_mode( ev => ... )), so a schema connected with { async => 'ev' } answers the six *_async storage methods over EV::MariaDB while the same schema keeps serving synchronous queries over DBI/DBD::MySQL.

Thin transport: shared machinery is inherited

The Model-B orchestration (ADR 0030 §4) is inherited unchanged from DBIO::Storage::Async: the CRUD runner ("_run_crud" in DBIO::Storage::Async with its pooled / pinned runners), "txn_do_async" in DBIO::Storage::Async bracketing, the sql_maker plumbing and the sync ->get fallbacks. This class fills only the loop-/wire-specific seams and the genuine MySQL value-add:

Transport value-add

MySQL/MariaDB has no COPY, so -- unlike the PostgreSQL EV transport -- this transport carries no such wire value-add. EV::MariaDB pipelines queries automatically at the wire level (consecutive query calls are batched, up to 64 in flight) with no explicit pipeline-mode API to bracket; the core _pipeline_enter/_pipeline_sync/_pipeline_exit seam therefore does not apply and the pipeline capability is not declared (see "transport_capabilities"). The inherited $storage->pipeline is refused here: it returns a failed Future saying that this class does not support pipeline(), without taking a connection from the pool and without running the batch ("pipeline" in DBIO::Storage::Async, ADR 0009). MySQL/MariaDB has no native LISTEN/NOTIFY either; this transport emulates it and declares listen and notify for the emulation ("LISTEN / NOTIFY (emulated)"), next to on_connect_replay.

TLS and the event loop

Over TLS (ssl_cipher, ssl_ca, ssl_key, ssl_cert or ssl_capath in the DSN) statements run concurrently, like over plain TCP, because of a work-around in this transport. Without it they did not: libmariadb (3.4.9) leaves the socket of a TLS connection blocking, and its asynchronous TLS read and write then block in the kernel instead of suspending, so every query and prepare / execute held the whole event loop until the server had answered (docs/upstream/ev-mariadb-tls-blocks-the-loop.md, a draft, not sent). "_mysql_new_handle" in DBIO::MySQL::EV::Pool, where every handle of this distribution is made, now sets O_NONBLOCK on the socket in the handle's on_connect, and again after every reconnect, on every handle: the connect info does not tell whether TLS was negotiated, and over plain TCP the flag was measured to change nothing.

Limits, as measured on MySQL 8.0 and MariaDB 11: the connect and the TLS handshake itself still block the loop (the flag is set after them). close_async, finish and the TLS shutdown end at once, without an error, and the server's session is gone afterwards; a 6 MB result and a 5 MB bound parameter go through the non-blocking socket whole. Only the ssl parameters of the connect info are looked at: a session that ends up on TLS without one is not covered. Pinned by t/60-tls-nonblocking-socket-mock.t (the decision) and t/52-tls-concurrent-live.t (the effect, both servers).

LISTEN / NOTIFY (emulated)

listen, unlisten, notify, listen_alive and listen_reconnect are core async API (core ADR 0056), one contract on every async transport that declares listen / notify, documented once in "LISTEN / NOTIFY" in DBIO::Storage::Async. Core owns the channel registry, the one dedicated listen connection, reconnect with backoff, subscribing every channel again, and the fork guard. This class fills the seams.

MySQL and MariaDB have no LISTEN/NOTIFY, so this transport emulates it with a notify table and polling, through DBIO::MySQL::NotifyTable -- the part it shares with the future_io transport of the DBIO::MySQL distribution. The design and its reasons are dbio-mysql ADR 0008 (in that distribution's docs/adr/); how it is wired onto EV::MariaDB is this distribution's ADR 0010. notify inserts a row; the listen connection polls the table on an EV timer for rows new to it.

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

$async->on_listen_error(sub {
  my ($storage, $error) = @_;          # every error; without a hook it is warned
  $log->warn("listen: $error");
});
$async->on_listen_reconnect(sub {
  my ($storage) = @_;                  # rebuilt, every channel subscribed again
  $log->info('listen connection rebuilt -- re-read what may have been missed');
});

$async->deploy_notify_table            # once -- never created implicitly
  ->then(sub {
    $async->listen(jobs => sub {
      my ($channel, $payload, $sender_pid) = @_;   # $sender_pid: CONNECTION_ID()
      ...
    });                                # resolves once the mark is taken
  })
  ->then(sub {
    $async->notify(jobs => 'wake up'); # an INSERT on a pooled connection
  })
  ->retain;

EV::run;

The Futures are DBIO::MySQL::EV::Futures settled from the EV loop, like every other Future this transport returns: chain on them and run the loop, or call get, which runs the loop until the Future is ready ("future_class").

What the emulation delivers, and where it differs from a server push:

  • Latency is the poll interval ("notify_poll_interval", default 1 second): a notification arrives with the first poll after it became visible.

  • Delivery on commit. A notification becomes visible when the transaction that inserted it commits -- PostgreSQL's moment too. notify runs its INSERT on a pooled connection in autocommit, so it is visible at once; to notify transactionally, run "notify_sql" in DBIO::MySQL::NotifyTable inside your own transaction (txn_do_async).

  • No history, no replay. listen takes a mark before its Future resolves: a notification committed after that is delivered, nothing committed earlier is. A notification whose transaction was still open at that moment is delivered when it commits. Each listen connection takes new marks, so a reconnect loses what was committed while no connection listened; on_listen_reconnect is where to re-read state.

  • The lookback limit. Out-of-order commits are caught within "notify_lookback" seconds (default 60), each notification exactly once. A notification is lost when its transaction commits more than the lookback after its INSERT and a later notification on the same channel was delivered meanwhile ("How the out-of-order commit is caught" in DBIO::MySQL::NotifyTable).

  • Retention. The listen connection deletes rows older than "notify_retention" seconds (default 3600): one bounded DELETE ... LIMIT at most once a minute, back to back only while it clears a backlog ("Retention" in DBIO::MySQL::NotifyTable). A cleanup that fails on a live connection is reported through on_listen_error and tried again a period later; it does not end listening. notify_retention(0) turns it off for a deployment that prunes the table itself.

  • The table is "THE TABLE" in DBIO::MySQL::NotifyTable, named by "notify_table" (default dbio_notify). It is never created implicitly: deploy it with "deploy_notify_table", or run "create_table_sql" in DBIO::MySQL::NotifyTable from a migration. Until it exists, listen fails with a message naming the table and "deploy_notify_table", and notify with the server's error.

  • Privileges. The listening account needs SELECT and DELETE on the table (DELETE for the retention cleanup), a notifying one INSERT, and whoever deploys it CREATE.

  • Channels and payloads only ever travel as bind values. A channel is matched exactly and case-sensitively, at most 255 characters; a payload is at most 65535 bytes in UTF-8; both are refused beyond that, never truncated. An undef payload arrives as ''. They travel as EV::MariaDB sends and returns every string on this transport: bytes as given, results as bytes unless the connection info sets utf8 => 1 (with charset => 'utf8mb4', see "UNICODE" in EV::MariaDB) -- non-ASCII channel names need that setting to match.

  • The listen connection is a dedicated EV::MariaDB handle outside the pool, opened from the connect info a pool spawn would get at that moment (fresh AccessBroker credentials included). The pool's on_connect_do / on_connect_call replay does not run on it. It runs one statement at a time: a listen arriving while a poll is in flight waits for it, a poll tick that finds a statement running is skipped, and listen_alive reports a statement in flight as alive -- that statement reports a dead connection itself. Otherwise listen_alive checks the idle connection's socket without a round trip: an idle MySQL connection has nothing to read, so a readable socket means the server has hung up (KILL, a restart, wait_timeout). A peer that vanished without closing the connection is found by the next poll instead.

  • Fork. Core never touches the listen connection outside the process that opened it, and EV::MariaDB closes nothing when a forked child exits or drops its copy of the handle, so the parent's listen session survives. A child that resumes the EV loop would still share the parent's socket, and could read the reply to a poll that was in flight when it forked; the first thing such a child's loop does is disarm its copy of the handle, without touching the parent's session (ADR 0010). The pooled connections notify runs on carry the same guard ("pool").

ATTRIBUTES

notify_table

The notify table's name, a plain identifier (validated by "new" in DBIO::MySQL::NotifyTable). Default dbio_notify.

notify_poll_interval

Seconds between two polls of the listen connection: the latency of a notification. Default 1.

notify_lookback

Seconds a notification's transaction may stay open between its INSERT and its COMMIT and still be delivered after a later notification on the same channel ("LISTEN / NOTIFY (emulated)"). Default 60.

notify_retention

Seconds a row is kept before the listen connection's cleanup deletes it; 0 turns the cleanup off. Must exceed "notify_lookback" plus "notify_poll_interval". Default 3600.

All four are inherited class data seeded from "defaults" in DBIO::MySQL::NotifyTable: set them on the class for every connection, or on the async backend for one. They are read when the listen connection is opened and whenever a notify or "deploy_notify_table" builds its statement, so a change reaches listening from the next listen connection ("listen_reconnect" in DBIO::Storage::Async makes one). Invalid settings make the open throw before anything connects; core reports that and retries with backoff.

rollback_wait_timeout

Seconds a pinned ROLLBACK waits for the statements in flight on its connection before it gives up. Default 30; 0 or undef waits without limit. A statement in flight whose answer never comes would keep the ROLLBACK -- and with it the transaction and its connection -- waiting for ever. When the time is up the ROLLBACK is not sent, the connection is retired (it may still hold the transaction, see "_mysql_rollback") and the Future of the transaction fails with a DBIO::Exception naming the wait. inherited class data: set it on the class for every connection, or on the async backend for one.

METHODS

sql_maker_class

The DBIO::MySQL::SQLMaker subclass used to generate SQL. Shared with the sync driver, so the maker keeps emitting ? placeholders -- which MySQL/DBD understands natively ("_transform_sql" is identity).

_sql_maker_args

MySQL SQLMaker construction args: backtick identifier quoting, . name separator. (The MySQL LIMIT offset, rows pagination dialect is baked into DBIO::MySQL::SQLMaker itself.)

_post_insert_sql

Empty string -- MySQL has no RETURNING clause. The INSERT path ("_run_crud_pinned") reads SELECT LAST_INSERT_ID() on the pinned connection instead of appending a RETURNING suffix, so core's generic _run_crud insert branch (which consumes this seam) is never reached for this transport; the seam is defined only to satisfy the base contract.

future_class

Returns 'DBIO::MySQL::EV::Future': a Future subclass whose get on a pending Future runs the EV loop until it is ready (DBIO::MySQL::EV::Future). That is what makes the inherited blocking methods -- select, insert, txn_do, deploy, ... -- work: each is ->get on its *_async sibling, and a plain Future dies there instead of waiting (ADR 0001). The class reaches every Future such a method waits on: "pool" hands it to the pool, DBIO::MySQL::EV::QueryExecutor builds its query Futures from it, and Future's combinators keep it. A blocking call works from a script and from inside an EV callback, also inside a then on this transport's Futures and a txn_do coderef: those run from the idle watcher that settles the Futures, outside the callbacks of the EV::MariaDB handle, so a statement they send goes out at once (ADR 0001 addendum, "await" in DBIO::MySQL::EV::Future).

What is still refused is a blocking call that is queued for a pooled connection while the callbacks it runs inside hold every connection of the pool. In a txn_do coderef, $storage->select and its siblings run on a pooled connection, not on the transaction's -- that is what the context the coderef is handed is for -- and the transaction gives its connection back only after the coderef has returned. With a pool of one, or with every connection held by a transaction the call is nested in, the call would wait for a connection that cannot come back; it dies with "Blocking wait refused: ..." and does not run, and the transaction is rolled back. With a connection to spare, or one that a statement in flight will give back, it waits and returns.

Everything else is Future's own. ->then callbacks auto-wrap a non-Future return value into a resolved Future (ADR 0031 §4), so ResultSet/Row *_async callbacks that return plain values resolve without an explicit Future->done(...) wrap.

transport_capabilities

my @caps = DBIO::MySQL::EV::Storage->transport_capabilities;

Class method (see "transport_capabilities" in DBIO::Storage::Async). Declares the wire capabilities this transport really provides, so "_async_storage" in DBIO::Storage::DBI lets an async extension layer that requires any of them compose onto it (and croaks naming the gap otherwise, rather than silently dropping a feature). This transport provides only:

  • on_connect_replay -- its pool (DBIO::MySQL::EV::Pool, a DBIO::Storage::PoolBase) drives core's "_setup_pool_connection" in DBIO::Storage::Async on every freshly-spawned connection, and "_run_pool_connect_statement" replays the owning sync storage's on_connect_do/on_connect_call against it.

  • listen and notify -- the capability names core's LISTEN/NOTIFY gate asks for (core ADR 0056 section 2), declared for an emulation, which core ADR 0056 section 6 allows when the POD states latency and on-commit delivery, as "LISTEN / NOTIFY (emulated)" does.

  • broker_connect_options -- read by core, not by layers: the connect options given beside an DBIO::AccessBroker, MyApp::Schema->connect($broker, { async => 'ev', pool_size => 3, ... }), are handed on as [ $broker, \%options ] and applied to every connection this transport opens. pool_size sizes the pool. The DBD attributes are treated as the same keys are in DBI-form connect info: this transport has no DBD, so they are dropped and never reach EV::MariaDB ("connect_info"). A connection parameter there (charset, host, ...) is neither applied nor dropped: the connect info is refused. Without the declaration core refuses such a connection at first async use.

It does not declare copy (MySQL has no COPY), nor pipeline (EV::MariaDB pipelines automatically at the wire level; there is no explicit pipeline-mode API for the core seam to bracket, ADR 0009).

connect_info

$storage->connect_info([ \%conninfo, \%opts ]);

Set connection parameters. %conninfo is passed to EV::MariaDB as named connection parameters (host, user, password, database, ...). When the embedding sync storage feeds its own DBI-form connect info (['dbi:MariaDB:...', $user, $pass, \%attrs, \%extra_attributes]) it is translated into the async [ \%conninfo, \%opts ] shape first (EV::MariaDB cannot parse a DSN string). So is the single-hash form [ { dsn => ..., user => ..., password => ..., pool_size => 3, <attributes> } ]: every key but dsn, user, password and a nested attrs hash is an attribute, and neither dsn nor async is handed to EV::MariaDB. What the translation reads, and refuses -- an unknown DSN key, a connection parameter given as an attribute -- is told by "dbi_to_conninfo" in DBIO::MySQL::EV::ConnectInfo. A hash that is given directly ([ \%conninfo ], [ \%conninfo, \%opts ]) is EV::MariaDB's own parameters; a dbi:... DSN as its database name is refused, not read as a name. AccessBroker connect info ([ $broker ]) is detected and wired to the per-spawn credential provider (the inherited broker seam), exactly as the sync path does; what the broker answers is read by "_async_broker_conninfo", which croaks on an answer it cannot connect from.

A broker may come with the connect options the owning sync storage was given beside it, [ $broker, \%options ] -- the form core hands a transport declaring broker_connect_options ("transport_capabilities"). They are read through core's "_access_broker_call_options" in DBIO::Storage::Async, after what the owner applies itself (async, the storage options such as on_connect_do, the SQL maker options such as quote_names) is stripped:

  • pool_size sizes the pool. So does a pool_size in the broker's answer -- a key of its hash, or among the attributes of a DBI-form answer, in its fourth or fifth element, the later one winning. Given both in the answer and beside the broker, the two must be the same value, or this throws naming pool_size ("_access_broker_pool_size" in DBIO::Storage::Async). Given nowhere, the pool keeps its default of 5.

  • DBD attributes (mysql_enable_utf8mb4, mariadb_auto_reconnect, AutoCommit, RaiseError, ...) are dropped: there is no DBD on this transport to apply them, and EV::MariaDB croaks on an argument it does not know. In DBI-form connect info the DBD attributes are not dropped ("dbi_to_conninfo" in DBIO::MySQL::EV::ConnectInfo): the ones EV::MariaDB has a parameter for (mysql_enable_utf8mb4, ...) are translated, any other is refused. Beside a broker they are only kept apart, below. They change what the owner's DBI connection does and nothing about a pooled one. "_access_broker_call_attributes" in DBIO::Storage::Async answers what was dropped. What counts as one is told by its name, the way core tells it for the owning storage: a first letter in uppercase, or a start of private_, dbi_, dbd_, DBD::mysql's mysql_ or DBD::MariaDB's mariadb_ -- both DBD prefixes, since this transport is not told which of the two DBDs the owner connects with.

  • A connection parameter -- any other key set to a value: charset, utf8, connect_timeout, host, database, ... -- is refused. This throws, naming the parameters and never a value, and says where they belong. Every connection of this transport is opened from the broker's answer alone, so the parameter would not reach one; it is not dropped with the DBD attributes, which would leave the pool connecting without a ssl_verify_server_cert => 1 or host => ... beside a broker, and without a word. No list of EV::MariaDB parameters is kept: a lowercase name that is no DBI attribute is refused whether EV::MariaDB knows it or not. A key set to undef or the empty string names no parameter. Such a parameter is given in the broker's answer ("_async_broker_conninfo").

After that refusal nothing is opened through this storage without the parameter. The broker stays attached, no conninfo is stored -- not the one of a static connect_info before it either -- and every pool connection and every open of the listen connection is refused again, naming the parameters, until connect_info is given connect info without them. With the broker detached there is nothing to connect from.

Through a schema, MyApp::Schema->connect($broker, { async => 'ev', charset => ... }), the refusal comes when core builds this transport: at the first $schema->storage->async or *_async call, and at every later one. connect itself goes through: this transport is not there yet to refuse anything. The owning sync storage refuses the same options on its own account, when it opens its dbh, and the parts of the connection itself -- host, port, dbname, user, password, dsn -- already at connect ("_access_broker_call_info" in DBIO::Storage::DBI::AccessBroker).

No conninfo is kept from a broker's answer, as in core's "connect_info" in DBIO::Storage::Async. The answer is read once here -- to refuse one the transport cannot connect from, and for its pool_size, which sizes the pool -- and every connection asks the broker again, so a stored copy could only be that first answer, password included. A storage whose broker is detached afterwards has nothing to connect from until connect_info is called again: it does not fall back to what the broker once answered, nor to static connect info given before the broker. Static connect info is stored, being all a static connection is opened from.

This override (rather than the inherited base connect_info) is retained because the EV transport folds the DBI-form DSN into EV::MariaDB named params inline via "dbi_to_conninfo" in DBIO::MySQL::EV::ConnectInfo. It matches the base in every ownership-relevant respect: a truthy setter opens a new ownership generation (ADR 0045 section 4), rotating the context owner token via disconnect when a pool or a listen connection exists (the listen connection is closed, being opened with the old connect info) and via _rotate_context_owner_token otherwise, so a context from the previous generation cannot survive a reconfiguration even before a pool has been materialised.

_async_broker_conninfo

my $conninfo = $storage->_async_broker_conninfo($mode);
# { database => 'app', host => 'db1', port => 3306, user => ..., password => ... }

AccessBroker seam (see "ACCESSBROKER CONSUMPTION" in DBIO::Storage::Async): ask the attached broker for its current connect info -- anew each time, so rotated credentials reach the next connection -- and return it as the hash of EV::MariaDB named parameters the connection is opened from. Called for every new pool connection (through "_conninfo_provider" in DBIO::Storage::Async) and for every open of the listen connection ("_listen_open"), its first and every reconnect. "connect_info" reads the broker's answer the same way when the broker is attached, where a pool_size in it sizes the pool. Connect options given beside the broker change nothing in the conninfo: the DBD attributes among them never reach EV::MariaDB. A connection parameter among them stops the connection instead -- this croaks before the broker is asked, as "connect_info" did when it was given them. The answer may come in any of these shapes:

Anything else croaks, naming the shape it received -- never the values, which carry the password. That includes a DSN for another driver and any other string: EV::MariaDB takes named parameters only and parses no connection string.

So does an answer in one of these shapes that names neither a host nor a user: a hash holding only pool_size, or a database and a password, or undefined values for both; a DSN with a database only and no user beside it. EV::MariaDB starts a connect only when it is given one of the two; without either its handle stays unconnected and calls back neither on_connect nor on_error, so the pool's acquire would never resolve. One of the two is enough: what a connection needs beyond that is the server's to say. A broker that answers nothing at all -- undef, an empty hash or array -- is refused by core before this method reads the answer, naming the broker class ("current_access_broker_connect_info" in DBIO::Storage).

And so does a hash whose database name is a whole DSN: DBIO::AccessBroker::Static->new(dbname => 'dbi:mysql:database=app;host=db1', ...), the form core's sync storage takes as the DSN (DBIO::AccessBroker::Static). The broker still answers a hash, and this transport reads no DSN out of one: the DSN would be the name of the database and the host it names would not be given, so EV::MariaDB would connect to the client library's default -- the local server -- with the broker's user and password. The answer is refused at attach and for every connection after it, under a DBIO::AccessBroker::HostBound view too, whose host is not the one the DSN names; it is told by dbi: at the start of dbname, database or db, and the croak says nothing of the DSN. Have the broker answer the DSN in the DBI form, or the database name as dbname with host and port beside it. A schema connected from such a broker without { async => 'ev' } is not affected, and one connected with it gets the refusal at its first ->async or *_async call.

Croaks when no AccessBroker is attached -- one detached with "clear_access_broker" in DBIO::Storage while the per-spawn provider is still in place, on the storage or in a pool built with it. Core's seam "_current_async_connect_info" in DBIO::Storage::Async answers what "connect_info" stored then, and that is no broker's answer: the croak says that the broker is gone.

A hash answer, through a schema. A schema's broker is asked by two storages: this transport, and the owning sync storage for its dbh. The hash of EV::MariaDB parameters is this transport's shape only, and the sync storage takes less of it:

  • it needs a dbname (or a dsn): of a hash it builds dbname, host and port into its DSN, and an answer naming neither is refused when the schema is connected -- MyApp::Schema->connect throws. database, EV::MariaDB's own spelling, is not read there; dbname is read as database here;

  • it refuses a hash carrying any other parameter of the database client (charset, utf8, connect_timeout, ssl_ca, ...) when it is about to open its dbh, naming the broker class and the parameters: a DBD would keep such a key without a word and connect without it. connect and ->async go through, and the pool opens its connections with the parameter; what throws is the first call that needs the owner's dbh -- every sync call, and with the core this was written against (0.900004) select_async and the ResultSet reads on the schema as well.

So a schema's connections get such a parameter from an answer by the storage that asks ("connect_info_for_storage" in DBIO::AccessBroker): the hash with the parameter for a DBIO::MySQL::EV::Storage, an answer the sync storage takes for every other. One DSN for both halves carries it only under DBD::mysql, which ignores a DSN parameter it does not know (and so does not apply it to the dbh); DBD::MariaDB refuses one (Unknown attribute charset, measured with DBD::MariaDB 1.24 and DBD::mysql 4.055). The transport given the broker directly, $storage->connect_info([ $broker ]), takes the hash with any EV::MariaDB parameter as before: no sync storage reads the answer then.

_normalize_async_connect_info

my ($conninfo, $pool_size, $opts) = $storage->_normalize_async_connect_info($info);

MySQL-specific override of the base normaliser: besides stripping pool_size out of the conninfo, it maps dbname to database (EV::MariaDB's spelling) so a hash-form connect that used the DBI-style dbname key still reaches the native client correctly. Works on copies so the caller's structures are never mutated.

_conninfo_hash

my $conninfo = $storage->_conninfo_hash;

Returns the already-normalised stored EV::MariaDB conninfo hashref (or a passed override). Normalisation (dbname->database, pool_size extraction) is done once in "_normalize_async_connect_info", so this returns it as-is.

Only static connect info is stored. undef when there is none: no connect info was given yet, or an AccessBroker is attached -- "connect_info" keeps nothing of its answer, and what a connection is opened from is "_async_broker_conninfo"'s to say, anew each time.

pool

Returns the DBIO::MySQL::EV::Pool connection pool, created lazily on first access. The pool is wired with storage => $self so its core-shared spawn path ("_spawn_connection" in DBIO::Storage::PoolBase) replays the owning sync storage's connect actions on each new connection via "_run_pool_connect_statement". Fed the per-spawn conninfo_provider when an AccessBroker is attached, otherwise the static conninfo hash. With neither -- no connect info was given yet, or a broker and its provider are gone ("_clear_access_broker" in DBIO::Storage::Async) -- there is nothing to build a pool from, and this croaks ("new" in DBIO::Storage::PoolBase).

A forked child that resumes the EV loop leaves the pool's sessions to the parent: the pool finishes the child's copies of its connections -- checked out and pinned ones included -- before the child's loop reads anything, and no callback of a statement that was in flight at fork time runs in the child ("_create_connection" in DBIO::MySQL::EV::Pool, ADR 0010).

_mysql_mask_error

my $text = DBIO::MySQL::EV::Storage::_mysql_mask_error($text, \@values, $sql, $code);

The error masker of this transport's executor (ADR 0075 of the core: a message names keys, columns and options, never a value). MySQL and MariaDB write the offending value into their text -- Duplicate entry 'x' for key 'k', Incorrect integer value: 'x' for column 'i', the near '...' of a syntax error -- bound or not. It answers the text with the value replaced by *** and the type, the column, the key and the position left, by "mask_error_details" in DBIO::MySQL::Util (the sentences of the engine, the quoted literals of a syntax excerpt, the bound values found elsewhere) and then "mask_bound_values" in DBIO::Util. It is the one mask for every way a statement's error reaches a Future or an exception here: the executor (_query_async, insert_async and its LAST_INSERT_ID(), the pinned statements of a transaction and its ROLLBACK/COMMIT, the session reset, the connect actions of "_run_pool_connect_statement", deploy_async, the notify INSERT) and the statement runner of the listen connection (_mysql_listen_done_cb). \@values are plain values (the executor hands over the bound ones of four characters or more); the SQLSTATE of the exception is not a part of the text and stays.

$code is the error number of the server (1062, 1366, ...), optional: the server words its text in the language of its session (lc_messages), and with the code "mask_error_details" in DBIO::MySQL::Util masks the text by the code and not by the wording, so a short value is out of a German or French text as well. The executor reads it from the handle while the handle holds the error of the statement ("_handle_code" in DBIO::MySQL::EV::QueryExecutor); no code is the masking by the wording alone.

It is a function and not a method on purpose: it asks no storage and so never connects a dbh of the owning sync storage. It never throws -- a text it cannot treat is answered as it is, and so is anything that is no text (an exception object).

_txn_context_class

The pinned-connection transaction context the inherited "txn_do_async" in DBIO::Storage::Async hands to its coderef: DBIO::MySQL::EV::TransactionContext -- a thin subclass of core's generic DBIO::Storage::Async::TransactionContext that inherits the whole context surface and adds only the txn_mdb alias for txn_conn.

_txn_conn_accessor

The constructor key the pinned connection is passed under -- txn_conn, the core key DBIO::MySQL::EV::TransactionContext now inherits from DBIO::Storage::Async::TransactionContext. The handle goes under that key, not under a private one such as mdb, which core's own callers do not know: the transactional branch of "deploy_async" in DBIO::Storage::Async reads $ctx->txn_conn. MySQL COMMITs DDL implicitly, so "_ddl_class"'s deploy never takes that branch (ADR 0026).

_ddl_class

The install-DDL generator the inherited "deploy_async" in DBIO::Storage::Async resolves through "_install_ddl" in DBIO::Storage::Async: DBIO::MySQL::DDL -- the very class the sync MySQL deploy pipeline uses ("_ddl_class" in DBIO::MySQL::Deploy), so async and sync deploy emit byte-identical MySQL DDL. Filling this seam is all the transport needs: core's generic deploy_async then runs every generated statement over the "_query_async_pinned" seam this class already implements for CRUD.

The DDL batch is deliberately not wrapped in a transaction. MySQL implicitly COMMITs each DDL statement, so the inherited deploy_async takes its non-transactional branch (ADR 0026) -- statement-at-a-time on one pooled connection, with a one-shot warning naming this class. A deploy that fails half-way therefore leaves the already-executed statements behind; re-run with add_drop_table => 1 to get back to a known state.

_ddl_quote_ident

my $quoted = $storage->_ddl_quote_ident($name);

The identifier $name as the MySQL DDL writes it: between backticks, through "quote_ident" in DBIO::MySQL::Identifier, so a reserved word (order) or a name that is no plain word (my-table) is valid. Core's "_drop_statements_for" in DBIO::Storage::Async, the add_drop_table pre-pass of "deploy_async" in DBIO::Storage::Async, writes every view and table name through it.

_transform_sql

Transport-internal SQL shaping (ADR 0032). Identity for MySQL: MySQL/DBD speaks the ? placeholder dialect natively, so the sql_maker output needs no rewrite. The seam is retained (and applied first by "_query_async" / "_query_async_pinned") purely to keep the transport seam contract uniform across drivers -- do not reintroduce a dialect rewrite here.

_query_async

Transport seam. Execute a query on a freshly-acquired pooled connection, releasing it once the Future is ready. Returns a Future of the raw result rows (list of column arrayrefs for a result set, or the affected-row count for plain DML -- ADR 0031 §3), exactly what the inherited _run_crud expects.

The dispatch, "_await_query_result", goes through core's "_seam_future" in DBIO::Storage::Async: the release hangs off the Future the dispatch returns, so there has to be one. A dispatch that dies before it returns a Future -- EV::MariaDB croaks from prepare and query, with "another operation is in progress", "not connected" and the like -- fails the returned Future with that error. One that returns no Future at all -- undef, a plain value -- fails it with an error naming the backend class and _await_query_result. Either way the connection is released at once; kept checked out instead, a pool of N would be wedged for good after N such calls.

A connection that failed because it is gone is not reused: the pool is told before the release, retires it instead of idling it, and the next call -- or a caller already queued for the slot -- gets a newly opened connection (see "_mysql_execute"). A statement error the session survives -- a syntax error, a duplicate key, EV::MariaDB refusing a busy handle -- leaves the connection in the pool.

A caller that cancels the returned Future -- or loses it in a wait_any against a timeout -- stops waiting, and nothing else: EV::MariaDB is not told, the statement is answered all the same, and a statement with bind values still has its execute and close_stmt to go. The connection stays checked out until the dispatch has settled, and is released then, once. Released at the cancel, it would be idle with an operation in flight, and EV::MariaDB would refuse the next caller's prepare ("another operation is in progress"). So the cancel stops at the Future the caller holds and never reaches the dispatch ("_mysql_caller_future").

Receives SQL in the sql_maker ?-placeholder dialect and shapes it via "_transform_sql" (identity for MySQL) before it reaches the executor -- the ADR 0032 seam contract.

_mysql_caller_future

my $future = $storage->_mysql_caller_future($dispatch);

The Future a pooled call hands its caller for $dispatch, the Future of what runs on the pooled connection, whose settling releases that connection ("_query_async", "insert_async"). It settles as $dispatch does, but a cancel of it stops there ("without_cancel" in Future): Future.pm carries a cancel down a then chain, and a cancelled $dispatch is ready at once -- its connection would be released with an operation still in flight.

$dispatch is retained until it settles. With the caller gone nothing else may hold it -- "insert_async"'s is the end of a then chain, which Future.pm holds weakly -- and a dispatch that is freed never releases its connection.

A Future that is not a Future.pm one cannot be cancelled either, and is returned as it is.

The other half of the rule: the $pool->acquire->then(...) sequence a pooled call returns is held (_hold_derived) until it is done, because Future.pm holds it only weakly from the acquire Future still waiting for the pool, and a caller that lets go of it there would lose the chain and the connection.

_await_query_result

my $future = $storage->_await_query_result($conn, $sql, $bind, $bind_attrs);

The pooled dispatch of "_query_async": hand the already shaped statement to the executor on $conn ("_mysql_execute") and return its Future of the result. It shapes nothing and releases nothing. A method of its own, not a line inside "_query_async", because "_seam_future" in DBIO::Storage::Async takes the dispatch by name -- and names it in the error when it returns no Future.

_mysql_execute

my $future = $storage->_mysql_execute($conn, $sql, $bind, $dispatch, $bind_attrs);

Hand one shaped statement to the executor ("execute" in DBIO::MySQL::EV::QueryExecutor) on $conn and return its Future -- the one place both dispatches, pooled ("_await_query_result") and pinned ("_query_async_pinned"), reach the wire through.

A statement that fails has the pool told when its connection is gone ("_mysql_report_if_gone" in DBIO::MySQL::EV::Pool): whether it failed through its callback, or EV::MariaDB refused to dispatch it and the executor died (that error is rethrown unchanged). The report is the first thing the failed Future runs, so it is made before anything hands the connection back -- the pooled release of "_query_async" and "insert_async", or core's at the end of a transaction and of deploy_async, whose connection is released by core and can be reported from here only. The pool then retires the connection at that release instead of putting it back, where it would be handed out again and fail every caller the same way.

What tells a gone connection from a statement error is the handle, not the message: "_mysql_connection_gone" in DBIO::MySQL::EV::Pool. A session the server ended while the connection sat idle is not handed out in the first place ("_idle_connection_alive" in DBIO::MySQL::EV::Pool); one that ends after the pool looked, or without the server saying so, is found by the first statement sent on it: that statement fails, and this retires the connection. A statement that succeeds is never asked about.

The callback is built by a named sub, as "_release_on_ready" is and for the same reason (ADR 0044): it holds the connection for the flight, never the bind values.

The text of a statement that fails has its values taken out ("_mysql_mask_error") by the executor before the exception exists, also the text of a dispatch EV::MariaDB refuses, which is rethrown masked.

The statement is traced here, once, by the core's "_debug_query" in DBIO::Storage::Async (core ADR 0025) with the optional $bind_attrs of "_query_async"; its query_end runs when the Future is ready, failed or done. The pinned ROLLBACK/COMMIT and the COM_RESET_CONNECTION of a reset are traced the same way, as raw statements. The executor traces nothing, the connect actions of a new connection and the listen connection's statements are not traced.

_release_on_ready

my $cb = $storage->_release_on_ready($conn, $pool, $lease);

Build the pool-release callback for a query Future. It releases $conn to $pool, the pool it was acquired from -- never to "pool" asked again, which builds a new pool on a storage disconnected while the statement was in flight -- and passes $lease, $pool->_lease($conn) taken right after the acquire: a callback that runs a second time, once the connection went on to another caller, releases nothing.

A named sub, deliberately not a closure inside the ->then(sub {...}) acquire chain (ADR 0044): the callback is created HERE, in a sub whose pad dies when this sub returns, so the bind arrayref lives only until dispatch, not for the whole flight of the query. A callback created inside the ->then closure would be retained by the executor's Future for the flight and would pin that closure's pad -- and $bind -- alive via CvOUTSIDE.

_query_async_pinned

Transport seam. Like "_query_async" but runs on the supplied pinned connection and does not release it -- used for queries inside a pinned transaction and for the INSERT + LAST_INSERT_ID() pair (which must ride the same session). Shapes the incoming ?-dialect SQL via "_transform_sql" exactly as "_query_async" does.

A statement that fails on a connection that is gone reports it to the pool ("_mysql_execute"), so a transaction whose connection died in the middle has it retired when core hands it back, not returned to the idle list.

The two statements that end a transaction do not go through "_mysql_execute" directly. ROLLBACK goes through "_mysql_rollback": it waits for the statements in flight on the connection. COMMIT goes through "_mysql_commit". Every other statement is queued behind a prepare or an execute in flight on the connection, where EV::MariaDB would refuse it: see "execute_after_exclusive" in DBIO::MySQL::EV::QueryExecutor. Either end of a transaction that does not succeed retires the connection: one that may still hold a transaction never goes back to the pool.

_mysql_rollback

my $future = $storage->_mysql_rollback($conn, 'ROLLBACK', []);

The ROLLBACK of a pinned connection, what "_query_async_pinned" sends for it instead of "_mysql_execute". Two things differ.

It waits for the statements in flight on the connection. EV::MariaDB takes no query while a prepare or an execute is in flight, and a transaction ends that way whenever its coderef dies, its Future fails or one of its statements was cancelled while a statement with bind values was still on the wire. The ROLLBACK is handed over only after the last of them has settled and its statement is closed ("execute_when_idle" in DBIO::MySQL::EV::QueryExecutor): one order per pinned connection, so the transaction ends later than it would have. A connection with nothing in flight gets it at once, as before.

The wait has a limit: "rollback_wait_timeout" seconds, default 30. A statement whose answer never comes must not keep the transaction and its connection for ever. When the time is up the ROLLBACK is not sent, the Future fails with a DBIO::Exception naming the wait, and the connection is retired like one whose ROLLBACK failed (below).

A ROLLBACK that does not succeed retires the connection. Whether refused at dispatch or failed by the server or the client library, the session may still hold the transaction, and a connection with an open transaction must never go back to the pool: the next BEGIN there would commit it. The connection is reported to the pool as dead ("_mark_connection_dead" in DBIO::Storage::PoolBase), which retires it when core hands it back, and a caller queued for the slot gets a newly opened one.

_mysql_commit

my $future = $storage->_mysql_commit($conn, 'COMMIT', []);

The COMMIT of a pinned connection, what "_query_async_pinned" sends for it instead of "_mysql_execute". Core sends it only after every statement the transaction's context handed out has settled, so there is nothing of the transaction to wait for; like every other statement it is queued behind a prepare or execute that a statement sent past the context left in flight.

A COMMIT that does not succeed retires the connection, as a ROLLBACK that does not succeed does ("_mysql_rollback") and for the same reason: whether the server failed it or EV::MariaDB refused to take it (an operation sent on the connection past the context is in flight), nobody knows whether the transaction is still open, and a connection with an open transaction must never go back to the pool. The error the caller gets is unchanged -- core's COMMIT failed: ..., or the refusal -- and the next call runs on a newly opened connection.

_reset_pool_connection

my $future = $storage->_reset_pool_connection($conn);

Core's session-reset seam ("_reset_pool_connection" in DBIO::Storage::Async, core ADR 0079), asked by the pool when a borrow, a transaction or a pipeline ends. It makes $conn a connection like a freshly spawned one, in three steps that follow each other:

  1. COM_RESET_CONNECTION ("reset_connection" in EV::MariaDB, "reset_connection" in DBIO::MySQL::EV::QueryExecutor). The server drops what the session of the borrower held: user variables (@x), session variables (SET SESSION ..., sql_mode included, which fall back to the server's global values), temporary tables, prepared statements, locks taken with GET_LOCK, and an open transaction.

  2. SET NAMES <character set> COLLATE <collation> with the two names the connection had when it was new ("_setup_pool_connection"): the session starts again with the character set and the collation of the new connection, on MySQL and on MariaDB.

  3. The connect actions again -- the connection's schema, on_connect_call, on_connect_do -- through "_setup_pool_connection" in DBIO::Storage::Async, which puts back the session settings every connection of this storage starts with.

The Future resolves after all three have answered; the pool hands the connection on only then. A reset the server refuses, a connect action that fails, or no answer within the pool's reset_timeout fails it, and the pool retires the connection: the next borrower gets a newly opened one. There is no way to turn the reset off. The statements of the connect actions run as they do on a new connection, one after the other, and block the EV loop while they do ("_run_pool_connect_statement"); a storage without connect actions sends the reset and the SET NAMES, one without an owning sync storage only the reset.

Every borrow therefore has the session of the new connection, character set and collation included: the transport reads character_set_client and collation_connection once per connection, in one statement after the connect actions of its spawn, and sets both again after every reset. A name the server answers that is not made of letters, digits and underscores is refused (the connection is not used; the error names no value).

A reset that fails because the connection is gone reports it to the pool ("_mysql_execute"), as a failed statement does. The error is the client library's or the server's; it names no statement, bind value or credential.

_setup_pool_connection

$storage->_setup_pool_connection($conn);

Core's per-spawn seam ("_setup_pool_connection" in DBIO::Storage::Async): the connect actions of the owning sync storage run on the new connection, then one statement reads its character_set_client and collation_connection. Both names are kept per connection for "_reset_pool_connection", which sets them again after every reset. A no-op without an owning sync storage, as the core seam is. A name that is not made of letters, digits and underscores makes the call die, without quoting it.

insert_async

my $future = $storage->insert_async($source, \%vals);

Resolve the returned-columns hashref -- the supplied insert data overlaid with the auto-increment PK the engine populated (ADR 0031 §3). MySQL has no RETURNING clause, so the INSERT and a following SELECT LAST_INSERT_ID() must run on the same session: this override acquires one pooled connection, runs the whole insert pinned on it via "_run_crud_pinned", and releases it when the Future settles. (The base insert_async uses the pooled runner, which would acquire a fresh connection per query and read a foreign session's LII.)

"_run_crud_pinned" is called through core's "_seam_future" in DBIO::Storage::Async, as the dispatch of "_query_async" is. An insert that dies before it has a Future -- SQL generation throwing, a conflict target MySQL cannot honour say, or a croaking prepare -- fails the Future with that error. A _run_crud_pinned that returns no Future at all -- an override in a subclass or a composed layer answering undef or a plain value -- fails it with an error naming the backend class and _run_crud_pinned. Either way the connection is released at once.

An insert that finds its connection gone -- at the INSERT or at LAST_INSERT_ID() -- has it retired at that release, and the next call gets a newly opened one ("_mysql_execute").

A cancel of the returned Future does not reach the insert ("_mysql_caller_future"): the INSERT is answered, its statement closed and LAST_INSERT_ID() read as if nobody had cancelled, and the connection is released after the last of them, once. A cancelled insert is not undone, and it may well have inserted its row.

_run_crud_pinned

my $future = $storage->_run_crud_pinned($op, $conn, @args);

Build SQL and run a CRUD op on a pinned connection (the entry point the DBIO::MySQL::EV::TransactionContext and "insert_async" use). For every op except insert this delegates to the inherited runner. The insert op is the MySQL value-add: it runs the INSERT and then SELECT LAST_INSERT_ID() on the same $conn (so the session-scoped LII is the one the INSERT produced), captures it for legacy "last_insert_id" callers, and folds it into the returned-columns hashref via "_insert_returned_columns".

An upsert (on_conflict in the options) is planned by the owning sync storage's _mysql_upsert_plan, handed the hint returning => 0 -- this transport reads LAST_INSERT_ID(), never RETURNING -- on a copy of the options. The whole plan counts, as in the sync insert: where the row cannot be named and the caller asked for it, the primary key columns are taken out of the returned hashref and the plan's reason is reported once with carp_once, so the upsert resolves undef; with no_retrieve (result => 'void' or 'count') nothing is withheld.

An auto-increment value of 0 in the row data is generate to the server, so it counts as not supplied -- for the plan and for the returned columns, where LAST_INSERT_ID() is then the id -- unless the session's sql_mode has NO_AUTO_VALUE_ON_ZERO, where the 0 is a value and is kept. The sql_mode is read with SELECT @@SESSION.sql_mode on the pinned connection before the INSERT, and only for a 0. The sync insert of DBIO::MySQL::Storage keeps a supplied 0 as core does.

_insert_returned_columns

$hashref = $storage->_insert_returned_columns($source, \%to_insert, $lii_row);

Assemble the returned-columns hashref from a SELECT LAST_INSERT_ID() row (ADR 0031 §3). MySQL has no RETURNING clause, so the INSERT path captures the LII on the pinned connection and hands the single-column row to this method. The hashref is { %$to_insert, $col => $lii_id }, where $col is the source's first is_auto_increment column (falling back to the first PK column whose value was not supplied, matching the sync "insert" in DBIO::Storage::DBI heuristic). A value the caller supplied for that column (defined, not a literal) is kept as it is: LAST_INSERT_ID() says nothing about it. Overrides the inherited default that maps a positional RETURNING row onto a column list.

_run_pool_connect_statement

$storage->_run_pool_connect_statement($conn, $sql, $attrs, @bind);

Native-backend override of the core connect-action runner seam ("_run_pool_connect_statement" in DBIO::Storage::Async). The base default drives a blocking DBI do and croaks on a non-DBI connection; an EV::MariaDB handle is neither a { dbh => $dbh } wrapper nor a do-capable DBI handle, so this override drives the statement synchronously to completion on that connection over the EV loop.

Called once per freshly-spawned pool connection from "_setup_pool_connection" in DBIO::Storage::Async, so the owning sync storage's on_connect_do / on_connect_call replay on every new EV pool connection, identical to the DBD-based pools. The freshly-spawned EV::MariaDB handle connects asynchronously, so we first drive the loop until the pool's readiness Future for that connection settles -- a connect that fails rethrows here rather than leaving the runner spinning -- then run the statement and drive the loop until it completes. The statement runs through DBIO::MySQL::EV::QueryExecutor, as every other statement of this transport: bindless statements (the usual SET ... connect actions) go on the queueable query path, a bound one is prepared, executed and closed again. $attrs (the DBI attribute hashref) has no EV::MariaDB analogue and is ignored, with one key: dbio_rows => 1 (core's contract for reading a query at connect time, e.g. in a connect_call_*) makes the runner return the rows of the statement as an array reference of row array references (empty for an empty result). Without it nothing is returned.

_listen_open

my $f = $storage->_listen_open;   # done with the listen connection

Core listen seam ("_listen_open" in DBIO::Storage::Async): open the dedicated listen connection -- a new EV::MariaDB handle, never one from the pool -- and resolve once it is connected. Its connect info is what a pool spawn would get at this moment: fresh credentials through "_conninfo_provider" in DBIO::Storage::Async when an AccessBroker is attached, otherwise the stored static conninfo; with neither, it croaks. So it does for connect info that names neither a host nor a user: EV::MariaDB starts no connect then and would call back nothing. The pool's connect-action replay does not run on it.

The connection carries a fresh DBIO::MySQL::NotifyTable built from the "notify_table" settings: the marks of this connection, which a reconnect therefore takes anew. Invalid settings throw here, before anything connects. A connect that fails fails the Future; a connection-level error the handle reports later goes to "_listen_lost" in DBIO::Storage::Async. The handle is made where the pool's are ("_mysql_new_handle" in DBIO::MySQL::EV::Pool), so neither message quotes a password.

Fork safety. EV::MariaDB records the process that connected and closes nothing when a forked child exits or drops its copy, so the parent's session survives the child. A child that resumes the EV loop, though, would still have the handle's watchers armed on the shared socket and could read the reply to a statement that was in flight when it forked. An "fork" in EV watcher kept with the connection therefore finishes the child's copy before the child's loop runs anything else -- EV::MariaDB's fork-aware close, which leaves the parent's session alone (ADR 0010). The watcher never keeps the loop running (keepalive(0)): after it fired in a child it would otherwise keep the child's EV::run from ever returning.

_listen_close

$storage->_listen_close($conn);

Core listen seam ("_listen_close" in DBIO::Storage::Async): close the listen handle with EV::MariaDB's synchronous finish, which also tolerates a dead connection and one with a statement still in flight (core has stopped the watch first, so its result is not delivered). Statements still waiting for the handle fail. Also drops the fork watcher: a connection that is closed has nothing left to disarm.

_listen_subscribe

my $f = $storage->_listen_subscribe($conn, $channel);

Core listen seam ("_listen_subscribe" in DBIO::Storage::Async): take the channel's mark ("subscribe_sql" in DBIO::MySQL::NotifyTable) on the listen connection and resolve once it is in effect -- so a notify after listen resolved is delivered. A statement in flight is waited for first. The channel is validated here and travels as a bind value; a channel it refuses makes the seam throw, and a missing notify table fails it with a message naming the table and "deploy_notify_table". Either way core finds the connection alive, drops the channel and fails its listen Future with the reason. The mark is taken on the listen connection, not a pooled one, so that a failure means this connection's failure when core probes it (dbio-mysql ADR 0008 section 6).

_listen_unsubscribe

my $f = $storage->_listen_unsubscribe($conn, $channel);

Core listen seam ("_listen_unsubscribe" in DBIO::Storage::Async): stop polling the channel. Local bookkeeping only ("unsubscribe" in DBIO::MySQL::NotifyTable); rows for it that a poll already in flight brings back are dropped.

_listen_watch

$storage->_listen_watch($conn);

Core listen seam ("_listen_watch" in DBIO::Storage::Async), timer-driven: an EV timer fires after the connection's poll interval ("notify_poll_interval" as it stood when the connection opened); the tick runs one poll of the notify table ("poll_sql" in DBIO::MySQL::NotifyTable) on the listen connection, hands what is new to "_listen_dispatch" in DBIO::Storage::Async in order, runs the retention cleanup when one is due, and only then arms the timer again -- so polls never overlap and never queue up behind a slow one. A tick that finds a statement running or waiting on the connection (a subscribe's mark) skips its poll and arms again.

A failed poll is a dead connection and goes to "_listen_lost" in DBIO::Storage::Async, as does any other error in a tick. A failed cleanup goes there too when "_listen_probe" finds the connection dead; on a live connection it is reported through "_listen_error" in DBIO::Storage::Async and polling goes on (a listener without DELETE, say). The first poll runs one interval after the watch starts, never from inside this call.

_listen_unwatch

$storage->_listen_unwatch($conn);

Core listen seam ("_listen_unwatch" in DBIO::Storage::Async): stop the poll loop. The watch state is taken off the connection, which drops its timer; a poll or cleanup still in flight completes on the handle, finds the watch gone and delivers and reports nothing.

_listen_probe

my $alive = $storage->_listen_probe($conn);

Core listen seam ("_listen_probe" in DBIO::Storage::Async), asked by "listen_alive" in DBIO::Storage::Async and after a failed subscribe. Synchronous and without a round trip:

  • a statement in flight: alive, without touching the handle -- a ping then would die in EV::MariaDB (it is exclusive), and the statement reports a dead connection itself;

  • no socket (EV::MariaDB gives it up when an operation finds the connection gone): dead;

  • otherwise the idle socket must have nothing to read. A MySQL server never speaks unasked, so a readable idle socket is the server hanging up -- a KILL, a restart, wait_timeout -- and means dead. The check is the pool's, "_mysql_connection_gone" in DBIO::MySQL::EV::Pool, so the two cannot disagree (an interrupted select is asked again there).

EV::MariaDB's is_connected is not consulted: it stays true after the server killed the session and even after an operation failed on it. Its ping is not used either: it is asynchronous, so a synchronous probe would have to run the event loop from inside listen_alive (ADR 0010).

_listen_delay

my $f = $storage->_listen_delay($seconds);

Core listen seam ("_listen_delay" in DBIO::Storage::Async): the reconnect backoff, an "timer" in EV wrapped in a Future. It resolves from the EV loop, and cancel stops the timer.

_notify_send

my $f = $storage->_notify_send($channel, $payload);

Core listen seam ("_notify_send" in DBIO::Storage::Async): run "notify_sql" in DBIO::MySQL::NotifyTable -- an INSERT with channel and payload as bind values, CONNECTION_ID() as the sender -- on a pooled connection through "_query_async", in autocommit. Throws on an invalid channel, payload or "notify_table", which fails the Future of "notify" in DBIO::Storage::Async.

deploy_notify_table

$storage->deploy_notify_table->then(sub { ... });

Create the notify table ("create_table_sql" in DBIO::MySQL::NotifyTable, CREATE TABLE IF NOT EXISTS) on a pooled connection; a Future that resolves once it exists. Nothing creates it implicitly: it is DDL, which MySQL commits implicitly, and a schema change is the deployer's call. Fails for an invalid "notify_table".

last_insert_id

my $id = $storage->last_insert_id;

Returns the auto-increment value from the last INSERT performed on this storage instance (captured from SELECT LAST_INSERT_ID() by "_run_crud_pinned"). Valid after insert_async or the sync insert succeeds.

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.