Store

public class Store : CustomDebugStringConvertible

The Store represents an ObjectBox database on the local disk. For each persisted object type, you can obtain a Box instance with the box(for:) method. Boxes provide the interfaces for object persistence.

A typical setup sequence looks like this:

let store = try Store(directoryPath: pathToStoreData)
let personBox = store.box(for: Person.self)
let persons = try personBox.all()

Note

You must run the code generator by building at least once to create a Store initializer according to your data model. This generated initializer does not have a “model” parameter (that one is an internal initializer), and comes with convenient defaults for its named parameters.

  • The path to the directory containing our database files as it was passed to this instance when creating it.

    Declaration

    Swift

    internal(set) public var directoryPath: String { get }

  • Returns the version of ObjectBox Swift.

    Declaration

    Swift

    public static var version: String

  • Pass this together with a String identifier as the directory path to use a file-less in-memory database.

    Declaration

    Swift

    public static let inMemoryPrefix: String

  • Returns the versions of ObjectBox Swift, the ObjectBox lib, and ObjectBox core.

    Declaration

    Swift

    public static var versionAll: String { get }

  • Returns the product name (“ObjectBox Swift”) along with all versions (see versionAll()).

    Declaration

    Swift

    public static var versionFullInfo: String { get }

  • Returns the version of ObjectBox lib (C API).

    Declaration

    Swift

    public static var versionLib: String { get }

  • Returns the version of ObjectBox core (“internal” version).

    Declaration

    Swift

    public static var versionCore: String { get }

  • Attaches to a previously opened Store given its directory.

    Declaration

    Swift

    public static func attachTo(directory: String) throws -> Store

  • Returns if an open store (i.e. opened before and not yet closed) was found for the given directory.

    Declaration

    Swift

    public static func isOpen(directory: String) throws -> Bool

  • Creates a store using the given model definition. In most cases, you would want to use the initializer without the model argument created by the code generator instead.

    In-memory database

    To use a file-less in-memory database, instead of a directory path pass memory: together with an identifier string:

    let inMemoryStore = try Store(directoryPath: "memory:test-db")

    Important

    This initializer should only be used internally. Instead, use the generated initializer without the model parameter (trigger code generation if you don’t see it yet).

    Declaration

    Swift

    public init(model: OpaquePointer, directory: String = "objectbox", maxDbSizeInKByte: UInt64 = 1024 * 1024,
            fileMode: UInt32 = 0o644, maxReaders: UInt32 = 0, readOnly: Bool = false) throws

    Parameters

    model

    A model description generated using a ModelBuilder.
    directoryPath

    The directory path in which ObjectBox places its database files for this store, or to use an in-memory database memory:<identifier>.
    maxDbSizeInKByte

    Limit of on-disk space for the database files. Default is 1024 * 1024 (1 GiB).
    fileMode

    UNIX-style bit mask used for the database files; default is 0o644. Note: directories become searchable if the “read” or “write” permission is set (e.g. 0640 becomes 0750).
    maxReaders

    The maximum number of readers. “Readers” are a finite resource for which we need to define a maximum number upfront. The default value is enough for most apps and usually you can ignore it completely. However, if you get the maxReadersExceeded error, you should verify your threading. For each thread, ObjectBox uses multiple readers. Their number (per thread) depends on number of types, relations, and usage patterns. Thus, if you are working with many threads (e.g. in a server-like scenario), it can make sense to increase the maximum number of readers. Note: The internal default is currently around 120. So when hitting this limit, try values around 200-500.
    readOnly

    Opens the database in read-only mode, i.e. not allowing write transactions.

  • Clone a previously opened store; while a store instance is usable from multiple threads, situations may exist in which cloning a store simplifies the overall lifecycle. E.g. when a store is used for multiple threads and it may only be fully released once the last thread completes. The returned store is a new instance with its own lifetime.

    Declaration

    Swift

    public func clone() throws -> Store

  • Return a box for reading/writing entities of the given class from/to the database. Obtain a a Box for the given type.

    Declaration

    Swift

    public func box<T>(for entityType: T.Type = T.self) -> Box<T> where T : EntityInspectable, T : __EntityRelatable, T == T.EntityBindingType.EntityType

    Parameters

    entityType

    Object type to get a box for.

    Return Value

    Box for the given type.

  • Delete the database files on disk, including the database directory.

    This Store object will not be usable after calling this.

    For an in-memory database, this will just clean up the in-memory database.

    Declaration

    Swift

    public func closeAndDeleteAllFiles() throws

  • The SyncClient associated with this store. To create one, please check the Sync class and its makeClient().

    Declaration

    Swift

    internal(set) public var syncClient: SyncClient? { get }

Explicit Transactions

  • Runs the given block inside a read/write transaction.

    You can e.g. wrap multiple put calls into a single write transaction to ensure a “all or nothing” semantic. Also, this is more efficient and provides better performance than having one transactions for each operation.

    You can nest read-only transaction into read/write transactions, but not vice versa.

    Throws

    rethrows errors thrown inside, plus any ObjectBoxError that makes sense.

    Declaration

    Swift

    public func runInTransaction<T>(_ block: () throws -> T) throws -> T

    Parameters

    block

    Code that needs to run in a read/write transaction.

    Return Value

    The forwarded result of block.

  • Runs the given block inside a read(-only) transaction.

    You can e.g. wrap multiple get calls into a single read transaction to have a single consistent view on data. Also, this is more efficient and provides better performance than having one transactions for each operation.

    You can nest read-only transaction into read/write transactions, but not vice versa.

    Throws

    rethrows errors thrown inside, plus any ObjectBoxError that makes sense.

    Declaration

    Swift

    public func runInReadOnlyTransaction<T>(_ block: () throws -> T) throws -> T

    Parameters

    block

    Code that needs to run in a read or read/write transaction.

    Return Value

    The forwarded result of block.

Async helpers

  • Wait until anything that’s been submitted so far for asynchronous execution on any AsyncBox in this store has been processed.

    Declaration

    Swift

    @discardableResult
public func awaitAsyncSubmitted() -> Bool

  • Wait for the async queue used by all AsyncBoxes in this store to become idle because nothing has been queued up for a while.

    Declaration

    Swift

    @discardableResult
public func awaitAsyncCompleted() -> Bool

Generated initializer

  • A store with a fully configured model. Created by the code generator with your model’s metadata in place.

    In-memory database

    To use a file-less in-memory database, instead of a directory path pass memory: together with an identifier string:

    let inMemoryStore = try Store(directoryPath: "memory:test-db")

    Important

    This initializer is created by the code generator. If you only see the internal init(model:...) initializer, trigger code generation by building your project.

    Declaration

    Swift

    public convenience init(directoryPath: String, maxDbSizeInKByte: UInt64 = 1024 * 1024,
                        fileMode: UInt32 = 0o644, maxReaders: UInt32 = 0, readOnly: Bool = false) throws

    Parameters

    directoryPath

    The directory path in which ObjectBox places its database files for this store, or to use an in-memory database memory:<identifier>.
    maxDbSizeInKByte

    Limit of on-disk space for the database files. Default is 1024 * 1024 (1 GiB).
    fileMode

    UNIX-style bit mask used for the database files; default is 0o644. Note: directories become searchable if the “read” or “write” permission is set (e.g. 0640 becomes 0750).
    maxReaders

    The maximum number of readers. “Readers” are a finite resource for which we need to define a maximum number upfront. The default value is enough for most apps and usually you can ignore it completely. However, if you get the maxReadersExceeded error, you should verify your threading. For each thread, ObjectBox uses multiple readers. Their number (per thread) depends on number of types, relations, and usage patterns. Thus, if you are working with many threads (e.g. in a server-like scenario), it can make sense to increase the maximum number of readers. Note: The internal default is currently around 120. So when hitting this limit, try values around 200-500.
    readOnly

    Opens the database in read-only mode, i.e. not allowing write transactions.