arcadedb.aio.AsyncDatabase: await query, command, run_in_transaction and find_nearest from async def code (refs #306) - #379

What does this PR do?

The asyncio facade of #306, item 1, as the owner decided on the issue. arcadedb.aio.AsyncDatabase(db, max_workers=8) wraps an open Database and owns a bounded thread pool of its own.

• await adb.query(...) and await adb.command(...) run the blocking call on a worker and return the rows as a list of dict (ResultSet.to_list()), or None for a command that has no result set.
• await adb.run_in_transaction(fn, retries, backoff_s) runs the plain function fn from begin to commit, with every retry, on one worker. A transaction belongs to its thread and two awaits of one task can run on two workers, so there is no async with transaction. An exception of fn rolls back and reaches the awaiting task.
• await adb.find_nearest(index, query_vector, k, ...) runs index.find_nearest. await adb.run(fn, *args) runs any function.
• Cancellation is not exposed. Cancelling the awaiting task abandons the result, a call that started finishes, a call still waiting for a worker does not run. await adb.close() refuses new calls and waits for the ones that were submitted, the queued ones included, without blocking the loop. It does not close the Database.
• The docstring and the docs page say how AsyncDatabase differs from the engine's AsyncExecutor (db.async_executor()).

The module is one file of the shared tree, so both wheels carry it. New page how-to/asyncio.adoc (its Python blocks run in tests/test_docs_asyncio_page.py), a nav entry, and pointers from the concurrency, vectors and async-executor pages.

Tests on both wheels (CI runs them): tests/test_aio.py has rows and errors reaching the task, commit on one worker, rollback on an exception with the worker usable afterwards, 200 tasks writing and reading at once with no lost update, the pool running max_workers calls at once (a barrier) and never more, close() waiting for a running call and for queued ones and refusing new calls, both cancel cases, context variables, and the max_workers check. The two read-your-writes tests of #373 now also run through the facade. I ran the pool, close and cancel logic once without the engine to check the tests' own logic. The engine-side tests run in CI only.

Related issues

Refs #306. Items 3 (numpy in, arrays out) and 4 (collection size, graph index) still need measurements, so no closing keyword.

Docs

how-to/asyncio.adoc (new), nav.adoc, and one sentence each in how-to/concurrency.adoc, how-to/vectors.adoc and how-to/async-executor.adoc.

Checklist

• A regression test fails on the old code and passes on the new: this is a new module, so its tests fail on main with an import error.
• The test suite that the change can affect passes: CI runs it on both wheels.
• uvx pre-commit run --files <changed files> passes.

🤖 Generated with Claude Code