gel

library3.1.0jsnpmunverified

The `gel` package is the official Node.js client library for interacting with Gel databases. It provides a robust, type-safe API for executing queries, managing transactions, and interacting with Gel's data model. The current stable version, as per the prompt, is 2.2.0, with frequent minor and patch releases, often in conjunction with `@gel/generate` and `@gel/ai` packages, indicating active development and rapid iteration. Key differentiators include strong TypeScript support, an ORM-less approach focusing on direct query execution, automatic connection discovery for local development, and extensive query generation capabilities through its companion tools. It's designed for Node.js environments (v18.0.0+) and also supports TypeScript projects (v4.4.0+).

database

npm install gel

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GEL

gel

databasejavascriptv3.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createClient

✓ import { createClient } from 'gel';

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

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

Client

✓ import type { Client } from 'gel';

✗ import { 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

✓ import { IsolationLevel } from 'gel';

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

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

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();

gel --version

Debug

Known issues

breakingThe `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.

affects: >=2.0.0

breakingTypeScript 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`.

affects: >=2.0.0

gotchaThe `.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.

affects: >=1.0.0

gotchaFor 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`.

affects: >=1.0.0

breakingUnderlying 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.

affects: >=2.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

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

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')

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

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()`.

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/geldata/gel-js ↗

packagehttps://www.npmjs.com/package/gel ↗

homepagehttps://geldata.com ↗