For native build steps (required to compile the Rust-backed parser):

# Rust toolchain required for edgeql-parser
curl https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env

# Build the Rust parser extension
python setup.py build_ext --inplace

# PostgreSQL 15+ must be available on PATH
# On macOS:
brew install postgresql@15
# On Ubuntu/Debian:
apt-get install postgresql-15

Project setup

1. Clone or copy the source/ directory into your project root as edb/.

2. Ensure your PYTHONPATH includes the project root so import edb resolves:

   export PYTHONPATH=/path/to/your/project:$PYTHONPATH
   

3. Build the native Rust parser extension from the project root:

   cd /path/to/your/project
   python setup.py build_ext --inplace
   

4. Set required environment variables:

   export EDGEDB_SERVER_DATADIR=/var/lib/gel/data
   export EDGEDB_SERVER_PORT=5656
   export EDGEDB_SERVER_BIND_ADDRESS=127.0.0.1
   # For development mode (enables extra diagnostics):
   export EDGEDB_DEVELOPER=1
   

5. Initialize a data directory and start the server:

   python -m edb.server --data-dir $EDGEDB_SERVER_DATADIR --port $EDGEDB_SERVER_PORT
   

6. For TypeScript/Node.js projects connecting to the running server, install the official client:

   npm install gel
   # or
   npm install edgedb
   

Public API

No TypeScript exports are available directly - this is a Python engine. The public surface for connecting Node.js/TypeScript applications to a running Gel server is the gel npm client. The engine source symbols below are Python-level.

edb.server (module)

# Entry point for the Gel server process
python -m edb.server [OPTIONS]

The server module starts the full Gel database server. Use it to embed a managed server process within your infrastructure or to run tests against a live instance.

edb.errors (module)

import edb.errors as errors
# e.g. errors.QueryError, errors.ConstraintViolationError
raise errors.QueryError("invalid query syntax", hint="check your filter clause")

Structured exception hierarchy for all database-level errors. Extend or catch these classes when building middleware layers that translate Gel errors to HTTP responses.

edb.common.ast.base (module)

from edb.common.ast.base import AST, Field
# Base classes for defining typed AST nodes used throughout the compiler

Provides the foundational AST node base class and Field descriptor used throughout edgeql/, ir/, and pgsql/. Use this when writing custom compiler passes or AST transformations.

Working examples

Scenario - Start a Gel server and connect from Node.js

A backend service that spawns a local Gel server process and queries it using the official Node.js client.

import { createClient } from "gel";
import { spawn, ChildProcess } from "child_process";
import { setTimeout } from "timers/promises";

async function startGelServer(): Promise<ChildProcess> {
  const server = spawn("python", [
    "-m", "edb.server",
    "--data-dir", process.env.EDGEDB_SERVER_DATADIR ?? "/var/lib/gel/data",
    "--port", "5656",
    "--bind-address", "127.0.0.1",
  ], { stdio: "inherit" });

  // Wait for server to be ready
  await setTimeout(3000);
  return server;
}

async function main() {
  const server = await startGelServer();

  const client = createClient({
    host: "127.0.0.1",
    port: 5656,
    tlsSecurity: "insecure",
  });

  const result = await client.query(`
    select schema::ObjectType { name }
    filter .builtin = false
  `);

  console.log("User-defined types:", result);
  await client.close();
  server.kill();
}

main().catch(console.error);

Scenario - Run EdgeQL queries against a running Gel instance

Express API endpoint that executes parameterized EdgeQL queries.

import express from "express";
import { createClient } from "gel";

const app = express();
app.use(express.json());

const db = createClient({
  instanceName: "my_gel_instance",
  database: "main",
});

app.get("/movies", async (req, res) => {
  try {
    const movies = await db.query(`
      select Movie {
        title,
        actors: { name }
      }
      order by .title
    `);
    res.json(movies);
  } catch (err: any) {
    // Gel query errors have a code property matching edb.errors codes
    res.status(400).json({ error: err.message, code: err.code });
  }
});

app.post("/movies", async (req, res) => {
  const { title } = req.body;
  const movie = await db.querySingle(`
    insert Movie { title := <str>$title }
    unless conflict on .title
    else (select Movie filter .title = <str>$title)
  `, { title });
  res.json(movie);
});

app.listen(3000, () => console.log("API listening on :3000"));

Scenario - Use the Gel CLI programmatically via Python subprocess

A Node.js migration runner that shells out to the Gel CLI (backed by edb/cli).

import { execFile } from "child_process";
import { promisify } from "util";

const exec = promisify(execFile);

async function runMigration(dataDir: string): Promise<void> {
  // edb/cli/__main__.py exposes the gel CLI
  const { stdout, stderr } = await exec("python", [
    "-m", "edb",
    "--instance", process.env.GEL_INSTANCE ?? "local",
    "migration", "apply",
    "--schema-dir", "./dbschema",
  ], {
    env: {
      ...process.env,
      EDGEDB_SERVER_DATADIR: dataDir,
    },
  });
  if (stdout) console.log("Migration output:", stdout);
  if (stderr) console.error("Migration stderr:", stderr);
}

runMigration("/var/lib/gel/data").catch(console.error);

File walkthrough

• api/ - Contains errors.txt and types.txt which define the canonical error codes and wire-format type descriptors used by the binary protocol.
• cli/ - CLI entry point; __main__.py makes python -m edb work, routing to subcommands (server, migration, introspect, etc.).
• common/ - Foundational utilities: AST base classes, markup/pretty-printing system, async helpers, topological sort, parametric types, structured logging, and more.
• edgeql/ - Full EdgeQL front-end: lexer, parser, AST definitions, semantic analysis, and query compilation.
• edgeql-parser/ - Rust-accelerated parser bindings via PyO3; must be compiled before the engine can parse any EdgeQL.
• errors/ - Complete error taxonomy; every error the engine can raise is defined here with a stable numeric code.
• graphql/ - Translates GraphQL queries into EdgeQL and handles schema reflection for the GraphQL endpoint.
• graphql-rewrite/ - Rewrites incoming GraphQL documents to normalize them before translation.
• ir/ - Compiler intermediate representation: typed query graphs sitting between EdgeQL AST and SQL codegen.
• language_server/ - LSP server for IDE integration; provides completion, hover, and diagnostics for .esdl and .edgeql files.
• lib/ - Bundled shared libraries and any pre-built native artifacts.
• load_ext/ - Plugin/extension loader used at server startup to register custom types and functions.
• pgsql/ - PostgreSQL backend: IR-to-SQL compilation, DDL delta generation, catalog introspection, and connection management.
• protocol/ - Binary protocol encoder/decoder implementing the Gel wire protocol versions.
• schema/ - Schema object model, reflection queries, constraint system, and migration delta computation.
• server/ - Async server core: client connection handling, compiler service pool, pgcon pool, and HTTP/binary endpoint dispatch.
• testbase/ - Shared test fixtures, server lifecycle helpers, and assertion utilities for the engine's own test suite.
• tools/ - Code generation scripts (e.g., generating Python from .txt API definitions).
• buildmeta.py - Exposes BUILD_VERSION, BUILD_DATE, and related metadata for runtime version reporting.

Common pitfalls and fixes

• Rust extension not built: ImportError on edb._edgeql_parser at startup. Fix: run python setup.py build_ext --inplace from the project root before starting the server.
• PostgreSQL not found: Server fails with FileNotFoundError: pg_ctl. Fix: ensure pg_ctl (PostgreSQL 15+) is on PATH and EDGEDB_SERVER_POSTGRES_DSN or bundled Postgres is configured.
• Data directory not initialized: Server exits with "data directory is not initialized". Fix: run python -m edb.server --bootstrap-only --data-dir <dir> once before normal startup.
• EDGEDB_DEVELOPER not set: Some internal diagnostics and developer-only CLI commands are silently unavailable. Fix: export EDGEDB_DEVELOPER=1 in your dev environment.
• Python version mismatch: The engine uses match statements and other Python 3.10+ syntax. Fix: use Python 3.11+ exclusively; check with python --version.
• TLS required by client: The Node.js gel client enforces TLS by default in production. Fix: set tlsSecurity: "insecure" in development or provide a proper certificate via --tls-cert-file server flag.

Vibe-coding prompt template

I have the Gel (EdgeDB) database engine source located in `source/` (Python package `edb`).
I also have a `USAGE.md` file describing the source layout, setup steps, and working examples.

Please help me integrate this into my existing project step by step:

1. Read `USAGE.md` and `source/` to understand the engine structure.
2. Set up the Python environment: install dependencies from the "Required dependencies" section of USAGE.md.
3. Build the Rust-backed `edgeql-parser` native extension.
4. Configure environment variables for the server (data dir, port, bind address).
5. Wire up server startup (either as a subprocess from Node.js or as a direct Python service).
6. Connect my Node.js/TypeScript application to the running Gel server using the `gel` npm package.
7. Write the schema for [MY DOMAIN OBJECTS] in `dbschema/default.esdl`.
8. Apply migrations using the CLI entry point in `source/cli/`.
9. Add Express API endpoints that query Gel using parameterized EdgeQL.
10. Handle Gel errors gracefully by inspecting the error `code` field.

My project stack: [DESCRIBE YOUR STACK HERE - e.g., Node.js 20, TypeScript 5, Express 4, PostgreSQL 15 available on host].

The upstream project is `edgedb`/`gel`. Source is in `source/`. Follow the patterns in USAGE.md exactly.

License and credit

The Gel engine source is licensed under the Apache License 2.0. See source/LICENSE if present, or refer to the upstream repository for the full license text. This block is derived from the geldata/gel open-source project.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.