API

Establish a connection to an EdgeDB server.

Example:

// Use the Node.js assert library to test results.
const assert = require("assert");
const edgedb = require("edgedb");

async function main() {
  const conn = await edgedb.connect({
    dsn: "edgedb://edgedb@localhost/"
  });

  try{
    let data = await conn.queryOne("SELECT 1 + 1");

    // The result is a number 2.
    assert(typeof data === "number");
    assert(data === 2);
  } finally {
    conn.close();
  }
}

main();

await connect({host: 'localhost', port: 5656})
// or
await connect({dsn: 'edgedb://localhost'})

A representation of a database session.

Connection() is not meant to be instantiated directly; connect() should be used instead.

Execute an EdgeQL command (or commands).

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 };
`)

Run a query and return the results as a Set() instance.

This method takes optional query arguments.

Run a singleton-returning query and return its element.

This method takes optional query arguments.

The query must return exactly one element. If the query returns more than one element or an empty set, an Error is thrown.

Run a query and return the results as JSON.

This method takes optional query arguments.

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

This method takes optional query arguments.

The query must return exactly one element. If the query returns more than one element or an empty set, an Error is thrown.

Execute a retryable transaction.

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

See Transactions for more details.

Example:

await con.retryingTransaction(async tx => {
    let value = await tx.queryOne("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 con.

Execute a non-retryable transaction.

Contrary to retryingTransaction(), rawTransaction() will not attempt to re-run the nested code block in case a retryable error happens.

This is a low-level API and it is advised to use the retryingTransaction() method instead.

Example:

await con.rawTransaction(async tx => {
    let value = await tx.queryOne("SELECT Counter.value");
    await tx.execute(
        "UPDATE Counter SET { value := <int64>$value",
        value=value,
    )
})

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

Deprecated: Use retryingTransaction<T>() or rawTransaction<T>().

Executes a given action in transaction.

If an exception occurs during the execution of the given function argument, the transaction is automatically rolled back and the exception is rethrown. Otherwise, the transaction is committed.

Example:

await con.transaction(async () => {
    await con.execute(`
        INSERT Example {
            name := 'Test Transaction 1'
        };
    `);
    await con.execute("SELECT 1 / 0;");
});

// nested transactions are supported
// and handle save points
await con.transaction(async () => {

    // nested transaction
    await con.transaction(async () => {
        await con.execute(`
            INSERT Example {
                name := 'Test Transaction 2'
            };
        `);
    });
});

Close the connection gracefully.

Create a connection pool to an EdgeDB server.

If this parameter does not start with edgedb:// then this is a name of an instance.

Otherwise it specifies a single string in the connection URI format:

await createPool({
  maxSize: 10,
  connectOptions: {dsn: 'edgedb://localhost'},
})

A connection pool is used to manage a set of connections to a database. Since opening connections is an expensive operation, connection pools are used to maintain and reuse connections, enhancing the performance of database interactions.

Pools must be created using the method createPool:

const edgedb = require("edgedb");

async function main() {
    const pool = await edgedb.createPool(
        "edgedb://edgedb@localhost/test"
    );

    try {
        let data = await pool.queryOne("SELECT [1, 2, 3]");

        console.log(data);
    } finally {
        // in this example, the pool is closed after a single
        // operation; in real scenarios a pool is initialized
        // at application startup, and closed at application shutdown
        await pool.close();
    }
}

main();

The pool accepts the following parameters:

Acquire a connection, then execute an EdgeQL command (or commands). The commands must take no arguments.

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

Acquire a connection, then run a query and return the results as a Set() instance.

This method takes optional query arguments.

const items = await pool.query(
    `SELECT Movie {
        title,
        year,
        director: {
            first_name,
            last_name
        },
        actors: {
            first_name,
            last_name
        }
    }
    FILTER .id = <uuid>$id;`,
    {
        id: movieId,
    }
);

Acquire a connection, then run a query that returns a single item and return its result.

This method takes optional query arguments.

The query must return exactly one element. If the query returns more than one element or an empty set, an Error is thrown.

await pool.queryOne("SELECT 1");

Acquire a connection, then run a query and return the results as JSON.

This method takes optional query arguments.

Acquire a connection, then run a singleton-returning query and return its element in JSON.

This method takes optional query arguments.

The query must return exactly one element. If the query returns more than one element or an empty set, an Error is thrown.

Acquire a connection proxy, which provides access to an open database connection. The proxy must be released to return the connection to the pool.

Example:

const connection = await pool.acquire();
let value: number;

try {
    value = await connection.queryOne("select 1");
} finally {
    await pool.release(connection);
}

Release a previously acquired connection proxy, to return it to the pool.

Acquire a connection and use it to run the given action that accepts a connection, and return T, which is any type returned by the user’s defined function argument. The connection is automatically returned to the pool.

Example:

const result = await pool.run(async (connection) => {
    return await connection.queryOne("SELECT 1");
});
expect(result).toBe(1);

Execute a retryable transaction.

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

See Transactions for more details.

Example:

await pool.retryingTransaction(async tx => {
    let value = await tx.queryOne("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 pool pool.

Execute a non-retryable transaction.

Contrary to retryingTransaction(), rawTransaction() will not attempt to re-run the nested code block in case a retryable error happens.

This is a low-level API and it is advised to use the retryingTransaction() method instead.

Example:

await pool.rawTransaction(async tx => {
    let value = await tx.queryOne("SELECT Counter.value");
    await tx.execute(
        "UPDATE Counter SET { value := <int64>$value",
        value=value,
    )
})

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

Return information about the current state of the pool. Information includes the number of currently open connections and the number of pending consumers awaiting an available connection.

Example:

const stats = pool.getStats();
const queueLength = stats.queueLength;
const openConnections = stats.openConnections;

Expire all currently open connections. Cause all currently open connections to be replaced when they are acquired by the next .acquire() call.

Close the connection pool gracefully. When a connection pool is closed, all its underlying connections are awaited to complete their pending operations, then closed. A warning is produced if the pool takes more than 60 seconds to close.

Terminate all connections in the pool, closing all connections non gracefully. If the pool is already closed, return without doing anything.