Blocking API

function connect(dsn=None, *, host=None, port=None, admin=None, user=None, password=None, database=None, timeout=60)

Establish a connection to an EdgeDB server.

Parameters
  • dsn – Connection arguments specified using as a single string in the connection URI format: edgedb://user:password@host:port/database?option=value. The following options are recognized: host, port, user, database, password.

  • hostDatabase host address as one of the following:

    • an IP address or a domain name;
    • an absolute path to the directory containing the database server Unix-domain socket (not supported on Windows);
    • a sequence of any of the above, in which case the addresses will be tried in order, and the first successful connection will be returned.
    If not specified, the following will be tried, in order:
    • host address(es) parsed from the dsn argument,
    • the value of the EDGEDB_HOST environment variable,
    • on Unix, common directories used for EdgeDB Unix-domain sockets: "/run/edgedb" and "/var/run/edgedb",
    • "localhost".

  • portPort number to connect to at the server host (or Unix-domain socket file extension). If multiple host addresses were specified, this parameter may specify a sequence of port numbers of the same length as the host sequence, or it may specify a single port number to be used for all host addresses.If not specified, the value parsed from the dsn argument is used, or the value of the EDGEB_PORT environment variable, or 5656 if neither is specified.

  • admin – If True, try to connect to the special administration socket.

  • userThe name of the database role used for authentication.If not specified, the value parsed from the dsn argument is used, or the value of the EDGEDB_USER environment variable, or the operating system name of the user running the application.

  • databaseThe name of the database to connect to.If not specified, the value parsed from the dsn argument is used, or the value of the EDGEDB_DATABASE environment variable, or the operating system name of the user running the application.

  • password – Password to be used for authentication, if the server requires one. If not specified, the value parsed from the dsn argument is used, or the value of the EDGEDB_PASSWORD environment variable. Note that the use of the environment variable is discouraged as other users and applications may be able to read it without needing specific privileges.

  • timeout (float) – Connection timeout in seconds.

Returns

A BlockingIOConnection instance.

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.

Returns a new BlockingIOConnection object.

Example:

>>> 
import edgedb
>>> 
con = edgedb.connect(user='edgedeb')
>>> 
con.fetchone('SELECT 1 + 1')
{2}
class BlockingIOConnection

A representation of a database session.

Connections are created by calling connect().

method BlockingIOConnection.fetchall(query, *args, **kwargs)

Run a query and return the results as a edgedb.Set instance.

Parameters
  • query (str) – Query text.

  • args – Positional query arguments.

  • kwargs – Named query arguments.

Returns

An instance of edgedb.Set containing the query result.

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

method BlockingIOConnection.fetchone(query, *args, **kwargs)

Run a singleton-returning query and return its element.

Parameters
  • query (str) – Query text.

  • args – Positional query arguments.

  • kwargs – Named query arguments.

Returns

Query result.

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.

method BlockingIOConnection.fetchall_json(query, *args, **kwargs)

Run a query and return the results as JSON.

Parameters
  • query (str) – Query text.

  • args – Positional query arguments.

  • kwargs – Named query arguments.

Returns

A JSON string containing an array of query results.

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

method BlockingIOConnection.fetchone_json(query, *args, **kwargs)

Run a singleton-returning query and return its element in JSON.

Parameters
  • query (str) – Query text.

  • args – Positional query arguments.

  • kwargs – Named query arguments.

Returns

Query result encoded in JSON.

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.

method BlockingIOConnection.execute(query)

Execute an EdgeQL command (or commands).

Parameters

query (str) – Query text.

The commands must take no arguments.

Example:

>>> 
... 
... 
... 
... 
... 
... 
con.execute('''
    CREATE TYPE MyType {
        CREATE PROPERTY a -> int64
    };
    FOR x IN {100, 200, 300}
    UNION INSERT MyType { a := x };
''')
method BlockingIOConnection.transaction(isolation=None, readonly=None, deferrable=None)

Create a Transaction object.

Parameters
  • isolation – Transaction isolation mode, can be one of: 'serializable', 'repeatable_read'. If not specified, the server-side default is used.

  • readonly – Specifies whether or not this transaction is read-only. If not specified, the server-side default is used.

  • deferrable – Specifies whether or not this transaction is deferrable. If not specified, the server-side default is used.

method BlockingIOConnection.close()

Close the connection gracefully.

method BlockingIOConnection.is_closed()

Return True if the connection is closed.

The most common way to use transactions is through a context statement:

with connection.transaction():
    connection.execute("INSERT User { name := 'Don' }")

It is possible to nest transactions (a nested transaction context will create a savepoint):

with connection.transaction():
    connection.execute(
        'CREATE TYPE User { CREATE PROPERTY name -> str }')

    try:
        # Create a savepoint:
        with connection.transaction():
            connection.execute(
                "INSERT User { name := 'Don' }")
            # This nested savepoint will be
            # automatically rolled back:
            raise Exception
    except:
        # Ignore exception
        pass

    # Because the nested savepoint was rolled back, there
    # will be nothing in `User`.
    assert connection.fetchall('SELECT User') == []

Alternatively, transactions can be used without a with block:

tr = connection.transaction()
tr.start()
try:
    ...
except:
    tr.rollback()
    raise
else:
    tr.commit()

See also the BlockingIOConnection.transaction() function.

class Transaction

Represents a transaction or savepoint block.

Transactions are created by calling the BlockingIOConnection.transaction() method.

method Transaction.start()

Enter the trasnaction or savepoint block.

method Transaction.commit()

Exit the transaction or savepoint block and commit changes.

method Transaction.rollback()

Exit the transaction or savepoint block and discard changes.

interface with c:

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