discord-manager: Skill for Claude Code

Kysely

Everything here documents the repository as it is on main. If main disagrees with this file, main wins: follow it and flag the drift.

These conventions govern every Kysely query and migration in this project. The database is SQLite through better-sqlite3, and the connection is built with CamelCasePlugin, which converts identifiers from camelCase to snake_case automatically.

INSERT is the only write

The application schema is 100% append-only — load the database-design skill for the full doctrine. Application code never calls updateTable, deleteFrom, or truncate on application tables, and never uses .onConflict((oc) => oc.doUpdateSet(...)), because an upsert's update arm is an UPDATE. State changes are new event rows; current state is derived at query time.

.onConflict((oc) => oc.doNothing()) is fine: it makes an insert idempotent without mutating anything, which is exactly what re-observing an already-ingested Discord message needs.

Prefer the builder over raw SQL

Use the schema builder for anything Kysely expresses natively. Reserve sql template literals for what it cannot.

Instead of:

await sql`create index message_revisions_message_id_created_at on message_revisions (message_id, created_at desc)`.execute(db)

Do:

await db.schema
  .createIndex('messageRevisionsMessageIdCreatedAt')
  .on('messageRevisions')
  .columns(['messageId', 'createdAt desc'])
  .execute()

SQLite column types that work as string literals: 'text', 'integer', 'real', 'blob'. There are no other storage classes — text covers ids, timestamps, and JSON payloads; integer covers booleans and counts.

When raw SQL is appropriate

Use sql template literals for:

• Function calls in defaults: col.defaultTo(sql`strftime('%Y-%m-%dT%H:%M:%fZ','now')`)
• Check constraints: .addCheckConstraint('bookmarkAdditionsSource', sql`source in ('reaction','mcp')`)
• Window functions: sql<number>`row_number() over (partition by message_id order by created_at desc, id desc)`
• Pragmas: WAL mode and foreign-key enforcement are set once in app/framework/db.server.ts, never in a migration
• Complex expressions: filtered aggregates, raw subqueries inside a CTE