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.

Hướng dẫn cài đặt đầy đủ và prompt tích hợp sẽ mở khóa sau khi mua.