Communication and storageLocal storage and replication

Local storage and replication

Separate durable local commits, peer synchronization, and remote visibility.

Save and read your own data while offline. A local commit completes independently of replication. Remote availability requires authority, compatible schemas, registered scopes, storage, and a permitted peer path.

Choose a backend

BackendLifetimeUse
MemoryCurrent sessionDisposable examples and isolated tests
SQLiteDatabase on the native hostPersistent local applications
PostgreSQLConfigured database serviceNative service deployments with an available database
Browser memoryCurrent browser runtimeBrowser-local state without a durable adapter

Provide the database location and encryption material through the selected target's storage configuration. A key is not optional merely because the peer has a signing identity. Preserve both the database and its key under your backup policy.

Opening local storage runs the selected migration set. Local readiness does not wait for remote peer connection. PostgreSQL availability is a backend requirement, not evidence that another Atlas peer is online.

Understand the commit boundary

records.save(record, scope) validates and commits application state locally. SaveResult.local_commit reports that boundary. SaveResult.entity_ref is the stable reference you can put in an event.

Peer synchronization then exchanges authorized operations for the selected replication scope. It can proceed directly between peers. An application's always-on peer can retain data for later readers, but its presence is not a requirement for every exchange.

These outcomes complete independently:

  • The local save succeeds while no peer is connected.
  • An event reaches a reader before its record arrives.
  • A record replicates even when a live stream is unavailable.
  • One authorized peer synchronizes while another remains offline.

Register scopes and observe progress

A ReplicationScope identifies the application's exchange boundary. Register only the scopes that the current session needs. Registration expresses interest, not permission. A matching topic, scope, or discovered address never bypasses receive-path authorization.

Managed sync reports local status and lifecycle events. Network-not-ready state keeps the application locally usable. When the selected binding requires a registration retry after readiness, retry that registration after observing readiness. Do not hold startup open in a connection loop.

A completed pull describes the attempted peer and scope. It does not certify every possible peer's state. Preserve cursors and operation identities so retry and reconnect do not duplicate materialized effects.

Resolve references that arrive early

records.resolve(entity_ref, ResolveOptions) reads local state or uses permitted paths within the supplied deadline. Inspect structured PendingState separately from definitive NotFound. A valid event reference can arrive before its record.

Display the event's permitted bounded observation while a separate task resolves saved context. Do not fabricate a record to conceal pending synchronization.

Recovery and retention

Back up persistent data and keys using a backend-consistent procedure. Keep schema definitions, operation history, and migration metadata needed for recovery. A materialized view alone may not preserve replication history.

Disk exhaustion or an unreadable encryption key produces StorageFailure. Keep the app's unsaved input separate from committed state. Do not report a durable save after a storage failure. Live events and samples are not automatic backups of the database.

See offline behavior for reconnect and compatibility for additive migrations and unknown operations.