Gel Node.js Client

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to use `require()` with the `gel` package, which is primarily designed for ES Modules (ESM) imports.
  fix Change `const gel = require('gel')` or `const { createClient } = require('gel')` to `import * as gel from 'gel'` or `import { createClient } from 'gel'`. Ensure your project is configured for ESM (e.g., by adding `"type": "module"` to your `package.json`).

• Error: Connection failed: Host unreachable

  cause The Gel client could not establish a connection to the Gel database instance. This commonly indicates an incorrect Data Source Name (DSN), a non-running Gel instance, or network/firewall issues.
  fix Verify that your `GEL_DSN` environment variable is correctly configured, ensure your Gel database instance is running and accessible at the specified host/port, and check any local or cloud firewall rules.

• TypeError: Cannot read properties of null (reading 'property')

  cause You are using `.querySingle()` which returns `T | null`, and attempting to access properties on the result without first checking if it's `null`.
  fix Always check for `null` when using `.querySingle()`: `const user = await client.querySingle<{ name: string }>('select User { name } limit 1'); if (user) { console.log(user.name); } else { console.log('User not found'); }`

• Error: Query returned more than one element

  cause You are using `.queryRequiredSingle()` for a query that returned zero or multiple elements, violating its guarantee of exactly one result.
  fix If your query might return zero or many elements, use `.querySingle()` (for zero or one element, returning `T | null`) or `.query()` (for any number of elements, returning `T[]`) instead of `.queryRequiredSingle()`.

Warnings

• breaking The `gel` client library officially requires Node.js version 18.0.0 or higher. Earlier Node.js versions are not supported and may lead to runtime errors or unexpected behavior.
  Fix: Upgrade your Node.js runtime to version 18.0.0 or newer.
• breaking TypeScript users must ensure their project is configured for TypeScript 4.4 or higher to correctly interpret the client's shipped type definitions and generated code.
  Fix: Update TypeScript to version 4.4+ in your project's `package.json` and `tsconfig.json`.
• gotcha The `.query()`, `.querySingle()`, and `.queryRequiredSingle()` methods have distinct behaviors regarding result cardinality. `.query()` always returns an array. `.querySingle()` returns `T | null` for zero or one elements. `.queryRequiredSingle()` guarantees exactly one `T` element, throwing an error if zero or multiple are returned.
  Fix: Always use the appropriate query method based on the expected cardinality of your query's result to avoid runtime errors or incorrect type assumptions.
• gotcha For production environments, the Gel client relies on the `GEL_DSN` environment variable for connection details. Auto-discovery only works for local development within a `gel project` initialized directory.
  Fix: Ensure `GEL_DSN` is correctly configured in your production environment with a valid connection string in the format `gel://USERNAME:PASSWORD@HOSTNAME:PORT/DATABASE`.
• breaking Underlying Gel server changes in version 6.0 introduced breaking changes to the embeddings and RAG endpoints. While the core client package (gel) itself didn't have direct breaking changes, users interacting with Gel's AI extensions via `@gel/ai` should consult its release notes and the Gel 6.0 server documentation for compatibility.
  Fix: Review the latest `@gel/ai` package documentation and Gel server release notes (especially Gel 6.0) and migrate your AI-related code to align with updated API structures.

Install

• npm install gel npm
• yarn add gel yarn
• pnpm add gel pnpm

Imports

• createClient
  wrong:

  const { createClient } = require('gel');

  correct:

  import { createClient } from 'gel';

  The Gel client library is primarily designed for ESM usage. `createClient` is the main function for instantiating a client connection pool.
• Client
  wrong:

  import { Client } from 'gel';

  correct:

  import type { Client } from 'gel';

  The `Client` symbol typically refers to the TypeScript type definition for a client instance, not a runtime constructor. Use `createClient()` to get an instance.
• IsolationLevel
  wrong:

  const IsolationLevel = require('gel').IsolationLevel;

  correct:

  import { IsolationLevel } from 'gel';

  An enum used for configuring transaction isolation levels, such as `PreferRepeatableRead` which was introduced in v2.1.0.

Quickstart

Demonstrates basic client creation, connection configuration with transaction options, and executing various query types (`query`, `querySingle`, `queryRequiredSingle`) to handle different result cardinalities gracefully.

import { createClient, IsolationLevel } from 'gel';

async function runGelQuery() {
  // Create a client instance. For local development, it auto-discovers
  // connection info from `gel project init`. In production, set GEL_DSN env var.
  const client = createClient().withTransactionOptions({
    isolation: IsolationLevel.PreferRepeatableRead,
  });

  try {
    // Run a simple scalar query, expecting a single numeric result
    const resultScalar = await client.querySingle<number>('select 2 + 2');
    console.log(`Scalar query result: ${resultScalar}`); // Expected: 4

    // Run a query potentially returning multiple rows or an empty set
    const resultEmptySet = await client.query<string>('select <str>{}');
    console.log(`Empty set query result: ${resultEmptySet}`); // Expected: []

    // Run a query guaranteed to return exactly one element, using a shape type
    const resultRequiredSingle = await client.queryRequiredSingle<{ message: string }>(
      "select { message := 'Hello Gel!' }"
    );
    console.log(`Required single query result: ${resultRequiredSingle.message}`); // Expected: "Hello Gel!"

  } catch (error) {
    console.error('Gel query failed:', error);
  } finally {
    await client.close(); // Remember to close the client connection to release resources
  }
}

runGelQuery();