Crate icydb 

Module: lib

Responsibility: public facade crate surface and generated-code wiring. Does not own: core execution, storage internals, or schema mutation semantics. Boundary: re-exports stable runtime, design-time, and macro-facing surfaces.

icydb

icydb is the public facade crate for the IcyDB runtime. It is the recommended dependency for downstream canister projects.

This crate exposes:

• the stable runtime surface used inside canister actor code,
• schema and design-time helpers for macros and validation,
• and a small set of macros and entry points that wire generated code.

Low-level execution, storage, and engine internals live in icydb-core and are re-exposed selectively through stable facade modules.

Crate layout

• base Design-time helpers, sanitizers, and validators used by schemas and macros.

• build (host builds) Host-side build-script facade for generated actor glue. Downstream canister build.rs files should use this module rather than depending on lower-level implementation crates directly.

• traits / types / value / visitor Stable runtime and schema-facing building blocks used by generated code.

• model / metrics (internal) Runtime model and metrics internals. Exposed for advanced tooling only; not part of the supported semver surface.

• Error / ErrorKind / ErrorOrigin Shared error types for generated code and runtime boundaries.

• macros Derive macros for entities, canisters, and schema helpers.

• schema Schema AST, builders, and validation utilities.

• db The public database façade: session handles, query builders, and typed responses.

Read execution defaults

Ordinary typed/fluent reads through fluent execute, execute_rows, cursor-paged execution, and terminal helpers use the default bounded read-admission gate. Caller-facing endpoints still own caller authorization before entering IcyDB. Trusted read helpers are for controller/admin or maintenance code with a separate resource policy.

Prefer semantic read intents for caller-facing APIs:

• exact rows use primary-key access plus try_one();
• public lists use page(limit) / next_page(limit, cursor) cursor pagination;
• complete small sets use collect_complete();
• exact aggregates use semantic helpers such as count_exact(), sum_exact(field), min_exact_by(field), or avg_exact(field);
• trusted maintenance batches use trusted_read_unchecked().admin_batch(...).

Generated SQL endpoints are controller-gated admin surfaces. They are not generated public read endpoint templates.

The operational lane contract lives in docs/contracts/READ_ADMISSION.md. Endpoint migration recipes live in docs/guides/read-intent.md.

Preludes

• prelude Opinionated runtime prelude for canister actor code. Intended to be glob-imported in lib.rs to keep endpoints concise.

• design::prelude Prelude for schema and design-time code (macros, validators, and base helpers).

Internal boundaries

Generated code targets explicit facade surfaces (traits, model, and __macro) instead of a broad internal-export module.

Re-exports

pub use icydb_schema as schema;

pub use icydb_schema_derive as macros;

Modules

base

Module: base

build

Host-side build-script facade for generated actor glue.

db

Module: db

design

diagnostic

Compact diagnostic identity for CLI and canister callers.

prelude

traits

Module: traits

value

visitor

Macros

db

start

Structs

ConstraintDiagnostic

ConstraintDiagnostic

Error

Error

ErrorCode

ErrorCode

Enums

ConstraintDiagnosticContext

ConstraintDiagnosticContext

ConstraintDiagnosticKind

ConstraintDiagnosticKind

ErrorKind

ErrorKind

ErrorOrigin

ErrorOrigin

QueryErrorKind

QueryErrorKind

RuntimeErrorKind

RuntimeErrorKind

Constants

VERSION

Functions

sanitize

validate

Type Aliases

Create

Generic create-input alias for one entity type.