[artile]

Today a user writes the Schemas of a table's rows by hand, next to the table. They drift from the columns.

Closes #68.
Part of #52.

Changes

• New tableSchemas(table), exported from /clickhouse and /postgres. It derives Schema values (not only types) from the table's columns and its defaults / computed lists.
• Variants use the Model.Class names:
  • select: every column, decoded from the database wire form. Its Type is SelectRowOf<typeof T>.
  • insert: computed columns (ClickHouse MATERIALIZED / ALIAS, computed on table) are absent. Defaulted columns (default, defaultExpr, Postgres identity) and nullable columns are optional (?: A | undefined, as in InsertRow).
  • update: every writable column is optional.
  • json, jsonCreate, jsonUpdate: Schema.toCodecJson(Schema.toType(...)) of the three rows. A DateTime becomes an ISO string; brands and checks stay.
• New type TableSchemas<typeof T>.
• A decoded insert row type-checks in insertInto(T).values(...), and an update row in update(T).set(...) (type test).
• Tests: src/ch/table-schemas.test.ts (ClickHouse and Postgres tables), src/ch/table-schemas.test-d.ts, and a docs example test.
• Docs: a "Row Schemas" section in docs/tables-and-types.md, and docs/reference.md entries. One minor changeset.

Left out

• T.schemas as a property on every table value. A function keeps the Table interface and every table constructor unchanged. A property can come later if you prefer it.
• Primary keys out of update / jsonUpdate. The query-side Table has no primary key at the type level. It is only in the Postgres DDL.
• Sensitive-style columns (absent from the JSON variants) and client-side DateTimeInsert / DateTimeUpdate defaults. These need new column options.
• Build a table from a Model.Class, or a Model.Class from a table. The plain Structs here can feed Schema.Class already.
• SQLite, MySQL and D1: no change is needed, because the function reads only the column codecs. Upstream main has no such dialect yet, so there is no test for them.

Validation

• bun run build: pass.
• bun run typecheck: pass.
• bunx vitest run --testTimeout=60000 --hookTimeout=60000 with a live ClickHouse 26.8.2.7 (EFFECT_ORM_CLICKHOUSE_* set): 61 files passed, 1041 tests passed, 0 skipped.
• node scripts/check-doc-citations.mjs: doc citations ok (25 files).
• node scripts/check-exports-documented.mjs: export catalog ok (289 /clickhouse, 207 /postgres).
• node scripts/check-doc-examples.mjs: doc examples ok (21 files typechecked).
• bun scripts/check-package.ts: tarball imports, types, compilation and codecs passed; CommonJS consumer ok.
• Upstream CI for a fork PR waits for a maintainer to approve the run.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 50 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 97d6a359-7d91-453f-bdc7-a73c1f1c5d9c

Commits

Reviewing files that changed from the base of the PR and between b57faf1 and 9a350b1.

Files selected for processing: 8

• .changeset/table-row-schemas.md
• docs/reference.md
• docs/tables-and-types.md
• src/ch/table-schemas.test-d.ts
• src/ch/table-schemas.test.ts
• src/ch/table-schemas.ts
• src/core.ts
• src/docs-examples.test.ts

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[Makisuo]

Merge-readiness pass (merge commit 9a350b1, no rebase):

• Merged current main (SQLite/D1 dialects, SQLite DDL and migrations, Effect 4.0.6, afterCommit). One conflict in docs/reference.md: kept the tableSchemas row next to main's updated insertInto row.
• tableSchemas comes from core, so /sqlite exports it as well. Added SQLite coverage:
  • src/ch/table-schemas.test.ts: select/insert read SQLite's wire forms (0/1 booleans, timestamp text, JSON text, safe-integer check), and json/jsonCreate read plain JSON. A node:sqlite round trip renders the table with renderSqliteSchema, inserts a decoded jsonCreate body and reads the row back. The table uses a renamed column (name: "org_id") and a defaulted column.
  • src/ch/table-schemas.test-d.ts: the SQLite insert row type, and a check that SQLite.insertInto(...).values accepts it.
• Docs and changeset now say /sqlite too.

Verification (local, ClickHouse 26.8):

• bun run build, bun run typecheck: pass.
• bun run test: 1438/1439 passed. The one failure was generated fixtures: union results agree (clickhouse-join-nulls), a ClickHouse "Division by zero" on Id % Id. That is the known fuzz flake that test(fuzz): fix three flaky generated-data properties #131 fixes, not this PR. The three doc checks pass when run separately.
• FUZZ_SCALE=0.3 bunx vitest run tests/fuzz: 269/269 passed.

CI run 41472561237: the ClickHouse 26.8 job passed. The 26.2 job failed only on two "generated fixtures" fuzz properties with ClickHouse "Division by zero", the known flake that #131 fixes.