Inherits from NSObject
Declared in RLMRealm.h
RLMRealm.mm

Overview

An RLMRealm instance (also referred to as “a realm”) represents a Realm database.

Realms can either be stored on disk (see [RLMRealm realmWithPath:]) or in memory (see [RLMRealm inMemoryRealmWithIdentifier:]).

RLMRealm instances are cached internally, and constructing equivalent RLMRealm objects (with the same path or identifier) multiple times on a single thread within a single iteration of the run loop will normally return the same RLMRealm object. If you specifically want to ensure a RLMRealm object is destroyed (for example, if you wish to open a realm, check some property, and then possibly delete the realm file and re-open it), place the code which uses the realm within an @autoreleasepool {} and ensure you have no other strong references to it.

Warning: RLMRealm instances are not thread safe and can not be shared across threads or dispatch queues. You must call this method on each thread you want to interact with the realm on. For dispatch queues, this means that you must call it in each block which is dispatched, as a queue is not guaranteed to run on a consistent thread.

Properties

autorefresh

Set to YES to automatically update this Realm when changes happen in other threads.

@property (nonatomic) BOOL autorefresh

Discussion

If set to YES (the default), changes made on other threads will be reflected in this Realm on the next cycle of the run loop after the changes are committed. If set to NO, you must manually call refresh on the Realm to update it to get the latest version.

Even with this enabled, you can still call refresh at any time to update the Realm before the automatic refresh would occur.

Notifications are sent when a write transaction is committed whether or not this is enabled.

Disabling this on an RLMRealm without any strong references to it will not have any effect, and it will switch back to YES the next time the RLMRealm object is created. This is normally irrelevant as it means that there is nothing to refresh (as persisted RLMObjects, RLMArrays, and RLMResults have strong references to the containing RLMRealm), but it means that setting RLMRealm.defaultRealm.autorefresh = NO in application:didFinishLaunchingWithOptions: and only later storing Realm objects will not work.

Defaults to YES.

Declared In

RLMRealm.h

path

Path to the file where this Realm is persisted.

@property (nonatomic, readonly) NSString *path

Declared In

RLMRealm.h

readOnly

Indicates if this Realm was opened in read-only mode.

@property (nonatomic, readonly, getter=isReadOnly) BOOL readOnly

Declared In

RLMRealm.h

schema

The RLMSchema used by this RLMRealm.

@property (nonatomic, readonly) RLMSchema *schema

Declared In

RLMRealm.h

Class Methods

defaultRealm

Obtains an instance of the default Realm.

+ (instancetype)defaultRealm

Return Value

The default RLMRealm instance for the current thread.

Discussion

The default Realm is used by the RLMObject class methods which do not take a RLMRealm parameter, but is otherwise not special. The default Realm is persisted as default.realm under the Documents directory of your Application on iOS, and in your application’s Application Support directory on OS X.

Declared In

RLMRealm.h

defaultRealmPath

Returns the location of the default Realm as a string.

+ (NSString *)defaultRealmPath

Return Value

Location of the default Realm.

Discussion

~/Application Support/{bundle ID}/default.realm on OS X.

default.realm in your application’s documents directory on iOS.

See Also

Declared In

RLMRealm.h

encryptedRealmWithPath:key:readOnly:error:

Obtains an RLMRealm instance persisted to an encrypted file.

+ (instancetype)encryptedRealmWithPath:(NSString *)path key:(NSData *)key readOnly:(BOOL)readonly error:(NSError **)error

Parameters

path

Path to the file you want the data saved in.

key

64-byte key to use to encrypt the data.

readonly

BOOL indicating if this Realm is read-only (must use for read-only files)

error

If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, pass in NULL.

Return Value

An encrypted RLMRealm instance.

Discussion

The on-disk storage for encrypted Realms are encrypted using AES256+HMAC-SHA2, but otherwise they behave like normal persisted Realms.

Encrypted Realms currently cannot be opened while lldb is attached to the process since lldb cannot forward mach exceptions to the process being debugged. Attempting to open an encrypted Realm with lldb attached will result in an EXC_BAD_ACCESS.

Declared In

RLMRealm.h

inMemoryRealmWithIdentifier:

Obtains an RLMRealm instance for an un-persisted in-memory Realm. The identifier used to create this instance can be used to access the same in-memory Realm from multiple threads.

+ (instancetype)inMemoryRealmWithIdentifier:(NSString *)identifier

Parameters

identifier

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

Return Value

An RLMRealm instance.

Discussion

Because in-memory Realms are not persisted, you must be sure to hold on to a reference to the RLMRealm object returned from this for as long as you want the data to last. Realm’s internal cache of RLMRealms will not keep the in-memory Realm alive across cycles of the run loop, so without a strong reference to the RLMRealm a new Realm will be created each time. Note that RLMObjects, RLMArrays, and RLMResults that refer to objects persisted in a Realm have a strong reference to the relevant RLMRealm, as do RLMNotifcationTokens.

Declared In

RLMRealm.h

migrateEncryptedRealmAtPath:key:

Performs the registered migration block on an encrypted Realm at the given path.

+ (NSError *)migrateEncryptedRealmAtPath:(NSString *)realmPath key:(NSData *)key

Parameters

realmPath

The path of the Realm to migrate.

key

64-byte encryption key.

Return Value

The error that occurred while applying the migration, if any.

Discussion

As migrateRealmAtPath:, but for encrypted realms.

Declared In

RLMRealm.h

migrateRealmAtPath:

Performs the registered migration block on a Realm at the given path.

+ (NSError *)migrateRealmAtPath:(NSString *)realmPath

Parameters

realmPath

The path of the Realm to migrate.

Return Value

The error that occurred while applying the migration if any.

Discussion

This method is called automatically when opening a Realm for the first time and does not need to be called explicitly. You can choose to call this method to control exactly when and how migrations are performed.

Declared In

RLMRealm.h

realmWithPath:

Obtains an RLMRealm instance persisted at a specific file path.

+ (instancetype)realmWithPath:(NSString *)path

Parameters

path

Path to the file you want the data saved in.

Return Value

An RLMRealm instance.

Declared In

RLMRealm.h

realmWithPath:readOnly:error:

Obtains an RLMRealm instance with persistence to a specific file path with options.

+ (instancetype)realmWithPath:(NSString *)path readOnly:(BOOL)readonly error:(NSError **)error

Parameters

path

Path to the file you want the data saved in.

readonly

BOOL indicating if this Realm is read-only (must use for read-only files)

error

If an error occurs, upon return contains an NSError object that describes the problem. If you are not interested in possible errors, pass in NULL.

Return Value

An RLMRealm instance.

Discussion

Like realmWithPath:, but with the ability to open read-only realms and get errors as an NSError inout parameter rather than exceptions.

Warning: Read-only Realms do not support changes made to the file while the RLMRealm exists. This means that you cannot open a Realm as both read-only and read-write at the same time. Read-only Realms should normally only be used on files which cannot be opened in read-write mode, and not just for enforcing correctness in code that should not need to write to the Realm.

Declared In

RLMRealm.h

setDefaultRealmPath:

Set the default Realm path to a given path.

+ (void)setDefaultRealmPath:(NSString *)defaultRealmPath

Parameters

defaultRealmPath

The path to use for the default Realm.

See Also

Declared In

RLMRealm.h

setEncryptionKey:forRealmsAtPath:

Set the encryption key to use when opening Realms at a certain path.

+ (void)setEncryptionKey:(NSData *)key forRealmsAtPath:(NSString *)path

Parameters

key

64-byte encryption key to use, or nil to unset.

path

Realm path to set the encryption key for.

Discussion

This can be used as an alternative to explicitly passing the key to encryptedRealmWithPath:key:readOnly:error: each time a Realm instance is needed. The encryption key will be used any time a Realm is opened with realmWithPath: or defaultRealm.

If you do not want Realm to hold on to your encryption keys any longer than needed, then use encryptedRealmWithPath:key:readOnly:error: rather than this method.

Declared In

RLMRealm.h

setSchemaVersion:withMigrationBlock:

Specify a schema version and an associated migration block which is applied when opening any Realm with and old schema version.

+ (void)setSchemaVersion:(NSUInteger)version withMigrationBlock:(RLMMigrationBlock)block

Parameters

version

The current schema version.

block

The block which migrates the Realm to the current version.

Return Value

The error that occurred while applying the migration, if any.

Discussion

Before you can open an existing RLMRealm which has a different on-disk schema from the schema defined in your object interfaces you must provide a migration block which converts from the disk schema to your current object schema. At the minimum your migration block must initialize any properties which were added to existing objects without defaults and ensure uniqueness if a primary key property is added to an existing object.

You should call this method before accessing any RLMRealm instances which require migration. After registering your migration block Realm will call your block automatically as needed.

Warning: Unsuccessful migrations will throw exceptions when the migration block is applied. This will happen in the following cases:

  • The migration block was run and returns a schema version which is not higher than the previous schema version.
  • A new property without a default was added to an object and not initialized during the migration. You are required to either supply a default value or to manually populate added properties during a migration.

See Also

Declared In

RLMRealm.h

Instance Methods

addNotificationBlock:

Add a notification handler for changes in this RLMRealm.

- (RLMNotificationToken *)addNotificationBlock:(RLMNotificationBlock)block

Parameters

block

A block which is called to process RLMRealm notifications.

Return Value

A token object which can later be passed to removeNotification: to remove this notification.

Discussion

The block has the following definition:

 typedef void(^RLMNotificationBlock)(NSString *notification, RLMRealm *realm);

It receives the following parameters:

  • NSString *notification: The name of the incoming notification. See RLMRealmNotification for information on what notifications are sent.
  • RLMRealm *realm: The realm for which this notification occurred

Declared In

RLMRealm.h

addObject:

Adds an object to be persisted it in this Realm.

- (void)addObject:(RLMObject *)object

Parameters

object

Object to be added to this Realm.

Discussion

Once added, this object can be retrieved using the objectsWhere: selectors on RLMRealm and on subclasses of RLMObject. When added, all linked (child) objects referenced by this object will also be added to the Realm if they are not already in it. If the object or any linked objects already belong to a different Realm an exception will be thrown. Use [RLMObject createInRealm:withObject] to insert a copy of a persisted object into a different Realm.

The object to be added must be valid and cannot have been previously deleted from a Realm (i.e. isInvalidated) must be false.

Declared In

RLMRealm.h

addObjects:

Adds objects in the given array to be persisted it in this Realm.

- (void)addObjects:(id<NSFastEnumeration>)array

Parameters

array

An enumerable object such as NSArray or RLMResults which contains objects to be added to this Realm.

Discussion

This is the equivalent of addObject: except for an array of objects.

See Also

Declared In

RLMRealm.h

addOrUpdateObject:

Adds or updates an object to be persisted it in this Realm. The object provided must have a designated primary key. If no objects exist in the RLMRealm instance with the same primary key value, the object is inserted. Otherwise, the existing object is updated with any changed values.

- (void)addOrUpdateObject:(RLMObject *)object

Parameters

object

Object to be added or updated.

Discussion

As with addObject:, the object cannot already be persisted in a different Realm. Use [RLMObject createOrUpdateInRealm:withObject:] to copy values to a different Realm.

Declared In

RLMRealm.h

addOrUpdateObjectsFromArray:

Adds or updates objects in the given array to be persisted it in this Realm.

- (void)addOrUpdateObjectsFromArray:(id)array

Parameters

array

NSArray, RLMArray, or RLMResults of RLMObjects (or subclasses) to be added to this Realm.

Discussion

This is the equivalent of addOrUpdateObject: except for an array of objects.

Declared In

RLMRealm.h

beginWriteTransaction

Begins a write transaction in an RLMRealm.

- (void)beginWriteTransaction

Discussion

Only one write transaction can be open at a time. Write transactions cannot be nested, and trying to begin a write transaction on a RLMRealm which is already in a write transaction with throw an exception. Calls to beginWriteTransaction from RLMRealm instances in other threads will block until the current write transaction completes.

Before beginning the write transaction, beginWriteTransaction updates the RLMRealm to the latest Realm version, as if refresh was called, and generates notifications if applicable. This has no effect if the RLMRealm was already up to date.

It is rarely a good idea to have write transactions span multiple cycles of the run loop, but if you do wish to do so you will need to ensure that the RLMRealm in the write transaction is kept alive until the write transaction is committed.

Declared In

RLMRealm.h

cancelWriteTransaction

Revert all writes made in the current write transaction and end the transaction.

- (void)cancelWriteTransaction

Discussion

This rolls back all objects in the Realm to the state they were in at the beginning of the write transaction, and then ends the transaction.

This restores the data for deleted objects, but does not re-validated deleted accessor objects. Any RLMObjects which were added to the Realm will be invalidated rather than switching back to standalone objects. Given the following code:

 ObjectType *oldObject = [[ObjectType objectsWhere:@"..."] firstObject];
 ObjectType *newObject = [[ObjectType alloc] init];

 [realm beginWriteTransaction];
 [realm addObject:newObject];
 [realm deleteObject:oldObject];
 [realm cancelWriteTransaction];

Both oldObject and newObject will return YES for isInvalidated, but re-running the query which provided oldObject will once again return the valid object.

Calling this when not in a write transaction will throw an exception.

Declared In

RLMRealm.h

commitWriteTransaction

Commits all writes operations in the current write transaction.

- (void)commitWriteTransaction

Discussion

After this is called the RLMRealm reverts back to being read-only.

Calling this when not in a write transaction will throw an exception.

Declared In

RLMRealm.h

deleteAllObjects

Deletes all objects in this Realm.

- (void)deleteAllObjects

Declared In

RLMRealm.h

deleteObject:

Delete an object from this Realm.

- (void)deleteObject:(RLMObject *)object

Parameters

object

Object to be deleted from this Realm.

Declared In

RLMRealm.h

deleteObjects:

Delete an NSArray, RLMArray, or RLMResults of objects from this Realm.

- (void)deleteObjects:(id)array

Parameters

array

RLMArray, NSArray, or RLMResults of RLMObjects to be deleted.

Declared In

RLMRealm.h

invalidate

Invalidate all RLMObjects and RLMResults read from this Realm.

- (void)invalidate

Discussion

An RLMRealm holds a read lock on the version of the data accessed by it, so that changes made to the Realm on different threads do not modify or delete the data seen by this RLMRealm. Calling this method releases the read lock, allowing the space used on disk to be reused by later write transactions rather than growing the file. This method should be called before performing long blocking operations on a background thread on which you previously read data from the Realm which you no longer need.

All RLMObject, RLMResults and RLMArray instances obtained from this RLMRealm on the current thread are invalidated, and can not longer be used. The RLMRealm itself remains valid, and a new read transaction is implicitly begun the next time data is read from the Realm.

Calling this method multiple times in a row without reading any data from the Realm, or before ever reading any data from the Realm is a no-op. This method cannot be called on a read-only Realm.

Declared In

RLMRealm.h

refresh

Update an RLMRealm and outstanding objects to point to the most recent data for this RLMRealm.

- (BOOL)refresh

Return Value

Whether the realm had any updates. Note that this may return YES even if no data has actually changed.

Declared In

RLMRealm.h

removeNotification:

Remove a previously registered notification handler using the token returned from addNotificationBlock:

- (void)removeNotification:(RLMNotificationToken *)notificationToken

Parameters

notificationToken

The token returned from addNotificationBlock: corresponding to the notification block to remove.

Declared In

RLMRealm.h

transactionWithBlock:

Helper to perform a block within a transaction.

- (void)transactionWithBlock:(void ( ^ ) ( void ))block

Declared In

RLMRealm.h

writeCopyToPath:error:

Write a compacted copy of the RLMRealm to the given path.

- (BOOL)writeCopyToPath:(NSString *)path error:(NSError **)error

Parameters

path

Path to save the Realm to.

error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

Return Value

YES if the realm was copied successfully. Returns NO if an error occurred.

Discussion

The destination file cannot already exist.

Note that if this is called from within a write transaction it writes the current data, and not data when the last write transaction was committed.

Declared In

RLMRealm.h