{"id":15622,"library":"gel","title":"Gel Node.js Client","description":"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+).","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/geldata/gel-js","tags":["javascript","typescript"],"install":[{"cmd":"npm install gel","lang":"bash","label":"npm"},{"cmd":"yarn add gel","lang":"bash","label":"yarn"},{"cmd":"pnpm add gel","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The Gel client library is primarily designed for ESM usage. `createClient` is the main function for instantiating a client connection pool.","wrong":"const { createClient } = require('gel');","symbol":"createClient","correct":"import { createClient } from 'gel';"},{"note":"The `Client` symbol typically refers to the TypeScript type definition for a client instance, not a runtime constructor. Use `createClient()` to get an instance.","wrong":"import { Client } from 'gel';","symbol":"Client","correct":"import type { Client } from 'gel';"},{"note":"An enum used for configuring transaction isolation levels, such as `PreferRepeatableRead` which was introduced in v2.1.0.","wrong":"const IsolationLevel = require('gel').IsolationLevel;","symbol":"IsolationLevel","correct":"import { IsolationLevel } from 'gel';"}],"quickstart":{"code":"import { createClient, IsolationLevel } from 'gel';\n\nasync function runGelQuery() {\n  // Create a client instance. For local development, it auto-discovers\n  // connection info from `gel project init`. In production, set GEL_DSN env var.\n  const client = createClient().withTransactionOptions({\n    isolation: IsolationLevel.PreferRepeatableRead,\n  });\n\n  try {\n    // Run a simple scalar query, expecting a single numeric result\n    const resultScalar = await client.querySingle<number>('select 2 + 2');\n    console.log(`Scalar query result: ${resultScalar}`); // Expected: 4\n\n    // Run a query potentially returning multiple rows or an empty set\n    const resultEmptySet = await client.query<string>('select <str>{}');\n    console.log(`Empty set query result: ${resultEmptySet}`); // Expected: []\n\n    // Run a query guaranteed to return exactly one element, using a shape type\n    const resultRequiredSingle = await client.queryRequiredSingle<{ message: string }>(\n      \"select { message := 'Hello Gel!' }\"\n    );\n    console.log(`Required single query result: ${resultRequiredSingle.message}`); // Expected: \"Hello Gel!\"\n\n  } catch (error) {\n    console.error('Gel query failed:', error);\n  } finally {\n    await client.close(); // Remember to close the client connection to release resources\n  }\n}\n\nrunGelQuery();","lang":"typescript","description":"Demonstrates basic client creation, connection configuration with transaction options, and executing various query types (`query`, `querySingle`, `queryRequiredSingle`) to handle different result cardinalities gracefully."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 18.0.0 or newer.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update TypeScript to version 4.4+ in your project's `package.json` and `tsconfig.json`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use `require()` with the `gel` package, which is primarily designed for ES Modules (ESM) imports.","error":"ERR_REQUIRE_ESM"},{"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.","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.","error":"Error: Connection failed: Host unreachable"},{"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'); }`","cause":"You are using `.querySingle()` which returns `T | null`, and attempting to access properties on the result without first checking if it's `null`.","error":"TypeError: Cannot read properties of null (reading 'property')"},{"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()`.","cause":"You are using `.queryRequiredSingle()` for a query that returned zero or multiple elements, violating its guarantee of exactly one result.","error":"Error: Query returned more than one element"}],"ecosystem":"npm"}