# Using Sqlfu

> Using sqlfu

- Skill: `iterate/using-sqlfu` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iterate/using-sqlfu`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iterate/using-sqlfu/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: iterate (https://skillmd.com/u/iterate)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iterate/using-sqlfu

---


# Using sqlfu

`sqlfu` is a SQL-first data toolkit. If this skill triggered, treat the current project/package as using sqlfu for its database workflow: SQL is the authored source and TypeScript is generated from it.

## First read the config

Find the nearest `sqlfu.config.ts` for the project/package you are changing. It tells you where sqlfu's files live:

- `definitions`: desired schema SQL.
- `migrations`: ordered migration history, if the project uses migrations.
- `queries`: checked-in `.sql` query files.
- `db`: the database used by `migrate`, `check`, `sync`, `goto`, `baseline`, and the UI, if configured.
- `generate`: typegen options such as schema authority, runtime validators, sync wrappers, and import extension.

Paths are relative to the config file. Do not assume the defaults if the config says otherwise.

## Source files

- Edit `definitions.sql` or the configured `definitions` file when changing the desired schema.
- Do not hand-author a new migration file. Run `sqlfu draft`, then review and edit the drafted SQL if needed.
- Edit query `.sql` files under the configured `queries` directory. Generated wrappers live under `<queries>/.generated/`; do not edit them directly.

## Schema changes

When `migrations` is configured:

1. Update the configured `definitions` file.
2. Run `sqlfu draft`.
3. Review the new migration. Pay attention to renames, destructive changes, backfills, and SQLite table rebuilds.
4. Run `sqlfu migrate` for the configured dev database.
5. Run `sqlfu generate` if generated outputs may have changed.
6. Run `sqlfu check` before considering the schema work complete.

`sqlfu draft` derives a migration filename when no name is supplied. Only pass an explicit name when the user or repo convention calls for one.

When `migrations` is not configured, there is no migration history to draft. Update the configured `definitions` file and run the commands that still apply for the project, usually `sqlfu generate` and any repo tests.

## Query changes

1. Add or edit a `.sql` file under the configured `queries` directory.
2. Run `sqlfu generate`.
3. Import and call the generated wrapper from application code.

If generated TypeScript looks wrong, fix the SQL source or config first. The generated file is output, not the source of truth.

## Useful commands

- `sqlfu init`: create a new sqlfu project.
- `sqlfu config`: print the resolved project config.
- `sqlfu draft`: create a reviewable migration from the definitions-vs-migrations diff.
- `sqlfu migrate`: apply pending migrations to the configured database.
- `sqlfu pending`: list unapplied migration files.
- `sqlfu applied`: list migrations recorded in the database.
- `sqlfu goto <target>`: move the database schema and migration history to a target migration.
- `sqlfu baseline <target>`: update migration history to a target without changing live schema.
- `sqlfu sync`: push the desired schema directly to the live database; use for local development only.
- `sqlfu generate`: regenerate TypeScript outputs from checked-in query files.
- `sqlfu check`: verify the repo and configured database agree, and report recommended next actions.
- `sqlfu` or `sqlfu serve`: start the local backend for `https://sqlfu.dev/ui`.

Use the project's normal command runner for these commands, such as a package script, `pnpm sqlfu ...`, `npx sqlfu ...`, or a local/global `sqlfu` binary already available in the environment.