Discordlancer's SurrealDB conventions - the schema, the append-only history tables, record IDs, money, transactions, connecting and testing. Use whenever work touches src/db/, schema.surql, queries, tables, fields, indexes, events, stages stored in the database, or database tests, even if the user only says "save this", "record it", "add a field" or "the database".
92%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Our database is SurrealDB 4 on SurrealDB Cloud ("Earth"): namespace freelance, database bot. Read the vendor skills surrealdb-js and surrealql for the general API; this skill covers how we use it and what we learned the hard way. The schema is src/db/schema.surql, and the data model is described in PLAN.md.
connectDatabase(env) from src/db/client.ts: one long-lived WebSocket connection. The SDK signs in again and reconnects by itself./signin. The same user signs in fine over the WebSocket RPC, which the SDK uses. Don't build anything on the HTTP endpoints.db.close() hangs against SurrealDB 4, because the WebSocket close handshake never finishes. Always use closeDatabase(db), which gives up after 3 seconds. A script calls process.exit() after it.@surrealdb/node 3.2.0 or later. Both are pinned on purpose; see PLAN.md.OVERWRITE, so applySchema() is safe to run again. The bot applies it at startup, and npm run db:migrate does it by hand.SCHEMAFULL.FLEXIBLE comes after TYPE: TYPE option<object> FLEXIBLE. Before it is a parse error in SurrealDB 4, and one bad statement rejects the whole schema.option<...>. When writing, leave an absent field out of the object rather than sending undefined.created_at ... DEFAULT time::now() READONLY and updated_at ... VALUE time::now();VALUE time::now() READONLY, so the bot can't backdate them.STAGES in src/domain/stages.ts. A test checks this.schema.surql.test/db/schema.test.ts.PLAN.md.event, spec, quote, agreement and payment are history. Code only ever creates them.
DEFINE EVENT OVERWRITE append_only ON <table> WHEN $event IN ["UPDATE", "DELETE"] THEN { THROW "..." }.
This was proven on 9 Nov, both in memory and on the cloud server. UPDATE, UPSERT and DELETE are refused, and the record is left unchanged.recordEvent() in src/db/events.ts. Correct a mistake with a new event, never an edit.safeRecord() in src/discord/client.ts. It logs a failed write instead of throwing.Projects use their name as the record ID: new RecordId('project', name).
Results come back as SDK classes, not plain JS values: RecordId, DateTime. Compare them with toString() or JSON.stringify, not ===. Parse them with Zod before trusting them.
Money is an int of micro-USDC (6 decimals). Convert with src/domain/money.ts, never with floats.
Unique indexes:
A duplicate throws an error whose message contains "already". That's how a retry is made safe.
$name), never build SurrealQL from strings. A field name in a query must come from our code, never from a user.db.query() returns one array per statement, and throws when a statement fails.BEGIN TRANSACTION; ... COMMIT TRANSACTION;), through one function in src/db/projects.ts, which is added in phase 2.test/helpers/db.ts gives memoryDb(): an in-memory SurrealDB 4 with the real schema applied. It needs no network and no keys.pool: 'forks'), because the engine is a native module.CANCEL TRANSACTION, so nothing is left behind.boranfurkan/discordlancer
6bd7b62
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.