Skills api-database-edgedb

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

install

source · Clone the upstream repo

git clone https://github.com/agents-inc/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/agents-inc/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/dist/plugins/api-database-edgedb/skills/api-database-edgedb" ~/.claude/skills/agents-inc-skills-api-database-edgedb && rm -rf "$T"

manifest: dist/plugins/api-database-edgedb/skills/api-database-edgedb/SKILL.md

source content

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

Core Patterns:

examples/core.md - Client setup, schema definition, EdgeQL basics, migration workflow

Query Builder:

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

Advanced Schema:

examples/advanced-schema.md - Access policies, backlinks, abstract types, polymorphism, triggers

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:

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.
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.
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.
Shapes for projection -- SELECT returns structured, nested objects (like GraphQL responses), not flat rows. You specify the "shape" of what you want.
Computed properties are views -- Computed properties and links are not stored; they are evaluated on every query. Use them for derived data.
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>

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 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 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 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 edit the database with DDL directly -- always modify

.gel

files and use the migration workflow. See examples/core.md for the full workflow including

gel watch --migrate

for prototyping.

Pattern 5: Transactions

Pass

tx

(not

client

) to ALL operations inside

client.transaction()

. Using

client

inside the callback runs queries outside the transaction.

await client.transaction(async (tx) => {
  await tx.execute(`update Account ...`); // tx, not client!
});

See examples/core.md for transaction patterns and examples/query-builder.md for query builder transactions.

</patterns>

<red_flags>

RED FLAGS

High Priority Issues:

Using
```
client
```
instead of
```
tx
```
inside
```
client.transaction()
```
-- queries run outside the transaction and cannot be rolled back
Forgetting to run
```
npx @gel/generate edgeql-js
```
after
```
gel migrate
```
-- query builder types are stale and TypeScript won't catch schema mismatches
Using raw
```
uuid
```
properties instead of
```
link
```
-- defeats Gel's graph traversal and referential integrity
Using
```
datetime_current()
```
in schema-defined computed properties -- volatile functions are forbidden in schema computeds; use
```
datetime_of_statement()
```
or
```
datetime_of_transaction()
```

Medium Priority Issues:

Bare
```
{}
```
for empty sets -- EdgeQL requires explicit type cast (
```
<str>{}
```
,
```
<array<int64>>[]
```
) because the type cannot be inferred from an empty literal
Using
```
:=
```
when you mean
```
+=
```
on multi links in UPDATE --
```
:=
```
replaces the entire set,
```
+=
```
adds to it,
```
-=
```
removes from it
Not specifying
```
filter
```
on UPDATE/DELETE -- without a filter, the operation applies to ALL objects of that type
Editing the database with DDL directly instead of through
```
.gel
```
files + migrations -- causes schema drift between files and database

Common Mistakes:

Expecting element-wise behavior from set operations --
```
{1, 2} + {10, 20}
```
produces
```
{11, 21, 12, 22}
```
(Cartesian product), not
```
{11, 22}
```
Forgetting that
```
select
```
on a single link returns an object (not an ID) -- you do not need to JOIN; just traverse with
```
.
```
Using
```
select count(MyType)
```
and expecting
```
querySingle
```
to work --
```
count()
```
always returns exactly one value, so use
```
queryRequiredSingle
```
Defining a computed backlink but forgetting the type filter --
```
.<author
```
without
```
[is Post]
```
returns all types that have an
```
author
```
link

Gotchas & Edge Cases:

Computed properties are not stored -- they are re-evaluated on every query, which can be expensive for complex expressions
```
required
```
on a multi link means "at least one" -- an empty set violates the constraint, which can be surprising
String concatenation uses
```
++
```
not
```
+
```
-- the
```
+
```
operator is for arithmetic only
```
LIMIT 1
```
does NOT make a query return a singleton for cardinality purposes -- use
```
filter .id = <uuid>$id
```
(exclusive constraint) for the query builder to infer singleton cardinality
Multi links are unordered sets -- if you need ordering, add an
```
order by
```
in your query or use an intermediate type with an
```
order
```
property
Backlinks (
```
.<link_name
```
) default to
```
multi
```
cardinality -- use
```
single
```
keyword explicitly if you know the relationship is one-to-one
EdgeDB branches (v5+) are separate database copies, not lightweight references -- branching a large database takes time and disk space proportional to the data size

</red_flags>

<critical_reminders>

CRITICAL REMINDERS