Claude Skill

api-database-edgedb

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

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_api-database-edgedb_skills_api-database-edgedb-707467a.zip · 20 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/api-database-edgedb/skills/api-database-edgedb
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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

Core Patterns:

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

Query Builder:

Advanced Schema:




<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

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

Failure to follow these rules will cause stale types, silent data bugs, or transaction isolation failures.

</critical_reminders>

Files (skills)
  • examples
    • advanced-schema.md 9.8 KB
      Loading…
    • core.md 12.1 KB
      Loading…
    • query-builder.md 12.8 KB
      Loading…
  • reference.md 10.4 KB
    Loading…
  • SKILL.md 12.3 KB
    ---
    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()`. Connection details are auto-discovered from `gel.toml` (or `edgedb.toml`) or environment variables.
    
    ```typescript
    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.
    
    ```edgeql
    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.
    
    ```bash
    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](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.
    
    ```typescript
    await client.transaction(async (tx) => {
      await tx.execute(`update Account ...`); // tx, not client!
    });
    ```
    
    See [examples/core.md](examples/core.md) for transaction patterns and [examples/query-builder.md](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
    
    **(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)**
    
    **Failure to follow these rules will cause stale types, silent data bugs, or transaction isolation failures.**
    
    </critical_reminders>
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.