Configuration

@frozen
public struct Configuration : Sendable
extension Realm.Configuration: CustomStringConvertible
extension Realm.Configuration: Equatable

A Configuration instance describes the different options used to create an instance of a Realm.

Configuration instances are just plain Swift structs. Unlike Realms and Objects, they can be freely shared between threads as long as you do not mutate them.

Creating configuration values for class subsets (by setting the objectClasses property) can be expensive. Because of this, you will normally want to cache and reuse a single configuration value for each distinct configuration rather than creating a new value each time you open a Realm.

Show on GitHub

Default Configuration

  • The default Configuration used to create Realms when no configuration is explicitly specified (i.e. Realm())

    Declaration

    Swift

    public static var defaultConfiguration: Configuration { get set }
    Show on GitHub

Initialization

  • Creates a Configuration which can be used to create new Realm instances.

    Note

    The fileURL, inMemoryIdentifier, and syncConfiguration parameters are mutually exclusive. Only set one of them, or none if you wish to use the default file URL.

    Declaration

    Swift

    @preconcurrency
public init(fileURL: URL? = URL(fileURLWithPath: RLMRealmPathForFile("default.realm"), isDirectory: false),
            inMemoryIdentifier: String? = nil,
            syncConfiguration: SyncConfiguration? = nil,
            encryptionKey: Data? = nil,
            readOnly: Bool = false,
            schemaVersion: UInt64 = 0,
            migrationBlock: MigrationBlock? = nil,
            deleteRealmIfMigrationNeeded: Bool = false,
            shouldCompactOnLaunch: (@Sendable (Int, Int) -> Bool)? = nil,
            objectTypes: [ObjectBase.Type]? = nil,
            seedFilePath: URL? = nil)

    Parameters

    fileURL

    The local URL to the Realm file.
    inMemoryIdentifier

    A string used to identify a particular in-memory Realm.
    syncConfiguration

    For Realms intended to sync with Atlas App Services, a sync configuration.
    encryptionKey

    An optional 64-byte key to use to encrypt the data.
    readOnly

    Whether the Realm is read-only (must be true for read-only files).
    schemaVersion

    The current schema version.
    migrationBlock

    The block which migrates the Realm to the current version.
    deleteRealmIfMigrationNeeded

    If true, recreate the Realm file with the provided schema if a migration is required.
    shouldCompactOnLaunch

    A block called when opening a Realm for the first time during the life of a process to determine if it should be compacted before being returned to the user. It is passed the total file size (data + free space) and the total bytes used by data in the file.

                               Return `true ` to indicate that an attempt to compact the file should be made.
                           The compaction will be skipped if another process is accessing it.
    objectTypes

    The subset of Object and EmbeddedObject subclasses persisted in the Realm.
    seedFilePath

    The path to the realm file that will be copied to the fileURL when opened for the first time.
    Show on GitHub

Configuration Properties

  • A configuration value used to configure a Realm for synchronization with Atlas App Services. Mutually exclusive with inMemoryIdentifier.

    Declaration

    Swift

    public var syncConfiguration: SyncConfiguration? { get set }
    Show on GitHub

  • The local URL of the Realm file. Mutually exclusive with inMemoryIdentifier.

    Declaration

    Swift

    public var fileURL: URL? { get set }
    Show on GitHub

  • A string used to identify a particular in-memory Realm. Mutually exclusive with fileURL and syncConfiguration.

    Declaration

    Swift

    public var inMemoryIdentifier: String? { get set }
    Show on GitHub

  • A 64-byte key to use to encrypt the data, or nil if encryption is not enabled.

    Declaration

    Swift

    public var encryptionKey: Data?
    Show on GitHub

  • Whether to open the Realm in read-only mode.

    For non-synchronized Realms, this is required to be able to open Realm files which are not writeable or are in a directory which is not writeable. This should only be used on files which will not be modified by anyone while they are open, and not just to get a read-only view of a file which may be written to by another thread or process. Opening in read-only mode requires disabling Realm’s reader/writer coordination, so committing a write transaction from another process will result in crashes.

    Synchronized Realms must always be writeable (as otherwise no synchronization could happen), and this instead merely disallows performing write transactions on the Realm. In addition, it will skip some automatic writes made to the Realm, such as to initialize the Realm’s schema. Setting readOnly = YES is not strictly required for Realms which the sync user does not have write access to, but is highly recommended as it will improve error reporting and catch some errors earlier.

    Realms using query-based sync cannot be opened in read-only mode.

    Declaration

    Swift

    public var readOnly: Bool
    Show on GitHub

  • The current schema version.

    Declaration

    Swift

    public var schemaVersion: UInt64
    Show on GitHub

  • The block which migrates the Realm to the current version.

    Declaration

    Swift

    @preconcurrency
public var migrationBlock: MigrationBlock?
    Show on GitHub

  • Whether to recreate the Realm file with the provided schema if a migration is required. This is the case when the stored schema differs from the provided schema or the stored schema version differs from the version on this configuration. Setting this property to true deletes the file if a migration would otherwise be required or executed.

    Note

    Setting this property to true doesn’t disable file format migrations.

    Declaration

    Swift

    public var deleteRealmIfMigrationNeeded: Bool { get set }
    Show on GitHub

  • A block called when opening a Realm for the first time during the life of a process to determine if it should be compacted before being returned to the user. It is passed the total file size (data + free space) and the total bytes used by data in the file.

    Return true to indicate that an attempt to compact the file should be made. The compaction will be skipped if another process is accessing it.

    Declaration

    Swift

    @preconcurrency
public var shouldCompactOnLaunch: (@Sendable (Int, Int) -> Bool)?
    Show on GitHub

  • The classes managed by the Realm.

    Declaration

    Swift

    public var objectTypes: [ObjectBase.Type]? { get set }
    Show on GitHub

  • The maximum number of live versions in the Realm file before an exception will be thrown when attempting to start a write transaction.

    Realm provides MVCC snapshot isolation, meaning that writes on one thread do not overwrite data being read on another thread, and instead write a new copy of that data. When a Realm refreshes it updates to the latest version of the data and releases the old versions, allowing them to be overwritten by subsequent write transactions.

    Under normal circumstances this is not a problem, but if the number of active versions grow too large, it will have a negative effect on the filesize on disk. This can happen when performing writes on many different threads at once, when holding on to frozen objects for an extended time, or when performing long operations on background threads which do not allow the Realm to refresh.

    Setting this property to a non-zero value makes it so that exceeding the set number of versions will instead throw an exception. This can be used with a low value during development to help identify places that may be problematic, or in production use to cause the app to crash rather than produce a Realm file which is too large to be opened.

    Declaration

    Swift

    public var maximumNumberOfActiveVersions: UInt?
    Show on GitHub

  • When opening the Realm for the first time, instead of creating an empty file, the Realm file will be copied from the provided seed file path and used instead. This can be used to open a Realm file with pre-populated data.

    If a realm file already exists at the configurations’s destination path, the seed file will not be copied and the already existing realm will be opened instead.

    Note that to use this parameter with a synced Realm configuration the seed Realm must be appropriately copied to a destination with Realm.writeCopy(configuration:) first.

    This option is mutually exclusive with inMemoryIdentifier. Setting a seedFilePath will nil out the inMemoryIdentifier.

    Declaration

    Swift

    public var seedFilePath: URL?
    Show on GitHub

  • Configuration for Realm event recording. Events are enabled if this is set to a non-nil value.

    Declaration

    Swift

    public var eventConfiguration: EventConfiguration?
    Show on GitHub

CustomStringConvertible

  • A human-readable description of the configuration value.

    Declaration

    Swift

    public var description: String { get }
    Show on GitHub

Equatable