/api-database-edgedb

name: api-database-edgedb
description: Graph-relational database with EdgeQL query language, code-first schema, link-based relations, computed properties, and fully typed TypeScript query builder

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

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