kysely-codegen

name	kysely-codegen
description	Use this skill when working with database types, running type generation, or helping developers build custom Kysely types on top of the generated schema.

Overview

Overlord uses kysely-codegen to generate TypeScript interfaces from the live database schema. All generated and custom types live in src/types/.

src/types/
  db.ts        ← auto-generated by kysely-codegen (do not edit manually)
  index.ts     ← re-exports all generated types; add custom types here or in new files

Running Codegen

yarn generate

This script does two things:

1. Runs yarn start:local to ensure the local SQLite database is up-to-date with all migrations.
2. Runs kysely-codegen against database/.local/Overlord.sqlite and writes the output to src/types/db.ts.

Re-run yarn generate after every schema migration to keep types in sync.

PostgreSQL

To generate against a PostgreSQL database instead of the local SQLite default, run codegen directly with your connection URL:

kysely-codegen --url "$DATABASE_URL" --out-file src/types/db.ts

Or set DATABASE_URL in a .env file and use --env-file:

kysely-codegen --env-file .env --out-file src/types/db.ts

kysely-codegen infers the dialect from the URL scheme (postgres:// → PostgreSQL, file: / path → SQLite). You can also pass --dialect postgres explicitly.

Building Custom Types

src/types/db.ts contains raw table interfaces (one per table) and the top-level DB type used to construct a Kysely<DB> instance. The Generated<T> helper marks columns that have database-side defaults.

Kysely exports utility types for deriving safe row shapes:

Utility	Use for
Selectable<T>	Rows returned by SELECT
Insertable<T>	Rows passed to INSERT
Updateable<T>	Partial rows passed to UPDATE

Where to put custom types

Add derived types to src/types/index.ts (for a few shared types) or create additional files in src/types/ (e.g. src/types/tickets.ts) and re-export them from index.ts.

Example

// src/types/tickets.ts
import type { Selectable, Insertable } from 'kysely';
import type { Tickets } from './db.js';

export type TicketRow = Selectable<Tickets>;
export type NewTicket = Insertable<Tickets>;

// Narrowed type for tickets that haven't been deleted
export type ActiveTicket = TicketRow & { deleted_at: null };

// Narrowed type for the status vocabulary
export type TicketStatusType =
  | 'draft'
  | 'execute'
  | 'review'
  | 'complete'
  | 'blocked'
  | 'cancelled';

Then re-export from src/types/index.ts:

export type { TicketRow, NewTicket, ActiveTicket, TicketStatusType } from './tickets.js';

Importing types in service code

import type { DB } from '../types/index.js';
import type { TicketRow } from '../types/index.js';
import { Kysely } from 'kysely';

function getTicket(db: Kysely<DB>, id: string): Promise<TicketRow | undefined> {
  return db
    .selectFrom('tickets')
    .selectAll()
    .where('id', '=', id)
    .executeTakeFirst();
}

Keeping db.ts in Version Control

src/types/db.ts should be committed so that CI type-checking and other developers can run yarn typecheck without needing a local database. Always regenerate and commit it alongside schema migrations.

Configuration Reference

Key kysely-codegen flags used by this project:

Flag	Value	Purpose
--dialect	sqlite	Dialect for local SQLite dev DB
--url	database/.local/Overlord.sqlite	Path to local SQLite file
--out-file	src/types/db.ts	Output location

Run kysely-codegen --help to see all available options.