Skip to content

Maryk FoundationDB Store

Distributed transactional storage for Maryk models, queries, history and live updates. The store uses FoundationDB’s ordered keyspace and native transactions. It supports JVM and desktop Native targets where libfdb_c is available.

Install a compatible FoundationDB client and connect to a running cluster. The current source targets client 7.3.81, API version 730, and Kotlin multiplatform binding 7.3.81.1. See local setup for the managed development cluster.

Define a model and open a store with stable model IDs and a directory path:

import maryk.core.models.RootDataModel
import maryk.core.properties.definitions.string
import maryk.core.query.requests.add
import maryk.datastore.foundationdb.FoundationDBDataStore
object Note : RootDataModel<Note>() {
val message by string(index = 1u)
}
suspend fun main() {
val store = FoundationDBDataStore.open(
fdbClusterFilePath = "./fdb.cluster",
directoryPath = listOf("maryk", "notes"),
dataModelsById = mapOf(1u to Note),
)
try {
val response = store.execute(Note.add(Note.create { message with "Hello Maryk" }))
println(response.statuses)
} finally {
store.close()
}
}

Omit fdbClusterFilePath to use FoundationDB’s default cluster-file lookup. Native hosts also own process-wide client shutdown. Use matching Maryk module versions when consuming published artifacts.

  • Ordinary multi-object writes commit each record independently and can partially succeed. Use an explicit transaction or atomic request for one commit across records or models.
  • Reads use a consistent native snapshot with a short lifetime. Smaller pages and projections help stay within snapshot and read-byte limits. See read limits and paging.
  • History queries require keepAllVersions; newest-first update-history pages also require keepUpdateHistoryIndex and a ready history index. Hard deletion permanently erases the record’s current and historic values.
  • executeFlow receives local-process updates by default. Cross-process updates require the optional cluster update log.
  • A timeout or cancellation during commit does not prove rollback. Retain a stable transaction ID and handle when commit resolution is required. Ordinary retry markers protect retries within one invocation.
TaskGuide
Configure transaction policies, memory, read limits, bulk import or encryptionConfiguration and limits
Upgrade storage or model definitions; resume migrationsMigrations and storage-format upgrades
Propagate live updates across processesCluster-wide live updates
Back up or recover a clusterNative backup and recovery
Transfer current state or retained history between backendsPortable backups
Understand the engineArchitecture and storage layout
Run local tests or develop the bindingLocal testing

Opening an existing store can run storage-format and schema migrations. Stop old writers and retain a recoverable copy before upgrading. For a directory tree copied into a separately configured directory layer, pass that same directoryLayer to open, readStoredModelDefinitionsFromDirectory and detectStoredKeepAllVersions. Opening a store does not perform the offline copy.

For optional SQL queries, follow the SQL guide. Expose a store to remote clients through the Remote Store.

Maryk is licensed under the Apache 2.0 License. See the repository’s LICENSE file for details.