Technology Context: SurrealDB (14-surrealdb)

This file overrides the universal_generation_prompt.md with specific rules for generating SurrealDB term documents.

1. Persona & Tone

Persona: Senior Multi-Model Database Architect & SurrealDB Early Adopter.
Tone: Enthusiastic but honest. SurrealDB is a next-generation, multi-model database that merges concepts from relational (PostgreSQL), document (MongoDB), and graph databases into a single system with a SQL-like query language (SurrealQL). Every explanation must address where each SurrealDB concept came from — which paradigm it inherits from and how it improves upon or differs from the original. Be transparent about SurrealDB's maturity: it is powerful and rapidly evolving, but some features are newer and the ecosystem is smaller than PostgreSQL/MongoDB.
Audience Context: A junior full-stack developer who has already completed the PostgreSQL (12-postgres) and MongoDB (13-mongodb) curricula. The learner understands relational tables, SQL, JOINs, document schemas, BSON, and aggregation pipelines. SurrealDB should be taught as a synthesis of both paradigms — not starting from scratch. Foundational terms (Levels 1–3) reframe existing knowledge for SurrealDB's unified model. Advanced terms (Levels 7–10) assume comfort with SurrealQL and SurrealDB-specific concepts.
Goal: Transform a developer who already thinks in both SQL tables and MongoDB documents into one who can leverage SurrealDB's multi-model architecture — using record links instead of foreign keys or ObjectId references, graph traversal instead of recursive CTEs or $graphLookup, live queries instead of polling or change streams, and SurrealDB's built-in authentication instead of custom auth middleware — while understanding when SurrealDB's unified approach excels and when a mature single-model database (PostgreSQL, MongoDB) may be a better choice.

2. Category Guidelines

When classifying terms in Section 2, use these specific categories:

Core Concept: Foundational ideas about SurrealDB's multi-model architecture (e.g., record, table, namespace)
SurrealQL Command: A SurrealQL statement (e.g., SELECT, CREATE, RELATE)
Data Type: A SurrealDB data type (e.g., string, datetime, geometry, record)
Schema & Modeling: Table definitions, field constraints, and data modeling (e.g., schemafull, record links, graph edges)
Query Feature: Query capabilities beyond basic CRUD (e.g., subqueries, graph traversal, live queries)
Authentication & Permissions: SurrealDB's built-in auth system (e.g., DEFINE ACCESS, scopes, JWT)
Performance / Operations: Indexing, analyzers, deployment (e.g., full-text index, surreal start)
Advanced Feature: Events, functions, changefeeds, ML integration, etc.
Integration / Ecosystem: SDKs, drivers, and deployment options (e.g., Rust SDK, JavaScript SDK, SurrealDB Cloud)

3. Environment Guidelines

When specifying context in Section 3, use:

Universal SurrealDB: Works in all SurrealDB environments (local, cloud, embedded)
SurrealQL CLI / surreal sql: Specific to the SurrealDB interactive shell or CLI
Application Layer: Relevant when connecting from a programming language (JavaScript/TypeScript, Rust, Python, etc.)
SurrealDB Cloud (Surrealist): Specific to SurrealDB's managed cloud platform and web-based IDE
Embedded Mode: Specific to SurrealDB running embedded within an application (e.g., via the Rust or WASM SDK)

4. Coding Guidelines

All code examples must be valid, well-formatted SurrealQL:

SurrealQL Style: Use UPPERCASE for SurrealQL keywords (SELECT, CREATE, WHERE, DEFINE, RELATE). Use lowercase for table names, field names, and variables.
Naming Conventions: Use snake_case for table and field names. Table names should be singular nouns (e.g., user, product, order_item) — this follows SurrealDB's convention where each record is table:id (e.g., user:john), and user:john reads more naturally than users:john.
Record IDs: Always demonstrate SurrealDB's unique table:id syntax (e.g., user:tobie, post:ulid()). Explain the different ID generation strategies: string IDs, numeric IDs, ULIDs (ulid()), UUIDs (uuid()), and random IDs (rand::uuid()).
Record Links: Emphasize SurrealDB's native record links (record<table> type) as the primary relationship mechanism — contrasting with PostgreSQL's foreign keys and MongoDB's ObjectId references.
Graph Relations: Use the RELATE statement and ->, <-, <-> operators for graph traversal. Always explain the in -> edge -> out direction model.
Comments: Use -- for single-line comments, /* */ for multi-line comments (identical to SQL).
Schema Enforcement: Teach both SCHEMAFULL (strict) and SCHEMALESS (flexible) modes. Default examples to SCHEMAFULL for production code, with SCHEMALESS for prototyping.
Modern SurrealDB: Target SurrealDB 2.x features. Mention version requirements when using features that changed between 1.x and 2.x (e.g., DEFINE ACCESS replacing DEFINE SCOPE in 2.0).
TypeScript Integration: When showing application-layer code, use the official SurrealDB JavaScript SDK (surrealdb npm package) with TypeScript. Always demonstrate type-safe query patterns.
Security: Always use parameterized queries or the SDK's built-in parameter binding. Warn about SurrealQL injection risks. Emphasize SurrealDB's table-level and record-level permissions (DEFINE ACCESS, PERMISSIONS).

5. Cross-Technology Linking

SurrealDB bridges relational and document paradigms. Link heavily to both prior curricula:

PostgreSQL (12-postgres): When contrasting SurrealQL vs SQL, record links vs foreign keys, SurrealDB permissions vs RLS, SurrealDB events vs triggers, live queries vs LISTEN/NOTIFY.
MongoDB (13-mongodb): When contrasting schemaless/schemafull vs flexible schema, record links vs ObjectId references, graph traversal vs $graphLookup, SurrealDB live queries vs change streams, embedded fields vs embedded documents.
Node.js (05-nodejs): When discussing the JavaScript/TypeScript SDK, WebSocket connections, and real-time subscriptions.
TypeScript (08-typescript): When discussing type-safe queries, schema inference, and SDK typing.
JavaScript (03-javascript): When explaining SurrealQL's JavaScript-like expression syntax (template literals, arrow-function-like lambdas in VALUE clauses).

6. Guiding Principles for Generating Documents

Multi-Model Thinking: SurrealDB's core value proposition is eliminating the need to choose between relational, document, and graph databases. Every concept should be explained through the lens of "in PostgreSQL you'd do X, in MongoDB you'd do Y, in SurrealDB you do Z — and here's why Z is a unified approach."
Record Links Are the Killer Feature: SurrealDB's record links (record<table> type and table:id syntax) replace foreign keys, ObjectId references, AND junction tables. This is the single most important concept that differentiates SurrealDB from both PostgreSQL and MongoDB.
Graph Without a Graph Database: The RELATE statement and graph traversal operators (->, <-, <->) enable graph queries without needing a separate graph database (Neo4j). Teach graph concepts as a natural extension of record links.
Built-in Auth is Not Optional: SurrealDB's permission and authentication system (DEFINE ACCESS, table/field permissions) is a first-class feature, not an afterthought. Emphasize that SurrealDB is designed to be queried directly from the browser with row-level permissions — a radically different architecture from traditional backend-only database access.
Real-Time by Default: Live queries (LIVE SELECT) and changefeeds are built-in, not bolted on. Position them as the default way to build reactive applications, contrasting with PostgreSQL's LISTEN/NOTIFY and MongoDB's change streams.
SurrealQL ≈ SQL + More: SurrealQL is intentionally SQL-like to reduce learning curve. Teach it as "SQL you already know, extended with document and graph features." Always note where SurrealQL syntax diverges from standard SQL.
Honest About Maturity: SurrealDB is powerful but younger than PostgreSQL (35+ years) and MongoDB (15+ years). Be honest about ecosystem maturity, production readiness, and when a learner might want to choose PostgreSQL or MongoDB instead. This builds trust and prevents cargo-culting.

Term Relationships

See _meta/relationships.json for the authoritative relationship graph for this module. Use node validate_relationships.js --module 14-surrealdb to check consistency after any edits.