Blocking API​

Create a blocking 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 Client object.

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

• Client.query()

• Client.query_single()

• Client.query_required_single()

• Client.query_json()

• Client.query_single_json()

• Client.query_required_single_json()

• Client.execute()

• Client.transaction()

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

The same for transactions:

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

A thread-safe blocking client with a connection pool.

Blocking clients are created by calling create_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:

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

client.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 Retry.

See Transactions for more details.

Example:

for tx in client.transaction():
    with tx:
        value = tx.query_single("SELECT Counter.value")
        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 timeout) occurs in close() the pool will terminate by calling terminate().

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 transaction.

Instances of this type are yielded by a Retry 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 Client.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 Client.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 Client.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 Client.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 Client.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 Client.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 Client.execute() for details.

Represents a wrapper that yields Transaction object when iterating.

See Client.transaction() method for an example.

Yields Transaction object every time transaction has to be repeated.