api-database-edgedb

Gel (formerly EdgeDB) Patterns

Quick Guide: Gel (formerly EdgeDB) is a graph-relational database built on PostgreSQL. Define schemas in .gel files using SDL with types, links, and computed properties. Use gel migration create + gel migrate for schema changes. Query with EdgeQL (set-based, deeply nested shapes) or the TypeScript query builder (e.select, e.insert). Everything in EdgeQL is a set -- empty sets need explicit casts, and operations on sets produce Cartesian products. Use global variables with access policies for row-level security. The query builder requires a running database for code generation (npx @gel/generate edgeql-js).

Naming: EdgeDB was rebranded to Gel in February 2025. The edgedb npm package, CLI, and .esdl extension still work via compatibility shims, but new projects should use gel, @gel/generate, and .gel files.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST run npx @gel/generate edgeql-js after every gel migrate -- the generated query builder is based on the database schema and becomes stale after migrations)

(You MUST cast empty sets explicitly (<str>{}, <int64>{}) -- bare {} is a syntax error because EdgeQL is strongly typed and cannot infer the type of an empty set)

(You MUST understand that all EdgeQL values are sets -- operations on multi-valued expressions produce Cartesian products, not element-wise results)

(You MUST pass the transaction object tx (not client) to ALL query .run() calls inside client.transaction() -- using client inside a transaction runs queries outside the transaction)

(You MUST NOT use volatile functions like datetime_current() in schema-defined computed properties -- use datetime_of_transaction() or datetime_of_statement() instead)

</critical_requirements>

Auto-detection: Gel, gel, EdgeDB, edgedb, EdgeQL, edgeql, .gel, .esdl, dbschema, edgeql-js, createClient, e.select, e.insert, e.update, e.delete, e.params, gel migrate, gel migration, edgedb migrate, SDL schema, backlink, access policy, gel.toml, edgedb.toml

When to use:

• Defining graph-relational schemas with types, links, and computed properties
• Writing type-safe queries with EdgeQL or the TypeScript query builder
• Managing schema migrations with the built-in migration system
• Modeling complex relationships (multi links, backlinks, polymorphism)
• Implementing row-level security with access policies and globals

Key patterns covered:

• Client setup and connection (createClient, DSN, environment variables)
• Schema definition in SDL (types, properties, links, constraints, computed)
• EdgeQL query language (SELECT shapes, INSERT, UPDATE, DELETE)
• TypeScript query builder (e.select, e.insert, e.update, e.delete)
• Migrations workflow (gel migration create, gel migrate)

When NOT to use:

• Simple key-value storage (use a dedicated key-value store)
• Projects that need raw SQL as the primary interface (Gel uses EdgeQL; Gel 6+ adds native SQL support but EdgeQL is the primary interface)
• Environments where you cannot run the Gel server (it is not an embedded database)

Detailed Resources:

• For decision frameworks and quick reference, see [reference.md](reference.md)

Core Patterns:

• [examples/core.md](examples/core.md) - Client setup, schema definition, EdgeQL basics, migration workflow

Query Builder:

• [examples/query-builder.md](examples/query-builder.md) - TypeScript query builder (e.select, e.insert, e.update, e.delete, e.params)

Advanced Schema:

• [examples/advanced-schema.md](examples/advanced-schema.md) - Access policies, backlinks, abstract types, polymorphism, triggers

<philosophy>

Philosophy

Gel is a graph-relational database. It combines the relational model (tables, constraints, ACID) with a graph model (links between objects, deep traversal). The core idea: relationships are first-class citizens, not join tables.

Core principles:

1. Schema is the source of truth -- Define everything in .gel files (or .esdl for legacy projects). Migrations are auto-generated by comparing your schema files against the database state.
2. Links over foreign keys -- Use link to connect types. Gel handles the underlying foreign keys. You never write JOIN -- you traverse links with dot notation.
3. Sets everywhere -- Every value in EdgeQL is a set. A single string is a set of one element. This is the most important mental model shift from SQL.
4. Shapes for projection -- SELECT returns structured, nested objects (like GraphQL responses), not flat rows. You specify the "shape" of what you want.
5. Computed properties are views -- Computed properties and links are not stored; they are evaluated on every query. Use them for derived data.
6. Query builder for TypeScript -- The generated query builder provides compile-time type safety. Prefer it over raw EdgeQL strings in TypeScript projects.

When to use Gel:

• Applications with complex, deeply nested relationships (social graphs, content systems, e-commerce)
• Projects that benefit from graph-style traversals without sacrificing relational integrity
• TypeScript projects that want compile-time type-safe database queries
• Teams that want automatic migration generation from schema changes

When NOT to use:

• Existing projects locked into raw PostgreSQL with extensive stored procedures
• Applications where SQL compatibility is the only acceptable query language (Gel 6+ has native SQL support, but EdgeQL is the primary interface)
• Environments that cannot run the Gel server process

</philosophy>

<patterns>

Core Patterns

Pattern 1: Client Setup

Create a client with createClient(). Connection details are auto-discovered from gel.toml (or edgedb.toml) or environment variables.

import { createClient } from "gel";

const client = createClient(); // auto-discovers from project config
export { client };

Choose the right query method by expected cardinality: query() for sets, querySingle() for optional single, queryRequiredSingle() when result is guaranteed, execute() for side-effect-only statements. See [examples/core.md](examples/core.md) for full client setup patterns.

Pattern 2: Schema Definition (SDL)

Schemas live in dbschema/.gel files (or .esdl for legacy projects). Use required for non-null, link for relationships, constraint exclusive for uniqueness, computed backlinks (.<author[is Post]) for reverse traversal.

# dbschema/default.gel
module default {
  type User {
    required name: str;
    required email: str { constraint exclusive; };
    multi posts := .<author[is Post];  # computed backlink
  }
  type Post {
    required title: str;
    required author: User;             # link, not uuid!
  }
}

Key rule: Always use link for relationships -- never raw uuid properties. See [examples/core.md](examples/core.md) for complete schema patterns with constraints, indexes, and enums.

Pattern 3: EdgeQL Queries

SELECT uses shapes for projection (like GraphQL), INSERT assigns links via subqueries, UPDATE uses +=/-=/:= for multi link manipulation.

select User {
  name, email,
  posts: { title, status } filter .status = Status.published,
} filter .email = 'alice@example.com';

See [examples/core.md](examples/core.md) for SELECT/INSERT/UPDATE/DELETE patterns and parameterized queries.

Pattern 4: Migrations

Gel compares your .gel files against the database and auto-generates migrations.

gel migration create    # generate migration from schema diff (interactive)
gel migrate             # apply pending migrations (idempotent)
npx @gel/generate edgeql-js  # regenerate query builder

Never