Crate icydb 

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.

All low-level execution, storage, and engine internals live in icydb-core and are not part of the public API contract.

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).

• core (internal) Runtime data model, queries, filters, values, and observability. This crate is intentionally hidden behind internal adapters.

• error Shared error types for generated code and runtime boundaries.

• macros Derive macros for entities, schemas, and views.

• schema Schema AST, builders, and validation utilities.

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

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

The __internal module exposes selected engine internals strictly for generated code and macro expansion. It is not part of the supported API surface and may change without notice.

Re-exports

pub use error::Error;

pub use icydb_build as build;

pub use icydb_schema as schema;

pub use icydb_schema_derive as macros;

Modules

__reexports

re-exports

base

db

design

Design Prelude For schema/design code (macros, traits, base helpers).

error

key

model

Runtime data model definitions.

obs

Observability: runtime event telemetry (metrics) and storage snapshots.

prelude

Actor Prelude using _ brings traits into scope and avoids name conflicts

traits

types

value

view

visitor

Macros

build

Build-script helper that runs IcyDB codegen for the specified canister actor path.

db

db Access the current canister’s database session; use db!().debug() for verbose tracing.

start

Macros

Constants

VERSION

Consts

Functions

deserialize

Deserialize bytes into a concrete visitable value.

sanitize

Helpers

serialize

Serialize a visitable value into bytes.

validate

Validate a visitable tree, collecting issues by path.