Skip to main content

Crate icydb

Crate icydb 

Source
Expand description

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 Internal code generation helpers used by macros and tests (not intended for direct use).

  • 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 DbSession::execute_query, 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.

The operational lane contract lives in docs/contracts/READ_ADMISSION.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
db
Module: db
design
diagnostic
Compact diagnostic identity for CLI and canister callers.
prelude
traits
Module: traits
value
visitor

Macros§

db
start

Structs§

Error
Error
ErrorCode
ErrorCode

Enums§

ErrorKind
ErrorKind
ErrorOrigin
ErrorOrigin
QueryErrorKind
QueryErrorKind
RuntimeErrorKind
RuntimeErrorKind

Constants§

VERSION

Functions§

sanitize
validate

Type Aliases§

Create
Generic create-input alias for one entity type.