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.
- Aggregate
Jobs - 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. - Copy
Step - 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.
- Entity
Schema - Compiled entity metadata emitted by the entity macro.
- Field
Schema - 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. - Group
Count - One complete group. Absent optional key values belong to a group too.
- Group
Cursor - 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.
- Group
Page - One page of completed retained groups. Keep
nextwhen mappingrows. - Group
Value - One complete group’s aggregate value, preserving all-absent groups.
- Index
Schema - 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.
- Parse
Decimal Error - 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.
- Query
Cursor - 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.
- Query
Page - A bounded page. Empty rows do not mean completion when
nextis present. Ordinary queries are live; maintenance source pages read frozen input. - Reference
Schema - 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.
- Retired
Source - 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.
- Schema
Copy - 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.
- Schema
Transition - 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.
- Type
Link - Compiler-resolved link. Names carry identity; the function breaks constant cycles.
- Type
Schema - 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.
- Ulid
Generator - Monotonic ULIDs for one explicitly owned issuance stream.
- Ulid
Parse Error - Text was not an exact canonical uppercase 26-character ULID.
- Value
Schema - Payload shape, shared with the field type/optionality rules.
- Variant
Schema - 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.
- Field
Type - Stored value semantics supported by this increment.
- Group
Order - Completed-group ordering. Aggregate ties always use ascending canonical keys.
- Index
Value - 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.
- Literal
Default - A compiled literal used only when an insert input omits its field. These are schema constants, not a dynamic query or mutation value model.
- Managed
Timestamp - Database-owned timestamp assignment during bounded write preparation.
- Query
Operand - A literal, row field or length threshold in a fluent predicate.
- Sort
Direction - Direction of one field in an explicit result order.
- Time
Parse Error - Invalid or out-of-range human-readable time input.
- Type
Body - A compiled named type; record/enum members use canonical name order.
- Ulid
Generation Error - 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: - Insert
Input - 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: - Primary
Key - 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 intoic_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
BTreeMapwrapper usingkey(...),value(...)andmax_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(...)andmax_items = N(0..256). Elements can be primitives, scalar newtypes or unit enums. The generated wrapper contains aBTreeSet<T>. Decoding requires strictly increasing keys.