Client​

Creates a new Client() instance.

The above connection options can also be specified by their corresponding environment variable. If none of dsn, credentialsFile, host or port are explicitly specified, the client will connect to your linked project instance, if it exists. For full details, see the Connection Parameters docs.

Example:

import { createClient } from "gel";
import assert from "node:assert";

async function main() {
  const client = createClient();

  const data: number = await client.queryRequiredSingle<number>(
    "select 1 + 1"
  );

  assert(data === 2, "Result is exactly the number 2");
}

main();

A Client allows you to run queries on a Gel instance.

Since opening connections is an expensive operation, Client also maintains a internal pool of connections to the instance, allowing connections to be automatically reused, and you to run multiple queries on the client simultaneously, enhancing the performance of database interactions.

Client() is not meant to be instantiated directly; createClient() should be used instead.

Execute an EdgeQL command or script of commands. Does not return any results.

Example:

await client.execute(`
  for x in {100, 200, 300}
  insert MyType { a := x };
`)

Run an EdgeQL query and return the results as an array. This method always returns an array.

Example:

const result = await client.query<number>("select 2 + 2;"); // number[]: [4]
const result = await client.query<number>("select {1, 2, 3};"); // number[]: [1, 2, 3]
const result = await client.query<number>("select <int64>{};"); // number[]: []

Run a query that returns at least one element and return the result as an array. The query must return at least one element. If the query less than one element, a ResultCardinalityMismatchError error is thrown.

Example:

await client.queryRequired<number>("select 2 + 2;"); // [number, ...number[]]: [4]
await client.queryRequired<number>("select {1, 2, 3};"); // [number, ...number[]]: [1, 2, 3]
await client.queryRequired<number>("select <int64>{};"); // Throws a ResultCardinalityMismatchError

Run an optional singleton-returning query and return the result. The query must return no more than one element. If the query returns more than one element, a ResultCardinalityMismatchError error is thrown.

Example:

const result = await client.querySingle<number>("select 2 + 2;"); // number | null: 4
await client.querySingle<number>("select <int64>{};"); // number | null: null
await client.querySingle<number>("select {1, 2, 3};"); // Throws a ResultCardinalityMismatchError

Run a singleton-returning query and return the result. The query must return exactly one element. If the query returns more than one element, a ResultCardinalityMismatchError error is thrown. If the query returns an empty set, a NoDataError error is thrown.

Example:

await client.queryRequiredSingle<number>("select 2 + 2;"); // number: 4
await client.queryRequiredSingle<number>("select <int64>{};"); // Throws a NoDataError
await client.queryRequiredSingle<number>("select {1, 2, 3};"); // Throws a ResultCardinalityMismatchError

Run a query and return the results as a JSON-encoded string.

Run a query that returns at least one element and return the result as a JSON-encoded string. The query must return at least one element. If the query less than one element, a ResultCardinalityMismatchError error is thrown.

Example:

const result = await client.queryRequiredJSON("select 2 + 2;"); // string: "4"
const result = await client.queryRequiredJSON("select <int64>{};"); // Throws a ResultCardinalityMismatchError
const result = await client.queryRequiredJSON("select {1, 2, 3};"); // Throws a ResultCardinalityMismatchError

Run an optional singleton-returning query and return its element as a JSON-encoded string. The query must return at most one element. If the query returns more than one element, an ResultCardinalityMismatchError error is thrown.

Example:

const result = await client.querySingleJSON("select 2 + 2;"); // string: "4"
await client.querySingleJSON("select <int64>{};"); // Throws a ResultCardinalityMismatchError
await client.querySingleJSON("select {1, 2, 3};"); // Throws a ResultCardinalityMismatchError

Run a singleton-returning query and return its element as a JSON-encoded string. The query must return exactly one element. If the query returns more than one element, a ResultCardinalityMismatchError error is thrown. If the query returns an empty set, a NoDataError error is thrown.

Example:

const result = await client.queryRequiredSingleJSON("select 2 + 2;"); // string: "4"
await client.queryRequiredSingleJSON("select <int64>{};"); // Throws a ResultCardinalityMismatchError
await client.queryRequiredSingleJSON("select {1, 2, 3};"); // Throws a ResultCardinalityMismatchError

Execute a SQL command.

Example:

await client.executeSQL(`
  INSERT INTO "MyType" (prop) VALUES ("value");
`)

Run a SQL query and return the results as an array. This method always returns an array.

The array will contain the returned rows. By default, rows are Objects with columns addressable by name, and the type of the object as the generic type parameter T. You can also opt into array mode, where the array contains arrays of values by calling client.withSQLRowMode('array').

Example:

const sqlQuery = `SELECT 1 as foo, "hello" as bar`;
await client.querySQL<{foo: number; bar: string }>(sqlQuery);
// { foo: number; bar: string }[]: [{'foo': 1, 'bar': 'hello'}]

const arrayModeClient = client.withSQLRowMode('array');
await arrayModeClient.querySQL<[number, string]>(sqlQuery);
// [number, string][]: [[1, 'hello']]

Execute a retryable transaction. The Transaction object passed to the action callback function has the same execute and query* methods as Client.

The transaction() method will attempt to re-execute the transaction body if a transient error occurs, such as a network error or a transaction serialization error. The number of times transaction() will attempt to execute the transaction, and the backoff timeout between retries can be configured with Client.withRetryOptions().

See Transactions for more details.

Example:

await client.transaction(async (tx) => {
  const value = await tx.queryRequiredSingle<number>("select Counter.value");
  await tx.execute(
    `update Counter set { value := <int64>$value }`,
    {value: value + 1},
  );
});

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 a client. ensureConnected can be useful to catch any errors resulting from connection mis-configuration by triggering the first connection attempt explicitly.

Example:

import { createClient } from "gel";

async function getClient() {
  try {
    return await createClient().ensureConnected();
  } catch (err) {
    // handle connection error
  }
}

async function main() {
  const client = await getClient();

  await client.query("select 2 + 2;");
}

Returns a clone of the Client instance with the specified global values. The globals argument object is merged with any existing globals defined on the current client instance. The new client instance will share the same connection pool as the client it's created from.

Equivalent to using the set global command.

Example:

const user = await client.withGlobals({
  userId: "00000000-0000-0000-0000-000000000000"
}).querySingle<{ name: string }>(`
  select User { name } filter .id = global userId;
`);

Returns a clone of the Client instance with the specified module aliases. The aliases argument object is merged with any existing module aliases defined on the current client instance. The new client instance will share the same connection pool as the client it's created from.

If the alias name is module this is equivalent to using the set module command, otherwise it is equivalent to the set alias command.

Example:

const user = await client.withModuleAliases({
  module: "sys"
}).queryRequiredSingle<string>(`
  select get_version_as_str();
`);
// "6.4"

Returns a clone of the Client instance with the specified client session configuration. The config argument object is merged with any existing session config defined on the current client instance. The new client instance will share the same connection pool as the client it's created from.

Equivalent to using the configure session command. For available configuration parameters refer to the Config documentation.

Example:

const user = await client
  .withConfig({ "query_timeout": 10000 })
  .query<{ name: string }>(`
    select User { name };
  `);

Returns a clone of the Client instance with the specified retry attempts number and backoff time function (the time that retrying methods will wait between retry attempts, in milliseconds), where options not given are inherited from the current client instance.

The default number of attempts is 3. The default backoff function returns a random time between 100 and 200ms multiplied by 2 ^ attempt number.

Example:

const nonRetryingClient = client.withRetryOptions({
  attempts: 1
});

// This transaction will not retry
await nonRetryingClient.transaction(async (tx) => {
  // ...
});

Close the client's open connections gracefully. When a client 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.

Returns true if close() has been called on the client.

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