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 of ObjectBox Swift.

    Declaration

    Swift

    public static var version: 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 }
  • 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 }
  • 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 = 0o644, maxReaders: UInt32 = 0, readOnly: Bool = false) 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: 500 MB).

    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
  • 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 }
  • 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.

  • 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
  • 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, readOnly: Bool = false) throws

    Parameters

    directoryPath

    The directory path in which ObjectBox places its database files for this store.

    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.