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.
  • Returns the version number of ObjectBox C API the framework was built against.

    Declaration

    Swift

    public static var version: String { get }
  • The path that was passed to this instance when creating it.

    Declaration

    Swift

    internal(set) public var directoryPath: String
  • A store with a fully configured model. Created by the code generator with your model’s metadata in place.

    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 = 0o755,
                            maxReaders: UInt32 = 0) throws

    Parameters

    directoryPath

    The path to the directory in which ObjectBox should store database files.

    maxDbSizeInKByte

    Maximum size the database may take up on disk (default: 1 GiB).

    fileMode

    The unix permissions (like 0o755) to use for creating the database files.

    maxReaders

    readers are a finite resource for which you need to define a maximum 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. server-like scenario), it can make sense to increase the maximum number of readers. The default value 0 (zero) lets ObjectBox choose an internal default (currently around 120). So if you hit this limit, try values around 200-500.

  • Important

    this initializer is only used internally. Instead of this, 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 = 0o755, maxReaders: UInt32 = 0) throws

    Parameters

    model

    A model description generated using a ModelBuilder

    directory

    The path to the directory in which ObjectBox should store database files.

    maxDbSizeInKByte

    Maximum size the database may take up on disk (default: 1 GB).

    fileMode

    The unix permissions (like 0o755) to use for creating the database files.

    maxReaders

    readers are a finite resource for which you need to define a maximum 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. server-like scenario), it can make sense to increase the maximum number of readers. The default value 0 (zero) lets ObjectBox choose an internal default (currently around 120). So if you hit this limit, try values around 200-500.

  • 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. This Store object will not be usable after calling this.

    Declaration

    Swift

    public func closeAndDeleteAllFiles() throws
  • 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
  • Runs the given block inside a read/write transaction.

    Takes care of flattening nested transaction calls into a single transaction, and rolling back changes for you on error. You can e.g. wrap multiple put calls into a single write transaction to increase performance by re-using the resources of a single transaction to read and write data.

    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.

    Takes care of flattening nested transaction calls into a single transaction, and rolling back changes for you on error. You can e.g. wrap multiple get calls into a single read transaction to increase performance by re-using the resources for reading data into memory.

    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.