AsyncIO API​

Create an asynchronous client with a lazy connection pool.

The connection parameters may be specified either as a connection URI in dsn, or as specific keyword arguments, or both. If both dsn and keyword arguments are specified, the latter override the corresponding values parsed from the connection URI.

If no connection parameter is specified, the client will try to search in environment variables and then the current project, see Client Library Connection docs for more information.

Returns a new AsyncIOClient object.

The APIs on the returned client instance can be safely used by different asyncio.Task/coroutines, because under the hood they are checking out different connections from the pool to run the queries:

• AsyncIOClient.query()

• AsyncIOClient.query_single()

• AsyncIOClient.query_required_single()

• AsyncIOClient.query_json()

• AsyncIOClient.query_single_json()

• AsyncIOClient.query_required_single_json()

• AsyncIOClient.execute()

• AsyncIOClient.transaction()

client = edgedb.create_async_client()
await client.query('SELECT {1, 2, 3}')

The same for transactions:

client = edgedb.create_async_client()
async for tx in client.transaction():
    async with tx:
        await tx.query('SELECT {1, 2, 3}')

An asynchronous client with a connection pool, safe for concurrent use.

Async clients are created by calling create_async_client().

Acquire a connection and use it to run a query and return the results as an edgedb.Set instance. The temporary connection is automatically returned back to the pool.

Note that positional and named query arguments cannot be mixed.

Acquire a connection and use it to run an optional singleton-returning query and return its element. The temporary connection is automatically returned back to the pool.

The query must return no more than one element. If the query returns more than one element, an edgedb.ResultCardinalityMismatchError is raised, if it returns an empty set, None is returned.

Note, that positional and named query arguments cannot be mixed.

Acquire a connection and use it to run a singleton-returning query and return its element. The temporary connection is automatically returned back to the pool.

The query must return exactly one element. If the query returns more than one element, an edgedb.ResultCardinalityMismatchError is raised, if it returns an empty set, an edgedb.NoDataError is raised.

Note, that positional and named query arguments cannot be mixed.

Acquire a connection and use it to run a query and return the results as JSON. The temporary connection is automatically returned back to the pool.

Note, that positional and named query arguments cannot be mixed.

Acquire a connection and use it to run an optional singleton-returning query and return its element in JSON. The temporary connection is automatically returned back to the pool.

The query must return no more than one element. If the query returns more than one element, an edgedb.ResultCardinalityMismatchError is raised, if it returns an empty set, "null" is returned.

Note, that positional and named query arguments cannot be mixed.

Acquire a connection and use it to run a singleton-returning query and return its element in JSON. The temporary connection is automatically returned back to the pool.

The query must return exactly one element. If the query returns more than one element, an edgedb.ResultCardinalityMismatchError is raised, if it returns an empty set, an edgedb.NoDataError is raised.

Note, that positional and named query arguments cannot be mixed.

Acquire a connection and use it to execute an EdgeQL command (or commands). The temporary connection is automatically returned back to the pool.

The commands must take no arguments.

Example:

>>> 
... 
... 
... 
... 
... 
... 

await con.execute('''
    CREATE TYPE MyType {
        CREATE PROPERTY a -> int64
    };
    FOR x IN {100, 200, 300}
    UNION INSERT MyType { a := x };
''')

Open a retryable transaction loop.

This is the preferred method of initiating and running a database transaction in a robust fashion. The transaction() transaction loop will attempt to re-execute the transaction loop body if a transient error occurs, such as a network error or a transaction serialization error.

Returns an instance of AsyncIORetry.

See Transactions for more details.

Example:

async for tx in con.transaction():
    async with tx:
        value = await tx.query_single("SELECT Counter.value")
        await tx.execute(
            "UPDATE Counter SET { value := <int64>$value }",
            value=value + 1,
        )

Note that we are executing queries on the tx object rather than on the original connection.

Attempt to gracefully close all connections in the pool.

Wait until all pool connections are released, close them and shut down the pool. If any error (including cancellation) occurs in aclose() the pool will terminate by calling terminate().

It is advisable to use asyncio.wait_for() to set a timeout.

Terminate all connections in the pool.

If the client does not yet have any open connections in its pool, attempts to open a connection, else returns immediately.

Since the client lazily creates new connections as needed (up to the configured concurrency limit), the first connection attempt will only occur when the first query is run on a client. ensureConnected can be useful to catch any errors resulting from connection mis-configuration by triggering the first connection attempt explicitly.

Returns a shallow copy of the client with adjusted transaction options.

See Transaction Options for details.

Returns a shallow copy of the client with adjusted retry options.

See Retry Options for details.

Returns a shallow copy of the client with adjusted state.

See State for details.

Returns a shallow copy of the client with adjusted default module.

This is equivalent to using the set module command, or using the reset module command when giving None.

See State.with_default_module() for details.

Returns a shallow copy of the client with adjusted module aliases.

This is equivalent to using the set alias command.

See State.with_module_aliases() for details.

Returns a shallow copy of the client without specified module aliases.

This is equivalent to using the reset alias command.

See State.without_module_aliases() for details.

Returns a shallow copy of the client with adjusted session config.

This is equivalent to using the configure session set command.

See State.with_config() for details.

Returns a shallow copy of the client without specified session config.

This is equivalent to using the configure session reset command.

See State.without_config() for details.

Returns a shallow copy of the client with adjusted global values.

This is equivalent to using the set global command.

See State.with_globals() for details.

Returns a shallow copy of the client without specified globals.

This is equivalent to using the reset global command.

See State.without_globals() for details.

Represents a wrapper that yields AsyncIOTransaction object when iterating.

See AsyncIOClient.transaction() method for an example.

Yields AsyncIOTransaction object every time transaction has to be repeated.

Represents a transaction.

Instances of this type are yielded by a AsyncIORetry iterator.

Start and commit/rollback the transaction automatically when entering and exiting the code inside the context manager block.

Acquire a connection if the current transaction doesn’t have one yet, and use it to run a query and return the results as an edgedb.Set instance. The temporary connection is automatically returned back to the pool when exiting the transaction block.

See AsyncIOClient.query() for details.

Acquire a connection if the current transaction doesn’t have one yet, and use it to run an optional singleton-returning query and return its element. The temporary connection is automatically returned back to the pool when exiting the transaction block.

See AsyncIOClient.query_single() for details.

Acquire a connection if the current transaction doesn’t have one yet, and use it to run a singleton-returning query and return its element. The temporary connection is automatically returned back to the pool when exiting the transaction block.

See AsyncIOClient.query_required_single() for details.

Acquire a connection if the current transaction doesn’t have one yet, and use it to run a query and return the results as JSON. The temporary connection is automatically returned back to the pool when exiting the transaction block.

See AsyncIOClient.query_json() for details.

Acquire a connection if the current transaction doesn’t have one yet, and use it to run an optional singleton-returning query and return its element in JSON. The temporary connection is automatically returned back to the pool when exiting the transaction block.

See AsyncIOClient.query_single_json() for details.

Acquire a connection if the current transaction doesn’t have one yet, and use it to run a singleton-returning query and return its element in JSON. The temporary connection is automatically returned back to the pool when exiting the transaction block.

See AsyncIOClient.query_requried_single_json() for details.

Acquire a connection if the current transaction doesn’t have one yet, and use it to execute an EdgeQL command (or commands). The temporary connection is automatically returned back to the pool when exiting the transaction block.

See AsyncIOClient.execute() for details.