From cbe57244342701b99b01a329febd6afdef1fb9f3 Mon Sep 17 00:00:00 2001
From: ilbertt <luca.berte98@hotmail.it>
Date: Mon, 5 Oct 2026 17:07:14 +0200
Subject: [PATCH] docs(examples): demonstrate all check flags

---
 examples/check-only/README.md    | 16 ++++++++++++----
 examples/check-only/package.json |  3 +++
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/examples/check-only/README.md b/examples/check-only/README.md
index 67cfcea..039d34f 100644
--- a/examples/check-only/README.md
+++ b/examples/check-only/README.md
@@ -12,7 +12,15 @@ query name is unknown to `tsc`, so every query carries a `// @ts-expect-error`;
 `tsc` still runs over the rest of the file, and the describe-time `--check-queries`
 pass is the real gate (`check:types` runs it before `tsc`).
 
-Break a query — select a column that doesn't exist — and `check:queries` fails with
-the real Postgres error, pointing at the file and line. `--check-queries` ignores
-output freshness entirely; the sibling `--check-stale` (or `--check` for both) is
-what guards a committed `queries.gen.ts` in the typed lane.
+Run these commands from this directory; all write nothing:
+
+| Command | Flags | Checks |
+| --- | --- | --- |
+| `bun run check:queries` | `--check-queries` | Queries plan against the schema; errors point at the file and line. |
+| `bun run check:stale` | `--check-stale` | Generated types match the current queries and schema. |
+| `bun run check:migration-order` | `--check-queries --check-migration-order '^\d+'` | Queries are valid and migration prefixes are present, unique, and the same width. |
+| `bun run check` | `--check` | Query validity and generated-type freshness. |
+
+`check:stale` and `check` fail here because `queries.gen.ts` is intentionally absent;
+use them in the typed lane. `--check` doesn't include migration order. The
+migration-order command adds `--check-queries` to avoid generating types.
diff --git a/examples/check-only/package.json b/examples/check-only/package.json
index 70efcdd..a5e69ab 100644
--- a/examples/check-only/package.json
+++ b/examples/check-only/package.json
@@ -3,7 +3,10 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "check": "bun-sqlgen generate 'src/**/*.ts' --migrations src/db/migrations --check",
     "check:queries": "bun-sqlgen generate 'src/**/*.ts' --migrations src/db/migrations --check-queries",
+    "check:stale": "bun-sqlgen generate 'src/**/*.ts' --migrations src/db/migrations --check-stale",
+    "check:migration-order": "bun-sqlgen generate 'src/**/*.ts' --migrations src/db/migrations --check-queries --check-migration-order '^\\d+'",
     "check:types": "bun run check:queries && bun run --bun tsc"
   },
   "devDependencies": {