---
title: "SurrealQL: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/surrealdb-surrealql/
description: "SurrealDB skill for writing, adapting and troubleshooting SurrealQL statements, with statement tables linked to the docs and instructions to validate and format queries with the SurrealDB CLI and surql-fmt."
---

# SurrealQL: review, setup & limitations · Undominated.ai

> SurrealDB skill for writing, adapting and troubleshooting SurrealQL statements, with statement tables linked to the docs and instructions to validate and format queries with the SurrealDB CLI and surql-fmt.

[← Explore all skills](/skills/)

DATABASES / SurrealDB

# SurrealQL

SurrealDB skill for writing, adapting and troubleshooting SurrealQL statements, with statement tables linked to the docs and instructions to validate and format queries with the SurrealDB CLI and surql-fmt.

 [See setup guidance ↓](#setup)[Original source ↗](https://surrealdb.com)

SOURCE REVIEW

 Reviewed 2026-10-21
 Evidence 3 linked sources
 Publisher SurrealDB
 Licence [MIT ↗](https://github.com/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/LICENSE)
 Revision b139bf713490
 [Read what was—and wasn’t—checked ↓](#review)

“Generate and modify SurrealQL queries to interact with SurrealDB databases. This includes creating and retrieving records, designing and managing schemas, establishing and querying graph relationships, performing live (real-time) queries, and leveraging all unique SurrealQL features for advanced database workflows. Use this skill whenever users need to write, adapt, or troubleshoot SurrealQL statements.”

 [SurrealDB · upstream description ↗](https://github.com/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/skills/surrealql/SKILL.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - Tables map SurrealQL query, schema and control-flow statements, from SELECT and LIVE SELECT to DEFINE TABLE, DEFINE INDEX and BEGIN / COMMIT, to their surrealdb.com docs pages, with references for querying, schema and values.
- It targets current SurrealDB 3.x syntax unless the user explicitly asks for an older version, and tells the agent to check the active version with `surreal version`, or otherwise to read the latest released version, published as a plain string at https://download.surrealdb.com.
- README.md prints a single-skill install line for it, `npx skills add surrealdb/agent-skills --skill surrealql`.

### A good fit for

 - Write or adapt SELECT, CREATE, UPSERT, RELATE and LIVE SELECT statements in current SurrealQL
- Define tables, fields, indexes and events with DEFINE statements
- Convert a query from another query language to SurrealQL
- Validate a .surql file with surreal validate and format it with surql-fmt

### Weigh up before choosing

 - The skill directory skills/surrealql last changed in a commit dated 2026-06-16; the pinned revision is dated 2026-09-29. SKILL.md metadata says version 0.2.0.
- Validation needs the SurrealDB CLI; SKILL.md says it may fail due to version differences and works only on full queries or values, not partial statements. `surreal validate --stdin` is available since SurrealDB v3.1.0.
- When a NodeJS-like runtime is available, formatting runs `npx @surrealdb/surql-fmt` with no package version pinned, and its `--write` form formats files in place.
- Without the CLI, SKILL.md has the agent read the latest released version with `curl -s https://download.surrealdb.com`, a request to SurrealDB's download host.
- SKILL.md says SurrealQL is not ANSI-SQL and changes between releases, and treats https://surrealdb.com/docs as the source of truth for current syntax.
- LICENSE is the MIT License with the line Copyright (c) 2026 SurrealDB Ltd.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - skills/surrealql/SKILL.md at b139bf713490830384cb59f3ef1696e98e32223f
- README.md at b139bf713490830384cb59f3ef1696e98e32223f
- LICENSE at b139bf713490830384cb59f3ef1696e98e32223f
- skills/surrealql/references/querying.md, schema.md and values.md at b139bf713490830384cb59f3ef1696e98e32223f: scanned for commands and URLs; they hold SurrealQL examples and docs links
- Repository tree at b139bf713490830384cb59f3ef1696e98e32223f: 10 SKILL.md files

### Our findings

 - SKILL.md addresses commands to the agent: run `surreal version` if the CLI is installed (line 32), otherwise `curl -s https://download.surrealdb.com` (line 37).
- It says the agent should always validate generated or modified queries with the SurrealDB CLI if available (line 124), using `surreal validate` on a file, a glob or stdin.
- If a NodeJS-like runtime is available, it says the agent should always format queries presented to users, migration files and .surql files with `npx @surrealdb/surql-fmt`, which names no package version (lines 141-160).
- SKILL.md names no database connection, credentials or environment variables; the skill has no scripts.

### Not established by this review

 - Not executed: it was not installed or run.
- No query was generated, validated or formatted, and no SurrealDB instance or npm package was contacted.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Add a skill to your workflow.

[Upstream setup instructions ↗](https://github.com/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/README.md)

DOCUMENTED COMMAND

 npx skills add surrealdb/agent-skills --skill surrealql Copy command ↗

Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.

 - Run the README line `npx skills add surrealdb/agent-skills --skill surrealql` to add this skill; `npx skills add surrealdb/agent-skills` without --skill adds all 10 skills in the repository.
- For a local install, README.md says to clone the repository and copy the skills/ directory to where the coding agent reads its skills; that copies all 10 skills, not this one alone.

### Before you start

 - A NodeJS-like runtime for npx; SKILL.md formats with surql-fmt only if one is available
- The SurrealDB CLI (surreal) for version checks and validation, if available

### Compatibility

Claude Code · GitHub Copilot · Cursor · Cline

### Implementation

SurrealQL

### May run the SurrealDB CLI, curl and npx locally

 - Runs `surreal version` if the SurrealDB CLI is installed; otherwise `curl -s https://download.surrealdb.com` to read the latest released version.
- Is told to always validate generated or modified queries with `surreal validate` when the CLI is available, on files, globs or stdin.
- If a NodeJS-like runtime is available, is told to always format queries shown to users, migration files and .surql files with `npx @surrealdb/surql-fmt`, with no package version pinned; `--write` formats files in place.
- Consults https://surrealdb.com/docs as the source of truth for current syntax.

### Cost model

MIT skill text. The files read do not state a fee for the skill, the SurrealDB CLI or the surql-fmt package.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [surrealql SKILL.md at b139bf71 ↗](https://github.com/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/skills/surrealql/SKILL.md) Checked 2026-10-21 https://github.com/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/skills/surrealql/SKILL.md Supports: upstreamDescription, whySelected, bestFor, limitations, access, install.prerequisites, review.findings
- [Repository README at b139bf71 ↗](https://github.com/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/README.md) Checked 2026-10-21 https://github.com/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/README.md Supports: install, compatibility, homepage, whySelected
- [MIT LICENSE at b139bf71 ↗](https://github.com/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/LICENSE) Checked 2026-10-21 https://github.com/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/LICENSE Supports: license, limitations

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### CockroachDB SQL ↗ Cockroach Labs skill that turns a natural-language request into CockroachDB SQL, applies the relevant rule files with 00-fundamental-principles.md first, and tells the agent to run EXPLAIN on every generated query when a cluster connection is available.](/skills/cockroachlabs-cockroachdb-sql/)[### MongoDB schema design ↗ Pins MongoDB's schema-design skill, which separates read checks from writes and says write tools need an explicit yes.](/skills/mongodb-schema-design/)[### Postgres ↗ Timescale's postgres skill from pg-aiguide: a dispatcher that sends the agent to nine reference guides for schema exploration, table design, pgvector and hybrid search, TimescaleDB hypertables and schema migrations.](/skills/timescale-postgres/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
