[artile]

A team that uses effect-orm writes the same insert, update, findById and delete for each table, and must remember the tenant filter every time. Effect core has SqlModel.makeRepository for a Model.Class, but nothing builds it from an effect-orm table.

Closes #75.
Part of #52.

Depends on #99; review only the commits after it. This branch builds on tableSchemas(table) from #99. After #99 merges, I will rebase on main.

Changes

• New makeRepository(table, { idColumn, tenantColumn }) in /database. It returns an Effect that needs Database, like SqlModel.makeRepository needs SqlClient.
• Methods: insert, insertVoid, update, updateVoid, findById, delete. findById and update return an Option (Option.fromNullishOr on the first row). insert returns the stored row with its defaults.
• Input types come from tableSchemas(table): insert takes the insert row, a patch takes the update row. A patch cannot set the id.
• A table with a tenant column gets a TenantRepository. Every method takes the tenant first. Inserts write the tenant column from that argument, and the row type has no tenant column. Reads and writes filter on the tenant column and the id. A patch cannot set the tenant column. A tenant column put into a row or patch at runtime (through a cast) is removed. Each statement compiles as "single-tenant", so a Database with requireTenantScope runs it.
• A call without the tenant does not type-check. The Table type does not carry its tenant column (it is widened to string on purpose), so makeRepository checks tenantColumn against table.tenantColumn when it is built. A mismatch in either direction is a QueryBuilderDefect.
• ClickHouse: insertVoid, updateVoid, findById and delete work. updateVoid is a mutation with mutations_sync = 2, and delete a lightweight delete with lightweight_deletes_sync = 2, so a findById after them reads the write. insert and update need RETURNING, which ClickHouse does not have, so they die with the existing QueryBuilderDefect and write nothing. The choice uses the dialect's clauses (writeSettings, alterTableUpdate), not its name.
• Tests: PGlite behaviour tests (src/database/repository.test.ts, run with requireTenantScope: true), type tests (src/database/repository.test-d.ts), and a live ClickHouse suite (tests/repository.clickhouse.test.ts).
• Docs: a "Repositories" section in docs/database.md, a row in docs/reference.md, the docs index, and a minor changeset.

Left out

• Soft delete (deletedAt). It is optional in the issue. It can be one more option later.
• SQLite, D1 and MySQL. Upstream main has no such dialect yet (SQLite and D1 are feat: add SQLite and Cloudflare D1 query dialects #49). On MySQL, insert would need LAST_INSERT_ID() as in SqlModel.
• The in-memory test Layer from the issue's "Done when" (Test layers: in-memory and SQLite-backed Database #76 / PR feat(database): layerTest, a Database with no server for unit tests #93). The repository is a plain value over Database, so that Layer can wrap it later.
• runOne / runOption from feat(database): runOne, runOption and runNonEmpty cardinality helpers #92. This PR does not depend on it; findById uses Option.fromNullishOr on the first row.
• Spans per method (SqlModel's spanPrefix). Each statement already has its own span from Database.
• A type-level tenant check at makeRepository. It would need Table to carry the tenant column as a literal type, which is a larger change. The check runs when the repository is built.
• FINAL on ClickHouse findById. On a ReplacingMergeTree it can read an older version. The docs say so.

Validation

Run on b4f5c51 against a live ClickHouse 26.8.2.7 (the CI matrix version), with EFFECT_ORM_CLICKHOUSE_URL set, so no suite is skipped:

• bun run build: pass.
• bun run typecheck: pass.
• vitest run --testTimeout=60000 --hookTimeout=60000: pass. Test files: 63 passed (63). Tests: 1051 passed (1051).
• Doc citations, export catalog and doc examples: pass.
• bun scripts/check-package.ts (tarball, types, CommonJS consumer): pass.
• The longer timeouts are only for the local machine, which was under load.
• Upstream CI for fork PRs waits for a maintainer to approve the workflow 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 43 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: d5ff666b-7a38-4e27-9025-6c257295903f

Commits

Reviewing files that changed from the base of the PR and between b57faf1 and 74a123b.

Files selected for processing: 17

• .changeset/make-repository.md
• .changeset/table-row-schemas.md
• docs/README.md
• docs/database.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/database.ts
• src/database/repository.sqlite.test.ts
• src/database/repository.test-d.ts
• src/database/repository.test.ts
• src/database/repository.ts
• src/docs-examples.test.ts
• tests/repository.clickhouse.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 (74a123b):

• Still depends on feat: select, insert, update and json Schemas per table #99, which is open. I merged the feat: select, insert, update and json Schemas per table #99 branch tip 9a350b1 into this branch instead of main directly. 9a350b1 is feat: select, insert, update and json Schemas per table #99 with current main (b57faf1) already merged, so this branch is up to date with main and resolves feat: select, insert, update and json Schemas per table #99's files exactly as feat: select, insert, update and json Schemas per table #99 does. The merge had no conflicts. The diff against 9a350b1 is only this PR's 9 files. Merge feat: select, insert, update and json Schemas per table #99 first, or this PR brings it in.
• SQLite/D1: the new src/database/repository.sqlite.test.ts runs every method on node:sqlite and on a Miniflare D1 under requireTenantScope. It checks that insert and update get their rows through RETURNING. It also checks that update, find and delete from another tenant find nothing and change nothing. No library change was needed. Docs gain a SQLite and D1 note: SQLite-filled columns go in defaults.
• Tenant guard / Tenant guard: ON CONFLICT(id) DO UPDATE can modify another tenant while classified single-tenant #127: the repository writes plain INSERTs and never uses ON CONFLICT, so the upsert hole in Tenant guard: ON CONFLICT(id) DO UPDATE can modify another tenant while classified single-tenant #127 (fixed by fix: guard upsert tenant scope and SQLite rebuild dependencies #130) does not reach it. An insert reusing another tenant's id fails on the key constraint and does not overwrite that row. I documented one ClickHouse caveat: on a ReplacingMergeTree whose ORDER BY leaves out the tenant column, an insertVoid with another tenant's id replaces that tenant's row at merge time. Put the tenant column in ORDER BY.

Verified locally: bun run typecheck passes. bun run test against live ClickHouse 26.8 passes (77 files, 1451 tests), including tests/repository.clickhouse.test.ts. FUZZ_SCALE=0.3 vitest run tests/fuzz passes (9 files, 269 tests). CI run 41473712111.