/sqldelight create users table         # Create new table
/sqldelight add migration for v5       # Create migration file
/sqldelight explain query pattern      # Understand query patterns
/sqldelight fix foreign key issue      # Debug schema problems

services/sqldelight/src/main/sqldelight/
├── com/eygraber/jellyfin/db/
│   ├── User.sq           # Table definition + queries
│   └── migrations/
│       └── 1.sqm         # Migration files

CREATE TABLE User (
  id TEXT NOT NULL PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT NOT NULL,
  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
);

CREATE INDEX user_email ON User(email);

-- Queries
selectAll:
SELECT * FROM User;

selectById:
SELECT * FROM User WHERE id = ?;

upsert:
INSERT OR REPLACE INTO User(id, name, email) VALUES (?, ?, ?);

deleteById:
DELETE FROM User WHERE id = ?;

-- 1.sqm: Add email column
ALTER TABLE User ADD COLUMN email TEXT NOT NULL DEFAULT '';

-- Or for complex changes (copy-drop-rename):
CREATE TABLE User_new (
  id TEXT NOT NULL PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT NOT NULL
);

INSERT INTO User_new SELECT id, name, '' FROM User;
DROP TABLE User;
ALTER TABLE User_new RENAME TO User;

CREATE TABLE Message (
  id TEXT NOT NULL PRIMARY KEY,
  user_id TEXT NOT NULL REFERENCES User(id) ON DELETE CASCADE
);

CREATE INDEX message_user_id ON Message(user_id);

// Read (single)
withDbReadContext(dispatchers) { queries.selectById(id).executeAsOneOrNull() }

// Read (list)
withDbReadContext(dispatchers) { queries.selectAll().executeAsList() }

// Write
db.withTransaction(dispatchers) { queries.upsert(id, name, email) }

// Observe
queries.selectAll().asFlow().mapToList(dispatchers)

./gradlew :services:sqldelight:assembleDebug