Skip to main content

Crate ic_db

Crate ic_db 

Source
Expand description

Experimental IC database: compiled schemas and synchronous bounded records. Schema modules can import the declaration attributes and value types from design::prelude.

This M1 slice supports 8/16/32/64/128-bit integers, U256, Ulid, Date, Timestamp, Duration, Decimal, finite Float32/Float64, Bool, Principal, Account/Subaccount and bounded Text/Blob, with optional values. Named records and unit/payload enums support bounded recursion via explicit indirection and ordered lists; traversals share byte, depth, structured-value and total collection-item limits. Sets/maps use strict scalar/unit-enum key order. Secondary indexes admit integers, Ulid, Date, Timestamp, Duration, Decimal, finite floats, Account/Subaccount, Principal, Bool, Text and unit enums, including optional values; primary keys require non-optional integer, U256, Ulid, Principal, Account or Subaccount fields. References use the target’s exact key type; absence has no target, while every present target must survive the batch. Atomicity relies on the enclosing IC message: after persistent mutation starts, supplier failures trap. A later application trap also rolls back the batch. Native callers must discard their runtime after a mutation panic. No SQL, endpoint exports, automatic migration or production compatibility is promised.

Payload enums cannot become index keys, even when a row selects a unit variant:

ⓘ
use ic_db::{entity, enum_};
#[enum_(variant(name="Empty"), variant(name="Data", value(item(prim="Nat8"))))]
struct State {}
#[entity(pk(field="id"), index(field="state"), fields(
    field(name="id", value(item(prim="Nat64"))),
    field(name="state", value(opt, item(is="State")))
))]
struct Row {}

Payload enums also lack the generated ordering required by sets/maps:

ⓘ
use ic_db::{enum_, set};
#[enum_(variant(name="Empty"), variant(name="Data", value(item(prim="Nat8"))))]
struct State {}
#[set(item(is="State"), max_items=3)]
struct States {}

Modules§

design
Schema authoring for application design modules.

Structs§

Account
A Principal owner and optional subaccount.
Aggregate
A completed aggregate and its execution costs. No partial result or cursor.
AggregateJobs
Durable bounded aggregates in a host-governed allocation. Holds at most 16 jobs, each at most 16 KiB encoded bytes. Creation requires a fresh nonzero incarnation. Handles identify jobs; they do not authorize access. All mutation must run synchronously within one IC message, without awaits. Supplier failures trap; a later message trap rolls these changes back too.
Batch
A bounded synchronous batch; preparation is internal to Database::commit.
CopyStep
A bounded copy result. Completion means all source rows were copied, not that the target is validated for publication or available for ordinary access.
Database
Admitted database owning the supplier’s exclusive collection lease.
Date
A Gregorian calendar date, stored as days since the Unix epoch.
Decimal
Exact base-ten value with a signed 128-bit mantissa and scale 0–28. Construction removes fractional trailing zeros; all zero values share one representation. No floating-point conversion or implicit rounding is used.
Duration
Nonnegative millisecond duration. Constructors from larger units and arithmetic operators saturate; text parsing refuses overflow. No clock or timer is owned.
EntitySchema
Compiled entity metadata emitted by the entity macro.
FieldSchema
One named stored field; type, bounds, optionality and write policy define identity.
Float32
Finite canonical f32. Construction normalizes negative zero; NaN and infinities refuse.
Float64
Finite canonical f64. Construction normalizes negative zero; NaN and infinities refuse.
GroupCount
One complete group. Absent optional key values belong to a group too.
GroupCursor
Logical position in one completed retained job, not an authorization token. Positions are revalidated against the selected result; caller edits can skip rows intentionally but cannot change the result or advance input progress.
GroupPage
One page of completed retained groups. Keep next when mapping rows.
GroupValue
One complete group’s aggregate value, preserving all-absent groups.
IndexSchema
A compiled index over supported exact scalar components.
JobHandle
Opaque retained-job identity. The host must check caller authorization separately.
JobStep
Saved progress. Older sequences do not rescan; revision and expiry checks still apply.
Maintenance
Exclusive handle to a durably frozen source, before any target allocation/copy. Dropping this handle leaves maintenance active. Ordinary reads/writes remain closed. Host adapters own authorization and endpoint exposure.
Page
A page with explicit progress; a full page may require an empty final call.
ParseDecimalError
Invalid syntax or a value outside Decimal’s exact coefficient/scale domain.
Principal
An opaque IC identity containing at most 29 significant bytes.
Query
Fluent exact predicates over one entity. No callback executor is generated. Ordering uses primary order, an explicit index, a proven automatic path or bounded complete sorting. Work exhaustion never returns a sorted prefix.
QueryCursor
A bounded logical position, bound to database, schema, query and direction. It is not an authorization token or a snapshot. Callers may choose positions; the database revalidates all claims and retains no trusted progress counters.
QueryPage
A bounded page. Empty rows do not mean completion when next is present. Ordinary queries are live; maintenance source pages read frozen input.
ReferenceSchema
A required or optional typed reference using an ordinary reverse-lookup index. An absent optional value has no target; zero remains an ordinary target key.
RetiredSource
Exclusive cleanup authority for an entire source collection retired by cutover. Admission binds the exact transition and both database incarnations. Cleanup never opens the target and never clears the source’s retired manifest.
Schema
Validated executable schema. It is never reconstructed from stored data. Clones retain only immutable executable metadata; each database open still validates the current durable manifest independently. Revision reads and writes validate the affected counters when used, without caching them.
SchemaCopy
Exclusive source/target custody for a key-preserving whole-database transformation. Both allocations remain closed to ordinary access. Dropping preserves progress. Publication requires completed validation. Allocation reuse remains unsupported.
SchemaTransition
Identity of one explicitly supported source-to-target transformation. Changing code behavior requires a new version, even when both schemas match. This descriptor does not execute a transformation or authorize target publication.
Timestamp
Signed Unix-millisecond timestamp, including instants before 1970. Sub-millisecond conversions floor; arithmetic operators saturate only after the complete wide operation. This value never reads the clock.
TypeLink
Compiler-resolved link. Names carry identity; the function breaks constant cycles.
TypeSchema
Named schema; its links are shallow so recursive graphs never expand on comparison.
U256
Exact unsigned 256-bit integer. IC DB owns its durable and index encodings. A 256-bit unsigned integer type.
Ulid
A 128-bit ULID with exact 16-byte storage and canonical uppercase text.
UlidGenerator
Monotonic ULIDs for one explicitly owned issuance stream.
UlidParseError
Text was not an exact canonical uppercase 26-character ULID.
ValueSchema
Payload shape, shared with the field type/optionality rules.
VariantSchema
One unit or payload variant.

Enums§

Comparison
Exact comparison. Equality distinguishes absent values; ranges and pattern matches require presence.
Error
Failure before commit begins, or a refusal to admit stored data.
FieldType
Stored value semantics supported by this increment.
GroupOrder
Completed-group ordering. Aggregate ties always use ascending canonical keys.
IndexValue
One exact ordered scalar operand for index prefixes and fluent comparisons. Operand types must match declared fields; integers are never implicitly widened, narrowed or coerced across signedness. This is a bounded scalar boundary, not a general expression/value representation.
JobOutcome
Only Complete contains a result. Running never exposes a prefix as an exact total.
LiteralDefault
A compiled literal used only when an insert input omits its field. These are schema constants, not a dynamic query or mutation value model.
ManagedTimestamp
Database-owned timestamp assignment during bounded write preparation.
SortDirection
Direction of one field in an explicit result order.
TimeParseError
Invalid or out-of-range human-readable time input.
TypeBody
A compiled named type; record/enum members use canonical name order.
UlidGenerationError
A refused issuance; the generator’s previous state remains unchanged.

Constants§

MAX_INDEX_KEY_BYTES
Maximum complete encoded secondary-index key, including namespace and owner suffix.

Traits§

Entity
Codec boundary emitted by #[entity]; hand-written implementations are unsupported. Typed references use Rust resolution; an unresolved name fails compilation:
InsertInput
Typed insert construction with omission distinct from explicit optional absence. Generated inputs implement this once per entity; execution stays in Batch. Managed fields have no input setters:
PrimaryKey
Supported supplied primary key: integers, U256, Ulid, Principal, Account or Subaccount. This sealed boundary keeps lookup/delete/page arguments typed to their entity.
Value
Codec boundary generated by named-type macros; handwritten implementations are unsupported.

Type Aliases§

Blob
Owned binary bytes. The database codec enforces authored limits and row bounds.
Subaccount
Opaque application-owned subaccount bytes.

Attribute Macros§

entity
Author a typed record with named fields, a supplied scalar key and indexes.
enum_
Declare a named enum using an empty struct and variant(name = "...") attributes. Supports 1–64 unit or typed payload variants. Canonical name order determines stored ordinals; source declaration order does not. Use item(indirect, is = “Self”) for boxed recursion, with a finite base alternative. All-unit enums also convert by reference into ic_db::IndexValue, using the same canonical order. Any payload variant excludes the whole enum from indexes.
list
Declare a reusable ordered list with an item type and a shared maximum length.
map
Declare a named BTreeMap wrapper using key(...), value(...) and max_items = N (0..256). Keys are primitives, scalar newtypes or unit enums. Values use the ordinary optional/list/named field rules; stored duplicate keys refuse.
newtype
Declare a distinct Rust and schema type around one primitive, including its bounds.
record
Declare a named stored record using attribute-owned fields and an empty struct.
set
Declare a bounded ordered set with item(...) and max_items = N (0..256). Elements can be primitives, scalar newtypes or unit enums. The generated wrapper contains a BTreeSet<T>. Decoding requires strictly increasing keys.