Repository navigation
Maryk brings data modeling, querying, storage, and synchronization together around one strongly typed Kotlin Multiplatform model. Version 0.14 focuses on making that foundation faster in everyday use and more dependable as data grows, models evolve, and stores need to be recovered or moved.
This release improves performance across all five datastores, from point reads and batches to projections and historical queries. It also adds portable state backups for moving current data between compatible backends, incremental RocksDB backups for complete physical recovery points, and stronger safeguards for data integrity, serialization, and history restoration.
The redesigned maryk.io brings these capabilities together with clearer documentation, practical tutorials, and focused guides for configuring, migrating, and operating a store.
Upgrading from 0.13? This release includes persistent storage conversion and transport compatibility changes. Review the upgrade notes below and the storage upgrade guide before opening existing stores or updating Remote deployments.
Performance improvements
Faster reads and less repeated work benefit applications across Memory, RocksDB, FoundationDB, IndexedDB, and Remote stores. The measurements below illustrate the gains for specific workloads.
Measured against 0.13.0
A benchmark sweep covered 336 accepted JVM runs, 12 browser profiles, and 798 scenario groups. Representative improvements from the measured 0.14 development snapshot were:
| Store | Full point-read speedup | Full 32-key batch speedup |
|---|---|---|
| Memory | 1.76× | 1.41× |
| RocksDB | 1.08× | 1.45× |
| FoundationDB | 2.75× | 2.12× |
| Remote | 1.60× | 1.50× |
| IndexedDB | 9.46× | 3.26× |
Other measured gains include:
- FoundationDB projected timelines: 13.33 ms → 2.09 ms, approximately 6.38× faster.
- RocksDB repeated-key batches: approximately 3.17× faster.
- IndexedDB projected point reads: approximately 10.75× faster.
- IndexedDB large-record projections: approximately 4.61× faster in the measured 257-record fixture.
These are workload-specific latency comparisons from a development snapshot, using three independent runs per comparison. Measurements used an Apple M5 MacBook Pro, JVM stores on Java 21, and IndexedDB in Chrome. FoundationDB ran locally; Remote used loopback HTTP to a Memory backend.
Results vary by workload. Short dense FoundationDB full-record reads, some short query workloads, and Memory backup/first-use restore remained slower in the measured comparisons. These figures do not establish sustained concurrent throughput or final-release performance.
Changes across the request path
This release reduces repeated decoding, copying, index work, and temporary allocations throughout the request path.
- Memory: more efficient reads, value ownership, and historical reconstruction.
- RocksDB: faster projected and repeated-key reads, reused snapshot-bound read options, and less redundant index and decryption work.
- FoundationDB: overlapping bounded reads, prepared projections and filters, and reduced work during transaction retries.
- IndexedDB: narrower snapshots, batched reads, and safe snapshot reuse under schema and journal checks.
- Remote: bounded response streaming and reusable JVM HTTP connections.
- Core: lower serialization and value-copy overhead, including ProtoBuf and UTF-8 processing.
Backups and recovery
Portable state backups across stores
New state backup and restore APIs let you export current records and move them between compatible Maryk backends.
- Preserve record IDs, current values, creation and update versions, soft deletes, and incrementing-map allocation counters.
- Export through a consistent capture across registered models.
- Use a binary archive with checksums and completion verification.
- Restore in bounded, atomic batches into an empty target.
- Available across Memory, RocksDB, FoundationDB, IndexedDB, and compatible Remote Store deployments.
State backups work without retained history. Use history backups when earlier revisions must remain queryable after recovery.
Incremental RocksDB backups
The new RocksDBBackupRepository provides physical recovery points containing the complete store: records, indexes, Maryk metadata, and retained history.
- Repeated backups share unchanged SST files.
- Ordinary writes can continue during capture.
- Explicit retention controls let applications choose when to remove older recovery points.
- Exclusive repository ownership prevents conflicting processes from modifying the same backup repository.
- Restore verifies checksums and publishes into a new directory, with guards against incomplete recovery.
Physical backups work with or without keepAllVersions. Portable backups remain the option for transfers between different storage engines.
Stronger history restoration
History restore now replays complete source-version groups atomically, including changes spanning multiple models. Related changes from one source version remain together during recovery.
Remote Store negotiates and authorizes this capability explicitly. Restore also applies stricter payload validation and resource limits before replay.
Each version group is atomic; the complete archive is restored through multiple commits.
Data integrity and storage
A substantial part of 0.14 strengthens behavior across mutations, history, migrations, and live updates.
- Preserve empty-versus-absent collections, nested collection boundaries, and typed-value identity more consistently.
- Correct collection replacement, incrementing-map allocation, unique ownership, and deletion/restoration behavior.
- Prevent returned or historical values from sharing mutable state with later operations.
- Apply nested selections consistently through serialization and datastore updates.
- Improve live-query membership, multi-entry index handling, and lagged-snapshot behavior.
- Strengthen migration checkpoints, source-schema validation, and recovery after interrupted conversions.
- Preserve cancellation and normal listener completion during shutdown.
Updated persistent storage format
Storage format 2 corrects numeric ordering and affected index encodings, including floating-point values, variable-width boundaries, and collection descriptors.
Persistent stores created by 0.13.0 undergo a resumable opening conversion. The conversion preserves original record IDs and versions and publishes the new format marker only after verification.
Serialization and code generation
More interoperable ProtoBuf
Nanosecond-precision DateTime values now use a length-delimited seconds/nanoseconds message, allowing standard ProtoBuf readers to skip unknown fields correctly.
Known legacy scalar values remain readable. Legacy packed collections require explicit source-format context because their framing is ambiguous.
Further fixes improve repeated map entries, embedded message fragments, contextual collections, empty collection presence, and wire-type validation.
Stricter value handling
- Enforce numeric types, ranges, and scalar storage shapes.
- Preserve floating-point identity and rounding across platforms.
- Reject malformed Unicode and incomplete JSON or YAML structures.
- Correct YAML empty-array and nested-writer behavior.
Improved generated models
The generator now shares enum declarations across input schemas, discovers enum dependencies inside collections and maps, and rejects conflicting definitions. It also emits valid Kotlin for additional default values, including Long.MIN_VALUE and whole-hour timestamps.
SQL, tools, and operations
- SQL aggregates accumulate exactly before converting to their declared result types.
- Correlated expressions are checked against surrounding
GROUP BYrequirements, rejecting ambiguous grouped queries. - Desktop imports and SQL transaction recovery are better protected when windows close.
- RocksDB exposes additional diagnostics and checksum verification.
- RocksDB configuration separates read-cache, memtable, and retained-history budgets.
- Native comparator packaging and platform checks are expanded.
- Windows Native RocksDB recovery gains improved Unicode-path support.
SQL remains an optional layer over Maryk models and stores; the typed request API remains the primary application API.
A new home for Maryk
The redesigned maryk.io website provides a clearer path from defining a model to querying, synchronizing, and operating a store.
The documentation now includes:
- A refreshed homepage and visual design.
- Getting Started and a first-store tutorial.
- Practical guides for local-first applications, searchable catalogs, synchronization keys, and safe model changes.
- Focused configuration, migration, encryption, and recovery guides.
- A datastore performance guide with measurement context.
- Improved navigation, reference tables, and diagrams.
- Generated documentation exports for coding agents and other tools.
Upgrading from 0.13
Upgrade Maryk modules together. Use 0.14.0 consistently across dependencies, and upgrade Remote clients and servers together.
Prepare persistent stores before opening them. Keep a recoverable copy of the original store, schemas, and encryption keys. Complete pending model migrations with the original library, stop old writers, and allow time and space for conversion. Do not downgrade converted stores or run mixed old/new writers.
Review recovery requirements. Some legacy encodings do not contain enough information to reconstruct collection presence or allocation history. Conversion fails explicitly where authoritative source information is required.
Restart synchronization from a fresh snapshot. Existing scan cursors and replication checkpoints must be reviewed at the storage-format boundary.
Review transport compatibility. Upgrade both endpoints before exchanging the new nanosecond DateTime representation or relying on corrected collection encodings.
Create new portable backups after upgrading. Current portable backups use format 3; restore rejects earlier formats.
Review RocksDB memory settings. The default memtable budget increases from 32 MiB to 128 MiB. Read-cache, memtable, and retained-history budgets are separate and do not constitute a process-memory cap.
Maintenance
- Updated Kotlin to
2.4.21, Compose to1.12.2, and Ktor to3.6.1. - Updated RocksDB Multiplatform to
11.8.1.2and FoundationDB bindings to7.3.81.1. - Adopted stable Kotlin time and UUID APIs where applicable.
- Expanded integrity, recovery, browser, Android, and native-platform checks.
- Improved installer verification, dependency verification, and release workflows.