zmodu with zent

zent (chy3xyz/zent) is an ent-style, schema-as-code ORM for Zig. This page covers how to use it in zmodu modules and where it stops.

• zent v0.97.0 (pinned by both examples), zmodu v0.15.22+, Zig 0.17.0
• Reference implementation: examples/zent-modulith/; upstream examples: zig build run-start / run-complex / run-pool
• Related: MODULE_LAYERS.md · MODULITH.md · BEST_PRACTICES.md · SQLX_DRIVERS.md

1. Orthogonal stacks

The framework default is sqlx, not zent. Use zent per module; never mix drivers in one transaction.

• data.SqlxBackend is the default backend; data.Repository(T) is orm.Orm(SqlxBackend).Repository (src/data.zig).
• build.zig.zon has .dependencies = .{}, so zent is not a framework dependency; applications pin it by git tag (§11). “Commerce and social projects default to zent” is a selection recommendation (§2, §4.8), not a framework default.

Never put a zent.sql_driver.Driver inside zmodu.data.Client. Pools, dialects and migration tables stay separate. examples/_shared/zent_helpers.zig forwards to zent.helpers (StoreEnv, TestEnv, PooledEnv, ShardedEnv); it is example glue, not zmodu core.

2. When to use zent, when to use sqlx

Orchestration and messaging belong to zmodu; the domain graph and row policies to zent; simple tables and existing SQL to sqlx.

Multi-tenancy: TenantContext (JWT or middleware → runtime id) is engine-neutral and used by both. Row isolation follows one engine’s idiom, never both: sqlx modules use TenantInterceptor / DataPermission (zmodu.tenant, zmodu.datapermission); zent modules use a privacy filter or an explicit tenant_id predicate (§8, §9). Doing both gives two sources of truth.

3. Choosing per module

Different modules may pick different stacks. That is the recommended arrangement, not a workaround.

Same-database strong consistency means the same stack, or writes funneled through one persistence layer. Cross-domain side effects use the event bus or outbox. The only shared inputs are allocator, io and the HTTP context. Keep drivers inside persistence.zig; api and service must not leak zent.* or sqlx.* types.

4. Capability value and scenarios

4.1 Edges

O2M/M2O/M2M navigation replaces hand-written joins and junction tables. Use it for order → line → product → tag, org trees, follow graphs and RBAC; skip it for single-table CRUD and warehouse queries.

4.2 Codegen client

Typed client.product.Query() / Create() and predicates, with migrations that track the graph. Use it with many entities and several schema editors; skip it with a large hand-written SQL surface or DBA-owned migrations.

4.3 Privacy and tenant source

Reads and writes carry allow/deny/filter policies; a configured policy without withContext returns PrivacyDenied. CrudApiOpts.tenant_source:

.query lets the client declare its own tenant: changing ?tenant_id= reads another tenant. zmodu audit rule b22 rejects it. Reference: examples/zent-modulith/src/main.zig (.attr + jwtAuthFromCatalog; the dev token route exists only with ZENT_DEV_TOKEN=1).

4.4 Hooks

Before/after validation, audit, soft delete and defaults; before can cancel a write. Use it for soft delete, audit rows, updated_at and one-step state checks; keep cross-service orchestration, sagas and heavy rules in services.

4.5 Scenario map

Simple CRUD, existing SQL and reports go to sqlx; dense graphs with tenant row isolation and write-side cross-cutting rules go to zent; order/payment/outbox, BFF and rate limiting stay ORM-neutral in zmodu. tenant-shop (orchestration and messaging) fits sqlx; “product–category–tag, staff edit only their shop, soft delete and audit” is a zent module.

4.6 Feature reference (v0.20–v0.74)

4.7 Reports and the join boundary

zent is ent-style: relations use edge preloading, not ad-hoc cross-table joins. Prefer client.product.Query() plus WithEdge, or single-table aggregates (CountBy, Sum, GroupBy). For complex reports use zent driver raw SQL (client.driver.query(...)) or a separate zmodu data.sqlx connection, never sharing a transaction across stacks. Give reports their own report/ module with its own sqlx.Client.

Raw SQL does not carry soft-delete, privacy or interceptor predicates, so client.driver.query() silently skips tenant filtering. Splice the same contract in with zent.scope:

const scope = zent.scope.forClient(persist.infos, "product", &client.product, .{});
const frag = try scope.withClause(allocator);   // soft delete -> privacy -> interceptors
defer allocator.free(frag);
const sql = try std.fmt.allocPrint(allocator, "SELECT id, name FROM product WHERE 1=1 {s} ORDER BY id", .{frag});

A policy table without privacy_ctx returns error.PrivacyDenied from withClause instead of unfiltered SQL. :alias qualifies every injected predicate; table is comptime, so a wrong table name is a compile error.

4.8 Commerce and social matrix (v0.30–v0.74)

5. Layer mapping

For one transaction across entities use zent.codegen.client.beginTx, not two driver transactions. Duplicate into plain DTOs in persistence (zent-modulith does this) so Managed and deinitEntity never reach HTTP.

5.1 Write-mode differences

zent’s CreateBuilder.saveInternal iterates only explicitly set values, so the default-override problem does not exist there. On the zmodu side insert/update keep whole-field semantics (null explicitly clears); opt in for defaults or partial updates:

_ = try repo.insertOmitNulls(allocator, entity); // nullable-null columns take the DB default
try repo.updatePartial(allocator, entity);       // only non-null fields change

6. Startup pipeline

Minimal path:

const graph = comptime zent.codegen.graph.buildGraph(&.{ Tenant, Product });
var drv = try zent.sql_sqlite.SQLiteDriver.open(alloc, path);
defer drv.close();
try zent.sql_schema.migrateSchema(alloc, drv.asDriver(), graph.types);
var client = zent.codegen.client.makeClient(graph.types, alloc, drv.asDriver());

Production: use ConnPool and pass asDriver() to makeClient; migrations are conservative by default (drop_columns and allow_data_loss need explicit MigrateOptions); :memory: means one connection. Order: open/pool → migrateSchema → makeClient → inject persistence → start modules → listen.

6.1 Testing

TestEnv creates one in-memory SQLite per test; reset() drops schema tables and re-migrates. It forwards zent.helpers through examples/_shared/zent_helpers.zig; it does not pull zent into zmodu core.

const Env = zent_helpers.TestEnv(infos);
var env = try Env.init(std.testing.allocator);
defer env.deinit();
try env.reset(); // next assertions start from a fresh schema

6.2 Production connection pool

// `openDb(a) !SQLiteDriver` wraps SQLiteDriver.open(a, "app.db").
var pool = try Pool.init(allocator, .{ .io = io, .min_connections = 2, .max_connections = 8, .connect = openDb });
defer pool.deinit();
try zent.sql_schema.migrateSchema(allocator, pool.asDriver(), infos);
var client = zent.codegen.client.makeClient(infos, allocator, pool.asDriver());

Do not leak individual pooled connections to modules. Ensure no borrow or query is in flight before closing the pool.

6.3 Observability

sql_logger.Logger callbacks take no context, so forward to std.log (or an application StructuredLogger).

fn onQuery(c: zent.sql_logger.LogContext) void { std.log.debug("zent query [{s}] {s} ({d}us, {d} rows)", .{ c.table_name, c.sql, c.duration_us, c.rows_affected }); }
fn onExec(c: zent.sql_logger.LogContext) void { std.log.debug("zent exec [{s}] {s} ({d}us, {d} rows)", .{ c.table_name, c.sql, c.duration_us, c.rows_affected }); }
fn onError(c: zent.sql_logger.LogContext) void { std.log.err("zent SQL error [{s}] {s}: {any}", .{ c.table_name, c.sql, c.@"error" }); }
const logger = zent.sql_logger.Logger{ .onQuery = onQuery, .onExec = onExec, .onError = onError };
zent.codegen.client.SetLogger(infos, &client, logger);

Log metadata only; never log passwords, tokens or sensitive values. Put the application trace id in LogContext.trace_id.

6.4 Transactions

zent v0.31+ opens a typed transaction from a shared driver or pool: zent.codegen.beginTxFromDriver(infos, pool.asDriver(), alloc); re-entry degrades to a savepoint. Use it for cron jobs and event consumers.

Use one TxClient for cross-entity writes. For a partial rollback, run savepoints on the underlying Tx, then commit or roll back exactly once and deinit once:

var tx = try zent.codegen.client.beginTx(infos, client);
defer tx.deinit();
_ = try tx.tx.exec("SAVEPOINT order_item", &.{});
// tx.client.order.Create() / tx.client.order_item.Create() ...
_ = try tx.tx.exec("RELEASE SAVEPOINT order_item", &.{});
try tx.commit();

On an unrecoverable error call tx.rollback() and never commit(). Savepoints do not replace the outer commit or rollback.

7. Schema and edges

const field = zent.core.field;
const Schema = zent.core.schema.Schema;

pub const Product = Schema("Product", .{
    .fields = &.{ field.Int("tenant_id"), field.String("name"), field.Int("price_cents") },
});

// With edges: register both sides in the graph and use edge.To / From / M2M.
// pub const edges = &.{ edge.To("products", Product) };

• Table and entity names are stable. Renaming is a migration, never a silent change.
• Every tenant-scoped model declares tenant_id or carries a privacy filter; at least one.
• Indexes, enums, JSON and TimeMixin use the zent schema API, never ad-hoc DDL in services.

8. Persistence contract

const graph = zent.codegen.graph.buildGraph(&.{ model.Tenant, model.Product });
pub const infos = graph.types;
pub const Client = zent.codegen.client.Client(infos);

pub const CatalogStore = struct {
    allocator: std.mem.Allocator,
    client: Client,
    pub fn createProduct(self: *CatalogStore, tenant_id: i64, name: []const u8, price_cents: i64) !i64 {
        var b = try self.client.product.Create();
        defer b.deinit();
        _ = try b.setFieldValue("tenant_id", tenant_id);
        _ = try b.setFieldValue("name", name);
        _ = try b.setFieldValue("price_cents", price_cents);
        const row = try b.Save();
        return row.id;
    }
    pub fn listProducts(self: *CatalogStore, tenant_id: i64) ![]ProductRow {
        var q = self.client.product.Query();
        defer q.deinit();
        _ = try q.Where(.{self.client.product.predicates.tenant_idEQ(.{ .int = tenant_id })});
        var found = try q.All();
        defer self.client.product.deinitRows(&found); // page release, zent >= 0.40
        // duplicate into ProductRow DTOs ...
    }
};

9. Privacy and hooks

• Attach policy to the schema; inject PrivacyContext (roles, tenant, viewer) on the request path.
• Rules are allow / deny / filter; filters suit “only rows of my shop”.
• Test with no context, a wrong tenant and cross-tenant reads; all must fail or return nothing.
• before returns ValidationFailed / Forbidden to cancel a write; after does audit and cache invalidation only.
• Never open a second driver transaction or make a blocking remote call inside a hook.

10. Memory and errors

Persistence raises domain and driver errors; api maps them to HTTP status and text without swallowing I/O or DB errors.

11. Dependency wiring

zent ships a build.zig.zon module named zent. Pin a git tag in production; a path dependency replaces the URL for local work.

.zent = .{
    .url = "https://github.com/chy3xyz/zent/archive/refs/tags/v0.97.0.tar.gz",
    .hash = "<fill after zig fetch>",
},

const zent_dep = b.dependency("zent", .{
    .target = target,
    .optimize = optimize,
    .pg = false,    // zent >= v0.76.0: skip translate-c for drivers you do not import
    .mysql = false,
});
exe_mod.addImport("zent", zent_dep.module("zent"));

Disabling a driver you do import fails at first use (no module named 'pg_c'), never silently. zent-modulith disables pg and mysql; metaverse-creative disables mysql only. End-to-end cost on a developer machine was unchanged (763 MiB / 80 s vs 723 MiB / 82 s), because the skipped steps run in parallel with the SQLite step.

On the zmodu side, path dependencies still addImport("zmodu") and use db_link.Features.sqlite_only so zmodu’s sqlx does not link libpq or mysql. Full rules: SQLX_DRIVERS.md §8.

Upgrade procedure: change the pin → delete .zig-cache → rebuild. Zig 0.17 incremental caches reuse the previously fetched module, so “it compiled” may still be the old version. v0.96.0 → v0.97.0 was verified this way for both examples (zent-modulith smoke 44/0 with no leaks; metaverse-creative zig build demo reports demo_ok).

12. Anti-patterns

13. Checklist

• Schema lives in model.zig; HTTP does not import zent.sql_*
• Startup: open/pool → migrateSchema → makeClient; production uses ConnPool and conservative migrations
• Lists: client.<entity>.deinitRows(&rows) with var rows; builders and transactions defer deinit
• Tenant: predicate or PrivacyContext
• Public return values are DTOs, not zent entity lifetimes
• No zent driver passed into a sqlx client
• Same transaction across modules means the same stack; cross-domain uses the event bus or outbox

14. Upgrade contracts

Run these before reading the table:

zmodu audit .                 # tenant source / bare panic / shared maps / alignCast / allocator ownership / entropy (b19-b24)
zig build check-production    # bare catch / catch unreachable
zig build test                # shape and error-set snapshots, including doc-code consistency

Two traps this repository hit:

• Allocator mismatch on getOwned rows. Rows produced by a function that takes an allocator (the get / getOwned family, queryRowOwned, scanRowsToOwned, AllIn(arena)) are freed with deinitRowWith(allocator, &e) or by the arena. Only driver-scanned rows (Query().All(), builder Save()) go to deinitRow(&e). Mixing them is a cross-allocator free that kills the process; zmodu audit b23 catches it.
• Stale incremental cache. After a pin change, rm -rf .zig-cache (and stale zig-pkg/<old version> directories) before building, or you validate the old module.

15. Practical boundaries

Reference