Driver

The driver implements the core functionality required to establish a connection to your database and execute queries.

Creating clients

A client represents a connection to your database and provides methods for executing queries.

In actuality, the client maintains an pool of connections under the hood. When your server is under load, queries will be run in parallel across many connections, instead of being bottlenecked by a single connection.

To create a client:

const edgedb = require("edgedb");
const client = edgedb.createClient();

If you’re using TypeScript or have ES modules enabled, you can use import syntax instead:

import * as edgedb from "edgedb";
const client = edgedb.createClient();

Configuring the connection

Notice we didn’t pass any arguments into createClient. That’s intentional; we recommend using EdgeDB projects or environment variables to configure your database connections. See the Client Library Connection docs for details on configuring connections.

Running queries

To execute a basic query:

const edgedb = require("edgedb");
const client = edgedb.createClient();
async function main() {
  const result = await client.query(`select 2 + 2;`);
  console.log(result); // [4]
}

In TypeScript, you can supply a type hint to receive a strongly typed result.

const result = await client.query<number>(`select 2 + 2;`);
// number[]

Type conversion

The driver converts EdgeDB types into a corresponding JavaScript data structure. Some EdgeDB types like duration don’t have a corresponding type in the JavaScript type system, so we’ve implemented classes like Duration() to represent them.

To learn more about the driver’s built-in type classes, refer to the reference documentation.

• Duration()

• RelativeDuration()

• DateDuration()

• LocalDate()

• LocalTime()

• LocalDateTime()

• ConfigMemory()

• Range()

Enforcing cardinality

There are additional methods for running queries that have an expected cardinality. This is a useful way to tell the driver how many elements you expect the query to return.

The query method places no constraints on cardinality. It returns an array, no matter what.

await client.query(`select 2 + 2;`); // [4]
await client.query(`select <int64>{};`); // []
await client.query(`select {1, 2, 3};`); // [1, 2, 3]

Use querySingle if you expect your query to return zero or one elements. Unlike query, it either returns a single element or null. Note that if you’re selecting an array, tuple, or set, the returned ‘single’ element will be an array.

await client.querySingle(`select 2 + 2;`); // [4]
await client.querySingle(`select <int64>{};`); // null
await client.querySingle(`select {1, 2, 3};`); // Error

Use queryRequiredSingle for queries that return exactly one element.

await client.queryRequiredSingle(`select 2 + 2;`); // 4
await client.queryRequiredSingle(`select <int64>{};`); // Error
await client.queryRequiredSingle(`select {1, 2, 3};`); // Error

The TypeScript signatures of these methods reflects their behavior.

await client.query<number>(`select 2 + 2;`);
// number[]
await client.querySingle<number>(`select 2 + 2;`);
// number | null
await client.queryRequiredSingle<number>(`select 2 + 2;`);
// number

JSON results

Client provide additional methods for running queries and retrieving results as a serialized JSON string. This serialization happens inside the database and is typically more performant than running JSON.stringify yourself.

await client.queryJSON(`select {1, 2, 3};`);
// "[1, 2, 3]"
await client.querySingleJSON(`select <int64>{};`);
// "null"
await client.queryRequiredSingleJSON(`select 3.14;`);
// "3.14"

Non-returning queries

To execute a query without retrieving a result, use the .execute method. This is especially useful for mutations, where there’s often no need for the query to return a value.

await client.execute(`insert Movie {
  title := "Avengers: Endgame"
};`);

With EdgeDB 2.0 or later, you can execute a “script” consisting of multiple semicolon-separated statements in a single .execute call.

await client.execute(`
  insert Person { name := "Robert Downey Jr." };
  insert Person { name := "Scarlett Johansson" };
  insert Movie {
    title := <str>$title,
    actors := (
      select Person filter .name in {
        "Robert Downey Jr.",
        "Scarlett Johansson"
      }
    )
  }
`, { title: "Iron Man 2" });

Parameters

If your query contains parameters (e.g. $foo), you can pass in values as the second argument. This is true for all query* methods and execute.

const INSERT_MOVIE = `insert Movie {
  title := <str>$title
}`
const result = await client.querySingle(INSERT_MOVIE, {
  title: "Iron Man"
});
console.log(result);
// {id: "047c5893..."}

Remember that parameters can only be scalars or arrays of scalars.

Scripts

Both execute and the query* methods support scripts (queries containing multiple statements). The statements are run in an implicit transaction (unless already in an explicit transaction), so the whole script remains atomic. For the query* methods only the result of the final statement in the script will be returned.

const result = await client.query(`
  insert Movie {
    title := <str>$title
  };
  insert Person {
    name := <str>$name
  };
`, {
  title: "Thor: Ragnarok",
  name: "Anson Mount"
});
// [{id: "5dd2557b..."}]

For more fine grained control of atomic exectution of multiple statements, use the transaction() API.

Checking connection status

The client maintains a dynamically sized pool of connections under the hood. These connections are initialized lazily, so no connection will be established until the first time you execute a query.

If you want to explicitly ensure that the client is connected without running a query, use the .ensureConnected() method.

const edgedb = require("edgedb");
const client = edgedb.createClient();
async function main() {
  await client.ensureConnected();
}

Transactions

The most robust way to execute transactional code is to use the transaction() API:

await client.transaction(tx => {
  await tx.execute("insert User {name := 'Don'}");
});

Note that we execute queries on the tx object in the above example, rather than on the original client object.

The transaction() API guarantees that:

1. Transactions are executed atomically;

2. If a transaction fails due to retryable error (like a network failure or a concurrent update error), the transaction would be retried;

3. If any other, non-retryable error occurs, the transaction is rolled back and the transaction() block throws.

The key implication of retrying transactions is that the entire nested code block can be re-run, including any non-querying JavaScript code. Here is an example:

const email = "timmy@edgedb.com"
await client.transaction(async tx => {
  await tx.execute(
    `insert User { email := <str>$email }`,
    { email },
  )
  await sendWelcomeEmail(email);
  await tx.execute(
    `insert LoginHistory {
      user := (select User filter .email = <str>$email),
      timestamp := datetime_current()
    }`,
    { email },
  )
})

In the above example, the welcome email may be sent multiple times if the transaction block is retried. Generally, the code inside the transaction block shouldn’t have side effects or run for a significant amount of time.

Transactions allocate expensive server resources and having too many concurrently running long-running transactions will negatively impact the performance of the DB server.

• RFC1004

• Client.transaction()

Next up

If you’re a TypeScript user and want autocompletion and type inference, head over to the Query Builder docs. If you’re using plain JavaScript that likes writing queries with composable code-first syntax, you should check out the query builder too! If you’re content writing queries as strings, the vanilla driver API will meet your needs.