DatabaseOptions

public struct DatabaseOptions : Sendable

Configuration shared by every collection opened from a single NyaruDB instance.

DatabaseOptions controls compression, encryption, serialization format, file protection, and the fragmentation threshold that drives compaction hints. These options are applied to all collections within the database and are persisted in each collection’s manifest at creation time.

Changing options after collections exist has no effect on existing collections — the manifest is frozen at creation. Only encryptionKey is omitted from the manifest (it is provided at open time) so the key can be rotated or supplied from the Keychain without touching on-disk data.

  • The compression method applied to record payloads in every shard file.

    Default: .none. Consider .gzip for portable compression that works on all platforms.

    Declaration

    Swift

    public var compression: CompressionMethod

  • The iOS file protection level applied to every shard file (no-op on non-Apple platforms).

    Default: .none. Set to .completeUnlessOpen for data-in-rest protection on iOS devices.

    Declaration

    Swift

    public var fileProtection: FileProtection

  • The serialization format used for encoding and decoding documents.

    Default: .json. Set to .msgpack for more compact storage.

    Declaration

    Swift

    public var format: SerializationFormat

  • An optional AES-256-GCM symmetric key. When set, all shard payloads and collection manifests are encrypted before being written to disk and decrypted on read.

    Default: nil (no encryption).

    Important

    The encryption key itself is never persisted. It must be provided every time the database is opened. Store the key in the system Keychain and use NyaruCrypto.generateRandomKey() to create it.

    Declaration

    Swift

    public var encryptionKey: SymmetricKey?

  • The ratio of tombstoned records to total records above which needsCompaction() returns true for a collection.

    Default: 0.2 (20%).

    Declaration

    Swift

    public var maxFragmentation: Double

  • Creates database options with sensible defaults.

    Declaration

    Swift

    public init(
  compression: CompressionMethod = .none,
  fileProtection: FileProtection = .none,
  format: SerializationFormat = .json,
  encryptionKey: SymmetricKey? = nil,
  maxFragmentation: Double = 0.2
)

    Parameters

    compression

    Payload compression for all collections.
    fileProtection

    iOS file protection for shard files.
    format

    Document serialization format (.json or .msgpack).
    encryptionKey

    Optional AES-256-GCM key for encrypting data at rest.
    maxFragmentation

    Tombstone ratio that triggers compaction hints.