Realm Swift enables you to efficiently write your app’s model layer in a safe, persisted and fast way. Here’s what it looks like:

// Define your models like regular Swift classes
class Dog: Object {
  dynamic var name = ""
  dynamic var age = 0
}
class Person: Object {
  dynamic var name = ""
  dynamic var picture: NSData? = nil // optionals supported
  let dogs = List<Dog>()
}

// Use them like regular Swift objects
let myDog = Dog()
myDog.name = "Rex"
myDog.age = 1
print("name of dog: \(myDog.name)")

// Get the default Realm
let realm = try! Realm()

// Query Realm for all dogs less than 2 years old
let puppies = realm.objects(Dog.self).filter("age < 2")
puppies.count // => 0 because no dogs have been added to the Realm yet

// Persist your data easily
try! realm.write {
  realm.add(myDog)
}

// Queries are updated in realtime
puppies.count // => 1

// Query and update from any thread
DispatchQueue(label: "background").async {
  let realm = try! Realm()
  let theDog = realm.objects(Dog.self).filter("age == 1").first
  try! realm.write {
    theDog!.age = 3
  }
}

If you have an app that is presently using Core Data and have been considering switching to Realm, we recently published an article discussing how to go about doing this. Go check it out!

Getting Started

Download Realm Swift or see the source on GitHub.

Prerequisites

• Apps using Realm can target: iOS 8 or later, macOS 10.9 or later, all versions of tvOS and watchOS.
• Xcode 7.3 or later required.

Installation

• Dynamic Framework
• CocoaPods
• Carthage

Importing the Realm Framework

At the top of your Swift source files, use import RealmSwift to import Realm Swift and make it available for use with your code. That’s all you need to get started!

tvOS

Because writing to the Documents directory is prohibited on tvOS, the default Realm location is set to NSCachesDirectory. However, please be mindful that tvOS can purge files in the Caches directory at any point, so we encourage you to rely on Realm as a rebuildable cache rather than storing important user data.

If you would like to share a Realm file between a tvOS app and a TV services extension (e.g. Top Shelf extension), you have to use the Library/Caches/ directory within the shared container for the application group.

let fileURL = FileManager.default
    .containerURL(forSecurityApplicationGroupIdentifier: "group.io.realm.examples.extension")!
    .appendingPathComponent("Library/Caches/default.realm")

You can also bundle prebuilt Realm files in your app. However, be sure to comply with App Store guidelines, keeping your app under 200MB.

Please browse our tvOS examples for sample tvOS apps demonstrating how to use Realm as either an offline cache or with preloaded data.

Realm Browser

We also provide a standalone Mac app named Realm Browser to read and edit .realm databases.

You can generate a test database with sample data using the menu item Tools > Generate demo database.

If you need help finding your app’s Realm file, check this StackOverflow answer for detailed instructions.

The Realm Browser is available on the Mac App Store.

Xcode Plugin

Our Xcode plugin makes it easy to generate new Realm models.

The easiest way to install the Realm Xcode plugin is through Alcatraz under the name “RealmPlugin”. You can also install the plugin manually by opening plugin/RealmPlugin.xcodeproj contained in the release zip and clicking build. You will need to quit and relaunch Xcode to see our plugin. If you use the Xcode menu to create a new file (File > New > File… — or ⌘N) you should see a new option to create a new Realm model.

API Reference

You can consult our full API reference for all classes, methods & more.

Examples

You can find example applications for both iOS and OS X in our release zip under examples/, demonstrating how to use many features of Realm like migrations, how to use it with UITableViewControllers, encryption, command-line tools and much more.

Getting Help

• Need help with your code? Ask on StackOverflow. We actively monitor & answer questions on SO!
• Have a bug to report? Open an issue on our repo. If possible, include the version of Realm, a full log, the Realm file, and a project that shows the issue.
• Have a feature request? Open an issue on our repo. Tell us what the feature should do, and why you want the feature.

If you’re using a crash reporter (like Crashlytics or HockeyApp), make sure to enable log collection. Realm logs metadata information (but no user data) when throwing exceptions and in irrecoverable situations, and these messages can help debug when things go wrong.

Models

Realm data models are defined using regular Swift classes with properties. Simply subclass Object or an existing model class to create your Realm data model objects. Realm model objects mostly function like any other Swift objects - you can add your own methods and protocols to them and use them like you would any other object. The main restriction is that you can only use an object on the thread which it was created.

If you have installed our Xcode Plugin there will be a nice template to create the Swift file in the “New File…” dialog.

Relationships and nested data structures are modeled simply by including properties of the target type or Lists for typed lists of objects.

import RealmSwift

// Dog model
class Dog: Object {
    dynamic var name = ""
    dynamic var owner: Person? // Properties can be optional
}

// Person model
class Person: Object {
    dynamic var name = ""
    dynamic var birthdate = NSDate(timeIntervalSince1970: 1)
    let dogs = List<Dog>()
}

Since Realm parses all models defined in your code at launch, they must all be valid, even if they are never used.

When using Realm from Swift, the Swift.reflect(_:) function is used to determine information about your models, which requires that calling init() succeed. This means that all non-optional properties must have a default value.

See Object for more details.

Supported Types

Realm supports the following property types: Bool, Int8, Int16, Int32, Int64, Double, Float, String, NSDate, and NSData.

CGFloat properties are discouraged, as the type is not platform independent.

String, NSDate and NSData properties can be optional. Object properties must be optional. Storing optional numbers is done using RealmOptional.

Relationships

Objects can be linked to each other by using Object and List properties. Lists have an interface very similar to Array and objects contained in a List can be accessed using indexed subscripting. Unlike Arrays, Lists only hold Objects of a single subclass type. For more details see List.

Assuming your Person model has already been defined (see above) let’s create another model called Dog:

class Dog: Object {
    dynamic var name = ""
}

To-One Relationships

For many-to-one or one-to-one relationships, simply declare a property with the type of your Object subclass:

class Dog: Object {
    // ... other property declarations
    dynamic var owner: Person? // to-one relationships must be optional
}

You can use this property like you would any other:

let jim = Person()
let rex = Dog()
rex.owner = jim

When using Object properties, you can access nested properties using normal property syntax. For example rex.owner?.address.country will traverse the object graph and automatically fetch each object from Realm as needed.

To-Many Relationships

You can define a to-many relationship using List properties. Lists contain other Objects of a single type and have an interface very similar to a mutable Array.

To add a “dogs” property on our Person model that links to multiple dogs, we can declare a property of type List<Dog>:

class Person: Object {
    // ... other property declarations
    let dogs = List<Dog>()
}

You can access and assign List properties as usual:

let someDogs = realm.objects(Dog.self).filter("name contains 'Fido'")
jim.dogs.append(objectsIn: someDogs)
jim.dogs.append(rex)

List properties are guaranteed to preserve their order of insertion.

Inverse Relationships

Links are unidirectional. So if a to-many property Person.dogs links to a Dog instance and a to-one property Dog.owner links to Person, these links are independent from one another. Appending a Dog to a Person instance’s dogs property doesn’t automatically set the dog’s owner property to this Person. Because manually synchronizing pairs of relationships is error prone, complex and duplicates information, Realm provides linking objects properties to represent these inverse relationships.

With linking objects properties, you can obtain all objects that link to a given object from a specific property. For example, a Dog object can have a property named owners that contains all of the Person objects that have this exact Dog object in their dogs property. This is done by making the owners property of type LinkingObjects and then specifying the relationship that it has with the Person object.

class Dog: Object {
    dynamic var name = ""
    dynamic var age = 0
    let owners = LinkingObjects(fromType: Person.self, property: "dogs")
}

Optional Properties

String, NSDate, and NSData properties can be declared as optional or non-optional using the standard Swift syntax. Optional numeric types are declared using RealmOptional:

class Person: Object {
    // Optional string property, defaulting to nil
    dynamic var name: String? = nil

    // Optional int property, defaulting to nil
    // RealmOptional properties should always be declared with `let`,
    // as assigning to them directly will not work as desired
    let age = RealmOptional<Int>()
}

let realm = try! Realm()
try! realm.write() {
    var person = realm.create(Person.self, value: ["Jane", 27])
    // Reading from or modifying a `RealmOptional` is done via the `value` property
    person.age.value = 28
}

RealmOptional supports Int, Float, Double, Bool, and all of the sized versions of Int (Int8, Int16, Int32, Int64).

Cheatsheet

This table provides a handy reference to declaring model properties.

Property Attributes

Realm model properties need the dynamic var attribute in order for these properties to become accessors for the underlying database data.

There are two exceptions to this: List and RealmOptional properties cannot be declared as dynamic because generic properties cannot be represented in the Objective‑C runtime, which is used for dynamic dispatch of dynamic properties, and should always be declared with let.

Indexed Properties

Override Object.indexedProperties() to set which properties in your model should be indexed:

class Book: Object {
  dynamic var price = 0
  dynamic var title = ""

  override static func indexedProperties() -> [String] {
    return ["title"]
  }
}

Realm supports indexing for string, integer, boolean, and NSDate properties.

Indexing a property will greatly speed up queries where the property is compared for equality (i.e. the = and IN operators), at the cost of slower insertions.

Auto-Updating Objects

Object instances are live, auto-updating views into the underlying data, which means objects never have to be refreshed. Modifying the properties of an object will immediately reflect in any other instances referring to the same object.

let myDog = Dog()
myDog.name = "Fido"
myDog.age = 1

try! realm.write {
  realm.add(myDog)
}

let myPuppy = realm.objects(Dog.self).filter("age == 1").first
try! realm.write {
  myPuppy!.age = 2
}

print("age of my dog: \(myDog.age)") // => 2

This aspect of Object not only keeps Realm fast and efficient, it allows your code to be simpler and more reactive. For example, if your UI code is dependent on a specific Realm object, you don’t need to worry about refreshing or re-fetching it before triggering a UI redraw.

You can subscribe to Realm notifications to know when Realm data in an object is updated, indicating when your app’s UI should be refreshed. Alternatively, you can use key-value observation to be notified when a specific property of an Object is updated.

Primary Keys

Override Object.primaryKey() to set the model’s primary key. Declaring a primary key allows objects to be looked up and updated efficiently and enforces uniqueness for each value. Once an object with a primary key is added to a Realm, the primary key cannot be changed.

class Person: Object {
  dynamic var id = 0
  dynamic var name = ""

  override static func primaryKey() -> String? {
    return "id"
  }
}

Ignored Properties

Override Object.ignoredProperties() to prevent Realm from persisting model properties. Realm won’t interfere with the regular operation of these properties: they’ll be backed by ivars and you can freely override their setters and getters.

class Person: Object {
  dynamic var tmpID = 0
  var name: String { // read-only properties are automatically ignored
    return "\(firstName) \(lastName)"
  }
  dynamic var firstName = ""
  dynamic var lastName = ""

  override static func ignoredProperties() -> [String] {
    return ["tmpID"]
  }
}

Ignored properties can’t be used in queries, they won’t retain their value when retrieving different instances the same object, won’t trigger notifications when changed, etc. They can still be KVO-observed, however.

Model Inheritance

Realm allows models to be further subclassed, allowing for much code reuse across models, but some Cocoa features that contribute to the runtime’s rich class polymorphism aren’t available. Here’s what’s possible:

• Class methods, instance methods and properties on parent classes are inherited in their child classes.
• Methods and functions that take parent classes as arguments can operate on subclasses.

The following is not possible:

• Casting between polymorphic classes (ie, subclass to subclass, subclass to parent, parent to subclass, etc.).
• Querying on multiple classes simultaneously.
• Multi-class containers (List and Results).

Adding this functionality to Realm is on the roadmap, and for the time being, we’ve provided some code samples for working around some of the more common patterns.

Alternatively, if your implementation allows it, we recommend using the following pattern of class composition to build up subclasses encompassing logic from other classes:

// Base Model
class Animal: Object {
  dynamic var age = 0
}

// Models composed with Animal
class Duck: Object {
  dynamic var animal: Animal? = nil
  dynamic var name = ""
}
class Frog: Object {
  dynamic var animal: Animal? = nil
  dynamic var dateProp = NSDate()
}

// Usage
let duck = Duck(value: [ "animal": [ "age": 3 ], "name": "Gustav" ])

Collections

Realm has several types that help represent groups of objects, which we refer to as “Realm Collections”:

1. Results, a class representing objects retrieved from queries.
2. List, a class representing to-many relationships in models.
3. LinkingObjects, a class representing inverse relationships in models.
4. RealmCollection, a protocol defining the common interface to which all Realm Collections conform.
5. AnyRealmCollection, a type-erased class that can forward calls to a concrete Realm Collection like a Results, List or LinkingObjects.

Realm Collections conform to the RealmCollection protocol, which ensures they behave consistently. This protocol inherits from CollectionType so that it may be used in the same ways as other standard library collections. Additional common Realm Collection APIs are declared in this protocol, such as querying, sorting and aggregate operations, among others. Lists have additional mutation operations that extend beyond the protocol interface such as adding and deleting objects.

Using the RealmCollection protocol, you can write generic code that can operate on any Realm collection:

func operateOn<C: RealmCollection>(collection: C) {
  // Collection could be either Results or List
  print("operating on collection containing \(collection.count) objects")
}

Because protocols with associated types in Swift aren’t concrete, it’s necessary to use a type-erased wrapper such as AnyRealmCollection in order to store this collection as a property or variable:

class ViewController {
//  let collection: RealmCollection
//                  ^
//                  error: protocol 'RealmCollection' can only be used
//                  as a generic constraint because it has Self or
//                  associated type requirements
//
//  init<C: RealmCollection>(collection: C) where C.Element == MyModel {
//    self.collection = collection
//  }

  let collection: AnyRealmCollection<MyModel>

  init<C: RealmCollection>(collection: C) where C.Element == MyModel {
    self.collection = AnyRealmCollection(collection)
  }
}

Writes

Realm objects can be instantiated and used as unmanaged objects (i.e. not yet added to a Realm) just like regular Swift objects. To share objects between threads or re-use them between app launches you must add them into a Realm, an operation which must be done within a write transaction.

Since write transactions incur non-negligible overhead, you should architect your code to minimize the number of write transactions.

Because write transactions could potentially fail like any other disk IO operations, both Realm.write() & Realm.commitWrite() are marked as throws so you can handle and recover from failures like running out of disk space. There are no other recoverable errors. For brevity, our code samples don’t handle these errors but you certainly should in your production applications.

Creating Objects

When you have defined a model you can instantiate your Object subclass and add the new instance to the Realm. Consider this simple model:

class Dog: Object {
    dynamic var name = ""
    dynamic var age = 0
}

We can create new objects in several ways:

// (1) Create a Dog object and then set its properties
var myDog = Dog()
myDog.name = "Rex"
myDog.age = 10

// (2) Create a Dog object from a dictionary
let myOtherDog = Dog(value: ["name" : "Pluto", "age": 3])

// (3) Create a Dog object from an array
let myThirdDog = Dog(value: ["Fido", 5])

1. The most obvious is to use the designated initializer to create an object.
2. Objects can also be created from dictionaries using appropriate keys and values.
3. Finally, Object subclasses can be instantiated using arrays. The values in the array have to be in the same order as the corresponding properties in the model.

Nested Objects

If an object has properties that are Objects or Lists, these can be set recursively using nested arrays and/or dictionaries. You simply replace each object with a dictionary or array representing its properties:

// Instead of using already existing dogs...
let aPerson = Person(value: ["Jane", 30, [aDog, anotherDog]])

// ...we can create them inline
let anotherPerson = Person(value: ["Jane", 30, [["Buster", 5], ["Buddy", 6]]])

This will work for any combination of nested arrays and dictionaries. Note that a List may only contain Objects, not basic types such as String.

Adding Objects

You can add an object to a Realm like so:

// Create a Person object
let author = Person()
author.name = "David Foster Wallace"

// Get the default Realm
let realm = try! Realm()
// You only need to do this once (per thread)

// Add to the Realm inside a transaction
try! realm.write {
  realm.add(author)
}

After you have added the object to the Realm you can continue using it, and all changes you make to it will be persisted (and must be made within a write transaction). Any changes are made available to other threads that use the same Realm when the write transaction is committed.

Please note that writes block each other, and will block the thread they are made on if multiple writes are in progress. This is similar to other persistence solutions and we recommend that you use the usual best practice for this situation: offloading your writes to a separate thread.

Thanks to Realm’s MVCC architecture, reads are not blocked while a write transaction is open. Unless you need to make simultaneous writes from many threads at once, you should favor larger write transactions that do more work over many fine-grained write transactions. When you commit a write transaction to a Realm, all other instances of that Realm will be notified, and be updated automatically.

See Realm and Object for more details.

Updating Objects

Realm provides a few ways to update objects, all of which offer different tradeoffs depending on the situation. Choose which one is best for your situation:

Typed Updates

You can update any object by setting its properties within a write transaction.

// Update an object with a transaction
try! realm.write {
  author.name = "Thomas Pynchon"
}

Creating and Updating Objects With Primary Keys

If your model class includes a primary key, you can have Realm intelligently update or add objects based off of their primary key values using Realm().add(_:update:).

// Creating a book with the same primary key as a previously saved book
let cheeseBook = Book()
cheeseBook.title = "Cheese recipes"
cheeseBook.price = 9000
cheeseBook.id = 1

// Updating book with id = 1
try! realm.write {
  realm.add(cheeseBook, update: true)
}

If a Book object with a primary key value of ‘1’ already existed in the database, then that object would simply be updated. If it did not exist, then a completely new Book object would be created and added to the database.

You can also partially update objects with primary keys by passing just a subset of the values you wish to update, along with the primary key:

// Assuming a "Book" with a primary key of `1` already exists.
try! realm.write {
  realm.create(Book.self, value: ["id": 1, "price": 9000.0], update: true)
  // the book's `title` property will remain unchanged.
}

You may not pass update: true for object types which don’t define a primary key.

Please note that when updating objects, nil is still considered a valid value for optional properties. If you supply a dictionary with nil property values, then these will be applied to your object and those properties will be emptied. To ensure you don’t experience any unplanned data loss, please make sure to provide only the properties you wish to update when using this method.

Key-Value Coding

Object, Result, and List all conform to key-value coding (KVC). This can be useful when you need to determine which property to update at runtime.

Applying KVC to a collection is a great way to update objects in bulk without the overhead of iterating over a collection while creating accessors for every item.

let persons = realm.objects(Person.self)
try! realm.write {
  persons.first?.setValue(true, forKeyPath: "isFirst")
  // set each person's planet property to "Earth"
  persons.setValue("Earth", forKeyPath: "planet")
}

Deleting Objects

Pass the object to be deleted to the Realm().delete(_:) method within a write transaction.

// let cheeseBook = ... Book stored in Realm

// Delete an object with a transaction
try! realm.write {
  realm.delete(cheeseBook)
}

You can also delete all objects stored in a Realm. Note the Realm file will maintain its size on disk to efficiently reuse that space for future objects.

// Delete all objects from the realm
try! realm.write {
  realm.deleteAll()
}

Queries

Queries return a Results instance, which contains a collection of Objects. Results have an interface very similar to Array and objects contained in a Results can be accessed using indexed subscripting. Unlike Arrays, Results only hold Objects of a single subclass type.

All queries (including queries and property access) are lazy in Realm. Data is only read when the properties are accessed.

Results to a query are not copies of your data: modifying the results of a query (within a write transaction) will modify the data on disk directly. Similarly, you can traverse your graph of relationships directly from the Objects contained in a Results.

Execution of a query is deferred until the results are used. This means that chaining several temporary Results to sort and filter your data does not perform extra work processing the intermediate state.

Once the query has been executed, or a notification block has been added, the Results is kept up to date with changes made in the Realm, with the query execution performed on a background thread when possible.

The most basic method for retrieving objects from a Realm is Realm().objects(_:), which returns a Results of all Object instances of the subclass type being queried from the default Realm.

let dogs = realm.objects(Dog.self) // retrieves all Dogs from the default Realm

Filtering

If you’re familiar with NSPredicate, then you already know how to query in Realm. Objects, Realm, List, and Results all provide methods that allow you to query for specific Object instances by simply passing in an NSPredicate instance, predicate string, or predicate format string just as you would when querying an NSArray.

For example, the following would extend our earlier example by calling Results().filter(_:...) to retrieve all tan-colored dogs whose names begin with ‘B’ from the default Realm:

// Query using a predicate string
var tanDogs = realm.objects(Dog.self).filter("color = 'tan' AND name BEGINSWITH 'B'")

// Query using an NSPredicate
let predicate = NSPredicate(format: "color = %@ AND name BEGINSWITH %@", "tan", "B")
tanDogs = realm.objects(Dog.self).filter(predicate)

See Apple’s Predicates Programming Guide for more information about building predicates and use our NSPredicate Cheatsheet. Realm supports many common predicates:

• The comparison operands can be property names or constants. At least one of the operands must be a property name.
• The comparison operators ==, <=, <, >=, >, !=, and BETWEEN are supported for Int, Int8, Int16, Int32, Int64, Float, Double and NSDate property types. Such as age == 45
• Identity comparisons ==, !=, e.g. Results<Employee>().filter("company == %@", company)
• The comparison operators == and != are supported for boolean properties.
• For String and NSData properties, we support the ==, !=, BEGINSWITH, CONTAINS, and ENDSWITH operators, such as name CONTAINS ‘Ja’
• For String properties, the LIKE operator may be used to compare the left hand property with the right hand expression: ? and * are allowed as wildcard characters, where ? matches 1 character and * matches 0 or more characters. Such as value LIKE '?bc*' matching strings like “abcde” and “cbc”.
• Case insensitive comparisons for strings, such as name CONTAINS[c] ‘Ja’. Note that only characters “A-Z” and “a-z” will be ignored for case.
• Realm supports the following compound operators: “AND”, “OR”, and “NOT”. Such as name BEGINSWITH ‘J’ AND age >= 32
• The containment operand IN such as name IN {‘Lisa’, ‘Spike’, ‘Hachi’}
• Nil comparisons ==, !=, e.g. Results<Company>().filter("ceo == nil"). Note that Realm treats nil as a special value rather than the absence of a value, so unlike with SQL nil equals itself.
• ANY comparisons, such as ANY student.age < 21
• The aggregate expressions @count, @min, @max, @sum and @avg are supported on List and Results properties, e.g. realm.objects(Company.self).filter("employees.@count > 5") to find all companies with more than five employees.
• Subqueries are supported with the following limitations:
  • @count is the only operator that may be applied to the SUBQUERY expression.
  • The SUBQUERY(…).@count expression must be compared with a constant.
  • Correlated subqueries are not yet supported.

For more, see Results().filter(_:...).

Sorting

Results allows you to specify a sort criteria and order based on a single or multiple properties. For example, the following calls sorts the dogs returned from the example above alphabetically by name:

// Sort tan dogs with names starting with "B" by name
let sortedDogs = realm.objects(Dog.self).filter("color = 'tan' AND name BEGINSWITH 'B'").sorted(byProperty: "name")

For more, see Results().sorted(_:) and Results().sorted(_:ascending:).

Chaining

One unique property of Realm’s query engine is the ability to chain queries with very little transactional overhead when compared to traditional databases that require a separate trip to the database server for each successive query.

For example, if we wanted a result set for just tan colored dogs, and tan colored dogs whose names also start with ‘B’, you might chain two queries like this:

let tanDogs = realm.objects(Dog.self).filter("color = 'tan'")
let tanDogsWithBNames = tanDogs.filter("name BEGINSWITH 'B'")

Auto-Updating Results

Results instances are live, auto-updating views into the underlying data, which means results never have to be re-fetched. They always reflect the current state of the Realm on the current thread, including during write transactions on the current thread. The one exception to this is when using for...in enumeration, which will always enumerate over the objects which matched the query when the enumeration is begun, even if some of them are deleted or modified to be excluded by the filter during the enumeration.

let puppies = realm.objects(Dog.self).filter("age < 2")
puppies.count // => 0
try! realm.write {
  realm.create(Dog.self, value: ["name": "Fido", "age": 1])
}
puppies.count // => 1

This applies to all Results: all objects, filtered and chained.

This property of Results not only keeps Realm fast and efficient, it allows your code to be simpler and more reactive. For example, if your view controller relies on the results of a query, you can store the Results in a property and access it without having to make sure to refresh its data prior to each access.

You can subscribe to Realm notifications to know when Realm data is updated, indicating when your app’s UI should be refreshed for example, without having to re-fetch your Results.

Since results are auto-updating, it’s important to not rely on indices and counts staying constant. The only time a Results is frozen is when fast-enumerating over it, which makes it possible to mutate the objects matching a query while enumerating over it:

try! realm.write {
  for person in realm.objects(Person.self).filter("age == 10") {
    person.age += 1
  }
}

Alternatively, use key-value coding to perform operations on Results.

Limiting Results

Most other database technologies provide the ability to ‘paginate’ results from queries (such as the ‘LIMIT’ keyword in SQLite). This is often done out of necessity to avoid reading too much from disk, or pulling too many results into memory at once.

Since queries in Realm are lazy, performing this sort of paginating behavior isn’t necessary at all, as Realm will only load objects from the results of the query once they are explicitly accessed.

If for UI-related or other implementation reasons you require a specific subset of objects from a query, it’s as simple as taking the Results object, and reading out only the objects you need.

// Loop through the first 5 Dog objects
// restricting the number of objects read from disk
let dogs = try! Realm().objects(Dog.self)
for i in 0..<5 {
  let dog = dogs[i]
  // ...
}

Realms

The Default Realm

You may have noticed so far that we have initialized access to our realm variable by calling Realm(). That method returns a Realm object that maps to a file called “default.realm” under the Documents folder (iOS) or Application Support folder (OS X) of your app.

Realm Configuration

Configuring things like where your Realm files are stored is done through Realm.Configuration. The configuration can either be passed to Realm(configuration: config) each time you need a Realm instance, or you can set the configuration to use for the default Realm with Realm.Configuration.defaultConfiguration = config.

For example, suppose you have an application where users have to log in to your web backend, and you want to support quickly switching between accounts. You could give each account its own Realm file that will be used as the default Realm by doing the following:

func setDefaultRealmForUser(username: String) {
  var config = Realm.Configuration()

  // Use the default directory, but replace the filename with the username
  config.fileURL = config.fileURL!.deletingLastPathComponent()
                         .appendingPathComponent("\(username).realm")

  // Set this as the configuration used for the default Realm
  Realm.Configuration.defaultConfiguration = config
}

Other Realms

It’s sometimes useful to have multiple Realms persisted at different locations. For example, you may want to bundle some data with your application in a Realm file, in addition to your main Realm. You can do this with the following code:

let config = Realm.Configuration(
    // Get the URL to the bundled file
    fileURL: Bundle.main.url(forResource: "MyBundledData", withExtension: "realm"),
    // Open the file in read-only mode as application bundles are not writeable
    readOnly: true)

// Open the Realm with the configuration
let realm = try! Realm(configuration: config)

// Read some data from the bundled Realm
let results = realm.objects(Dog.self).filter("age > 5")

Please note that if a custom URL is used to initialize a Realm, it must be in a location with write permissions. The most common location to store writable Realm files is the “Documents” directory on iOS and the “Application Support” directory on OS X. Please respect Apple’s iOS Data Storage Guidelines, which recommend that documents that can be regenerated be stored in the <Application_Home>/Library/Caches directory.

In-Memory Realms

Normally Realms are persisted to disk, but you can also create ones which operate purely in memory by setting the inMemoryIdentifier rather than the fileURL on your Realm.Configuration.

let realm = try! Realm(configuration: Realm.Configuration(inMemoryIdentifier: "MyInMemoryRealm"))

In-memory Realms do not save data across app launches, but all other features of Realm will work as expected, including querying, relationships and thread-safety. This is a useful option if you need flexible data access without the overhead of disk persistence.

Error Handling

Like any disk IO operation, creating a Realm instance could sometimes fail if resources are constrained. In practice, this can only happen the first time a Realm instance is created on a given thread. Subsequent accesses to a Realm from the same thread will reuse a cached instance and will always succeed.

To handle errors when first accessing a Realm on a given thread, use Swift’s built-in error handling mechanism:

do {
  let realm = try Realm()
} catch let error as NSError {
  // handle error
}

Copying Objects Between Realms

Copying Realm objects to other Realms is as simple as passing in the original object to Realm().create(_:value:update:). For example, realm.create(MyObjectSubclass.self, value: originalObjectInstance). Remember that Realm objects can only be accessed from the thread on which they were first created, so this copy will only work for Realms on the same thread.

Finding a Realm File

If you need help finding your app’s Realm file, check this StackOverflow answer for detailed instructions.

Auxiliary Realm Files

Alongside the standard .realm files, Realm also generates and maintains additional files and directories for its own internal operations.

• .realm.lock - A lock file for resource locks.
• .realm.management - Directory of interprocess lock files.
• .realm.note - A named pipe for notifications.

These files don’t have any effect on .realm database files, and won’t cause any erroneous behavior if their parent database file is deleted or replaced.

When reporting Realm issues, please be sure to include these auxiliary files along with your main .realm file as they contain useful information for debugging purposes.

Bundling a Realm with an App

It’s common to seed an app with initial data, making it available to your users immediately on first launch. Here’s how to do this:

1. First, populate the Realm. You should use the same data model as your final, shipping app to create a Realm and populate it with the data you wish to bundle with your app. Since Realm files are cross-platform, you can use an OS X app (see our JSONImport example) or your iOS app running in the simulator.
2. In the code where you’re generating this Realm file, you should finish by making a compacted copy of the file (see Realm().writeCopyToPath(_:encryptionKey:)). This will reduce the Realm’s file size, making your final app lighter to download for your users.
3. Drag the new compacted copy of your Realm file to your final app’s Xcode Project Navigator.
4. Go to your app target’s build phases tab in Xcode and add the Realm file to the “Copy Bundle Resources” build phase.
5. At this point, your bundled Realm file will be accessible to your app. You can find its path by using NSBundle.main.pathForResource(_:ofType:).
6. If the bundled Realm contains fixed data that you don’t need to modify, you can open it directly from the bundle path by setting readOnly = true on the Realm.Configuration object. Otherwise, if it’s initial data that you’ll be modifying, you can copy the bundled file to your application’s Documents directory using NSFileManager.default.copyItemAtPath(_:toPath:).

You can refer to our migration sample app for an example of how to use a bundled Realm file.

Class Subsets

In some scenarios you may wish to limit which classes can be stored in a specific Realm. For example, if you have two teams working on different components of your application which both use Realm internally, you may not want to have to coordinate migrations between them. You can do this by setting the objectTypes property of your Realm.Configuration:

let config = Realm.Configuration(objectTypes: [MyClass.self, MyOtherClass.self])
let realm = try! Realm(configuration: config)

Deleting Realm Files

In some cases, such as clearing caches, or resetting your entire dataset, it may be appropriate to completely delete a Realm file from disk.

Unlike most files, Realm files are memory-mapped and Realm instances expect the files to be available for the duration of the instance’s lifetime.

So while most files can be deleted by calling NSFileManager’s removeItemAtPath method you must take additional steps to ensure there are no active references to any Realm objects accessing the database file at the time of deletion.

Realm instances hold a database connection for the exact duration of their lifetime. One way to limit a Realm instance’s lifetime is to wrap its usage in an autorelease pool.

So all Realm instances with their fileURL set to the Realm file you want to delete must be released before the deletion is performed.

Finally, although not strictly necessary, you should delete auxiliary Realm files as well as the main Realm file to fully clean up all related files.

autoreleasepool {
  // all Realm usage here
}
let realmURL = Realm.Configuration.defaultConfiguration.fileURL!
let realmURLs = [
  realmURL,
  realmURL.appendingPathExtension("lock"),
  realmURL.appendingPathExtension("log_a"),
  realmURL.appendingPathExtension("log_b"),
  realmURL.appendingPathExtension("note")
]
for URL in realmURLs {
  do {
    try FileManager.default.removeItem(at: URL)
  } catch {
    // handle error
  }
}

Using Realm with Background App Refresh

On iOS 8 and above, files inside apps are automatically encrypted using NSFileProtection whenever the device is locked. If your app attempts to do any work involving Realm while the device is locked and the NSFileProtection attributes of your Realm files are set to encrypt them (which is the case by default), an open() failed: Operation not permitted exception will be thrown.

In order to handle this, it is necessary to ensure that the file protection attributes applied to both the Realm file itself and its auxiliary files is downgraded to a less strict one that allows file access even when the device is locked, such as NSFileProtectionCompleteUntilFirstUserAuthentication.

If you choose to opt out of complete iOS file encryption in this way, we encourage you to use Realm’s own built-in encryption to ensure your data is still properly secured.

Since the auxiliary files can sometimes be lazily created and deleted mid-operation, we recommend that you apply the file protection attributes to the parent folder containing these Realm files. This will ensure the attribute is properly applied to all of the relevant Realm files, regardless of their creation time.

let realm = try! Realm()

// Get our Realm file's parent directory
let folderPath = realm.configuration.fileURL!.deletingLastPathComponent().path

// Disable file protection for this directory
try! FileManager.default.setAttributes([FileAttributeKey(rawValue: NSFileProtectionKey): NSFileProtectionNone],
                                       ofItemAtPath: folderPath)

Threading

Within individual threads you can just treat everything as regular objects without worrying about concurrency or multithreading. There is no need for any locks or resource coordination to access them (even if they are simultaneously being modified on other threads) and it is only modifying operations that have to be wrapped in write transactions.

Realm makes concurrent usage easy by ensuring that each thread always has a consistent view of the Realm. You can have any number of threads working on the same Realms in parallel, and since they all have their own snapshots, they will never cause each other to see inconsistent state.

The only thing you have to be aware of is that you cannot have multiple threads sharing the same instances of Realm objects. If multiple threads need to access the same objects they will each need to get their own instances (otherwise changes happening on one thread could cause other threads to see incomplete or inconsistent data).

Seeing Changes From Other Threads

On the main UI thread (or any thread with a runloop) objects will automatically update with changes from other threads between each iteration of the runloop. At any other time you will be working on the snapshot, so individual methods always see a consistent view and never have to worry about what happens on other threads.

When you initially open a Realm on a thread, its state will be based off the most recent successful write commit, and it will remain on that version until refreshed. Realms are automatically refreshed at the start of every runloop iteration, unless Realm’s autorefresh property is set to NO. If a thread has no runloop (which is generally the case in a background thread), then Realm.refresh() must be called manually in order to advance the transaction to the most recent state.

Realms are also refreshed when write transactions are committed (Realm.commitWrite()).

Failing to refresh Realms on a regular basis could lead to some transaction versions becoming “pinned”, preventing Realm from reusing the disk space used by that version, leading to larger file sizes. Refer to our Current Limitations for more details on this effect.

Passing Instances Across Threads

Unmanaged instances of Objects behave exactly as regular NSObject subclasses, and are safe to pass across threads.

Instances of Realm, Results, or List, or managed instances of Object can only be used on the thread on which they were created, otherwise an exception is thrown*. This is one way Realm enforces transaction version isolation. Otherwise, it would be impossible to determine what should be done when an object is passed between threads at different transaction versions without a potentially extensive relationship graph.

Instead, there are several ways to represent instances in ways that can be safely passed between threads. For example, an object with a primary key can be represented by its primary key’s value; or a Results can be represented by its NSPredicate or query string; or a Realm can be represented by its Realm.Configuration. The target thread can then re-fetch the Realm, Object, Results, or List using its thread-safe representation. Keep in mind that re-fetching will retrieve an instance at the version of the target thread, which may differ from the originating thread.

* Some properties and methods on these types can be accessed from any thread:

• Realm: all properties, class methods, and initializers.
• Object: invalidated, objectSchema, realm, class methods, and initializers.
• Results: objectClassName and realm.
• List: invalidated, objectClassName, and realm.

Using a Realm Across Threads

To access the same Realm file from different threads, you must initialize a new Realm to get a different instance for every thread of your app. As long as you specify the same configuration, all Realm instances will map to the same file on disk.

Sharing Realm instances across threads is not supported. Realm instances accessing the same Realm file must also all use the same Realm.Configuration.

Realm can be very efficient when writing large amounts of data by batching together multiple writes within a single transaction. Transactions can also be performed in the background using Grand Central Dispatch to avoid blocking the main thread. Realm objects are not thread safe and cannot be shared across threads, so you must get a Realm instance in each thread/dispatch queue in which you want to read or write. Here’s an example of inserting a million objects in a background queue:

DispatchQueue(label: "background").async {
  autoreleasepool {
    // Get realm and table instances for this thread
    let realm = try! Realm()

    // Break up the writing blocks into smaller portions
    // by starting a new transaction
    for idx1 in 0..<1000 {
      realm.beginWrite()

      // Add row via dictionary. Property order is ignored.
      for idx2 in 0..<1000 {
        realm.create(Person.self, value: [
          "name": "\(idx1)",
          "birthdate": Date(timeIntervalSince1970: TimeInterval(idx2))
        ])
      }

      // Commit the write transaction
      // to make this data available to other threads
      try! realm.commitWrite()
    }
  }
}

JSON

Realm does not have direct support for JSON, but it’s possible to add Objects from JSON using the output of NSJSONSerialization.JSONObjectWithData(_:options:). The resulting KVC-compliant object can be used to add/update Objects using the standard APIs for creating and updating objects.

// A Realm Object that represents a city
class City: Object {
  dynamic var city = ""
  dynamic var id = 0
  // other properties left out ...
}

let data = "{\"name\": \"San Francisco\", \"cityId\": 123}".data(using: .utf8)!
let realm = try! Realm()

// Insert from NSData containing JSON
try! realm.write {
  let json = try! JSONSerialization.jsonObject(with: data, options: [])
  realm.create(City.self, value: json, update: true)
}

If there are nested objects or arrays in the JSON, these will be mapped automatically to to-one and to-many relationships - see the Nested Objects section for more detail.

When inserting or updating JSON data in a Realm using this approach, be aware that Realm expects the JSON property names and types to exactly match the Object properties. For example:

• float properties should be initialized with float-backed NSNumbers.
• NSDate and NSData properties cannot be automatically inferred from strings, but should be converted to the appropriate type before passing to Realm().create(_:value:update:).
• If a JSON null (i.e. NSNull) is supplied for a required property, an exception will be thrown.
• If no property is supplied on insert for a required property, an exception will be thrown.
• Realm will ignore any properties in the JSON not defined by the Object.

If your JSON schema doesn’t align exactly with your Realm objects, we recommend you use a third party model mapping framework in order to transform your JSON. Swift has a thriving set of actively maintained model mapping frameworks which work with Realm, some of which are listed in the realm-cocoa repository.

Notifications

It is possible to register to be notified whenever a Realm, Results, List or LinkingObjects is updated by calling the addNotificationBlock method.

It’s also possible to observe changes to a single Object through Key-Value Observation.

When notifications can’t be delivered instantly, multiple write transactions may be coalesced into a single notification.

Notifications are delivered as long as a reference is held to the returned notification token. You should keep a strong reference to this token on the class registering for updates, as notifications are automatically unregistered when the notification token is deallocated.

Realm Notifications

Realm instances send out notifications to other instances on other threads every time a write transaction is committed:

// Observe Realm Notifications
let token = realm.addNotificationBlock { notification, realm in
    viewController.updateUI()
}

// later
token.stop()

Collection Notifications

Collection notifications are different from Realm notifications in that they contain information that describe what changes have occurred at a fine-grained level. This consists of the indices of objects that have been inserted, deleted, or modified since the last notification.

Collection notifications are delivered asynchronously, first with the initial results, and then again after each write transaction which changes either any of the objects in the collection, or which objects are in the collection.

These changes can be accessed via the RealmCollectionChange parameter that is passed to the notification block. This object holds information about the indices affected by deletions, insertions and modifications.

The former two, deletions and insertions, record the indices whenever objects start and stop being part of the collection. This takes into account when you add objects to the Realm or delete them from the Realm. For Results this also applies when you filter for specific values and the object was changed so that it is now matching the query or not matching anymore. For collections based either on List or LinkingObjects, including derived Results, this applies in addition when objects are added or removed from the relationship.

You’re notified about modifications whenever a property of an object has changed, which was previously part of the collection and is still part of it. This happens as well when to-one and to-many relationships change, but doesn’t take changes on inverse relationships into account.

class Dog: Object {
  dynamic var name = ""
  dynamic var age = 0
}

class Person: Object {
  dynamic var name = ""
  let dogs = List<Dog>()
}

So let’s assume you’re observing a list of dog owners as given by the model code above, you will be notified about modifications for a matched Person object for example when:

• You modify the Person’s name property.
• You add or remove a Dog to the Person’s dogs property.
• You modify the age property of a Dog belonging to that Person.

This makes it possible to discretely control the animations and visual updates made to the content inside your UI, instead of arbitrarily reloading everything each time a notification occurs.

class ViewController: UITableViewController {
  var notificationToken: NotificationToken? = nil

  override func viewDidLoad() {
    super.viewDidLoad()
    let realm = try! Realm()
    let results = realm.objects(Person.self).filter("age > 5")

    // Observe Results Notifications
    notificationToken = results.addNotificationBlock { [weak self] (changes: RealmCollectionChange) in
      guard let tableView = self?.tableView else { return }
      switch changes {
      case .initial:
        // Results are now populated and can be accessed without blocking the UI
        tableView.reloadData()
        break
      case .update(_, let deletions, let insertions, let modifications):
        // Query results have changed, so apply them to the UITableView
        tableView.beginUpdates()
        tableView.insertRows(at: insertions.map({ IndexPath(row: $0, section: 0) }),
                           with: .automatic)
        tableView.deleteRows(at: deletions.map({ IndexPath(row: $0, section: 0)}),
                           with: .automatic)
        tableView.reloadRows(at: modifications.map({ IndexPath(row: $0, section: 0) }),
                           with: .automatic)
        tableView.endUpdates()
        break
      case .error(let error):
        // An error occurred while opening the Realm file on the background worker thread
        fatalError("\(error)")
        break
      }
    }
  }

  deinit {
    notificationToken?.stop()
  }
}

Interface-Driven Writes

Notifications in Realm are always delivered asynchronously so your app never stutters or blocks the main UI thread. However, there are situations when changes need to be done synchronously, on the main thread, and reflected in the UI instantly. We refer to these transactions as interface-driven writes.

For example, say a user adds an item to a table view. The UI should ideally animate this operation and start this process as soon as the user initiates the action.

However, when the Realm change notification for this insertion is delivered a little later, it will indicate that an object was added to the collection backing the table view and we will once again attempt to insert a new row in the UI. This double insertion leads to inconsistent state between the UI and the backing data, which in turn will crash your app! 💥NSInternalInconsistencyException💥

When performing an interface-driven write, pass the notification tokens of the notification blocks that shouldn’t react to a change for a second time to Realm.commitWrite(withoutNotifying:).

This feature is especially useful when using fine-grained collection notifications with a synchronized Realm, because many of the workarounds to previously account for interface-driven writes rely on controlling the full state of when the app can perform changes. With synchronized Realms, changes are applied whenever they’re synchronized, which can happen at any point in the app’s lifetime.

// Add fine-grained notification block
token = collection.addNotificationBlock { changes in
  switch changes {
  case .initial:
    tableView.reloadData()
    break
  case .update(_, let deletions, let insertions, let modifications):
    // Query results have changed, so apply them to the UITableView
    tableView.beginUpdates()
    tableView.insertRows(at: insertions.map({ IndexPath(row: $0, section: 0) }),
                         with: .automatic)
    tableView.deleteRows(at: deletions.map({ IndexPath(row: $0, section: 0)}),
                         with: .automatic)
    tableView.reloadRows(at: modifications.map({ IndexPath(row: $0, section: 0) }),
                         with: .automatic)
    tableView.endUpdates()
    break
  case .error(let error):
    // handle error
    break
  }
}

func insertItem() throws {
  // Perform an interface-driven write on the main thread:
  collection.realm!.beginWrite()
  collection.insert(Item(), at: 0)
  // And mirror it instantly in the UI
  tableView.insertRows(at: [IndexPath(row: 0, section: 0)], with: .automatic)
  // Making sure the change notification doesn't apply the change a second time
  try collection.realm!.commitWrite(withoutNotifying: [token])
}

Notification APIs

See the following API documentation for details:

• Realm.addNotificationBlock(_:)
• AnyRealmCollection.addNotificationBlock(_:)
• Results.addNotificationBlock(_:)
• List.addNotificationBlock(_:)
• LinkingObjects.addNotificationBlock(_:)
• NotificationToken.stop()

Key-Value Observation

Realm objects are Key-Value Observing compliant for most properties. Almost all managed (non-ignored) properties on your Object subclasses are KVO-compliant, along with the invalidated property on Object and List. (LinkingObjects properties can’t be observed using KVO.)

Observing properties of unmanaged instances of Object subclasses works just like with any other dynamic property, but note that you cannot add an object to a Realm (with realm.add(obj) or other similar methods) while it has any registered observers.

Observing properties of managed objects (those previously added to a Realm) works a little differently. With managed objects, there are three times when the value of a property may change: when you directly assign to it; when you call realm.refresh() or the Realm is automatically refreshed after a write transaction is committed on a different thread; and when you call realm.beginWrite() after changes on a different thread which have not been picked up by a refresh on the current thread.

In the latter two cases, all of the changes made in the write transaction(s) on another thread will be applied at once, and KVO notifications will all be sent at once. Any intermediate steps are discarded, so if in the write transaction you incremented a property from one to ten, on the main thread you’ll get a single notification of a change directly from one to ten. Because properties can change in value when not in a write transaction or even as part of beginning a write transaction, trying to modify managed Realm objects from within observeValueForKeyPath(_:ofObject:change:context:) is not recommended.

Unlike NSMutableArray properties, observing changes made to List properties does not require using mutableArrayValueForKey(_:), although that is supported for compatibility with code not written with Realm in mind. Instead, you can simply call the modification methods on List directly, and anyone observing the property it is stored in will be notified. List properties do not need to be marked as dynamic to be observable, unlike normal properties.

In our example apps you can find a short example of using Realm with ReactiveCocoa from Objective‑C, and ReactKit from Swift.

Migrations

When working with any database, it is likely your data model will change over time. Since data models in Realm are defined as standard Swift classes, making model changes is as easy as changing any other Swift class. For example, suppose we have the following Person model:

class Person: Object {
    dynamic var firstName = ""
    dynamic var lastName = ""
    dynamic var age = 0
}

We want to update the data model to require a fullName property, rather than separate first and last names. To do this, we simply change the object interface to the following:

class Person: Object {
    dynamic var fullName = ""
    dynamic var age = 0
}

At this point if you had saved any data with the previous model version, there will be a mismatch between what Realm sees defined in code and the data Realm sees on disk. When this occurs, an exception will be thrown when you try to open the existing file unless you run a migration.

Performing a Migration

Defining Migrations

You define a migration and the associated schema version by setting Realm.Configuration.schemaVersion and Realm.Configuration.migrationBlock. Your migration block provides all the logic for converting data models from previous schemas to the new schema. When creating a Realm with this configuration, the migration block will be applied to update the Realm to the given schema version if a migration is needed.

For example, suppose we want to migrate the Person model declared earlier. The minimal necessary migration block would be the following:

// Inside your application(application:didFinishLaunchingWithOptions:)

let config = Realm.Configuration(
  // Set the new schema version. This must be greater than the previously used
  // version (if you've never set a schema version before, the version is 0).
  schemaVersion: 1,

  // Set the block which will be called automatically when opening a Realm with
  // a schema version lower than the one set above
  migrationBlock: { migration, oldSchemaVersion in
    // We haven’t migrated anything yet, so oldSchemaVersion == 0
    if (oldSchemaVersion < 1) {
      // Nothing to do!
      // Realm will automatically detect new properties and removed properties
      // And will update the schema on disk automatically
    }
  })

// Tell Realm to use this new configuration object for the default Realm
Realm.Configuration.defaultConfiguration = config

// Now that we've told Realm how to handle the schema change, opening the file
// will automatically perform the migration
let realm = try! Realm()

At the very minimum all we need to do is to update the version with an empty block to indicate that the schema has been upgraded (automatically) by Realm.

Updating Values

While this is the minimum acceptable migration, we probably want to use this block to populate any new properties (in this case fullName) with something meaningful. Within the migration block we can call Migration().enumerateObjects(ofType: _:_:) to enumerate each Object of a certain type, and apply any necessary migration logic. Notice how for each enumeration the existing Object instance is accessed via an oldObject variable and the updated instance is accessed via newObject:

// Inside your application(application:didFinishLaunchingWithOptions:)

Realm.Configuration.defaultConfiguration = Realm.Configuration(
  schemaVersion: 1,
  migrationBlock: { migration, oldSchemaVersion in
    if (oldSchemaVersion < 1) {
      // The enumerateObjects(ofType:_:) method iterates
      // over every Person object stored in the Realm file
      migration.enumerateObjects(ofType: Person.className()) { oldObject, newObject in
        // combine name fields into a single field
        let firstName = oldObject!["firstName"] as! String
        let lastName = oldObject!["lastName"] as! String
        newObject!["fullName"] = "\(firstName) \(lastName)"
      }
    }
  })

Once the migration is successfully completed, the Realm and all of its objects can be accessed as usual by your app.

Renaming Properties

Renaming the property on a class as part of a migration is more efficient than copying values and preserves relationships rather than duplicating them.

To rename a property during a migration, make sure that your new models have a property with the new name and don’t have a property with the old name.

If the new property has different nullability or indexing settings, those will be applied during the rename operation.

Here’s how you could rename Person’s yearsSinceBirth property to age:

// Inside your application(application:didFinishLaunchingWithOptions:)

Realm.Configuration.defaultConfiguration = Realm.Configuration(
  schemaVersion: 1,
  migrationBlock: { migration, oldSchemaVersion in
    // We haven’t migrated anything yet, so oldSchemaVersion == 0
    if (oldSchemaVersion < 1) {
      // The renaming operation should be done outside of calls to `enumerateObjects(ofType: _:)`.
      migration.renameProperty(onType: Person.className(), from: "yearsSinceBirth", to: "age")
    }
  })

Adding more versions

Suppose now we have two previous versions of the Person class:

// v0
// class Person: Object {
//   dynamic var firstName = ""
//   dynamic var firstName = ""
//   dynamic var age = 0
// }

// v1
// class Person: Object {
//   dynamic var fullName = "" // new property
//   dynamic var age = 0
// }

// v2
class Person: Object {
  dynamic var fullName = ""
  dynamic var email = "" // new property
  dynamic var age = 0
}

The logic in our migration block might look like the following:

Realm.Configuration.defaultConfiguration = Realm.Configuration(
  schemaVersion: 2,
  migrationBlock: { migration, oldSchemaVersion in
    // The enumerateObjects:block: method iterates
    // over every 'Person' object stored in the Realm file
    migration.enumerateObjects(ofType: Person.className()) { oldObject, newObject in
      // Add the `fullName` property only to Realms with a schema version of 0
      if oldSchemaVersion < 1 {
        let firstName = oldObject!["firstName"] as! String
        let lastName = oldObject!["lastName"] as! String
        newObject!["fullName"] = "\(firstName) \(lastName)"
      }

      // Add the `email` property to Realms with a schema version of 0 or 1
      if oldSchemaVersion < 2 {
          newObject!["email"] = ""
      }
    }
  })

// Realm will automatically perform the migration and opening the Realm will succeed
let realm = try! Realm()

For a more complete look at the implementation of a data schema migration, check out our migration sample app.

Linear Migrations

Suppose we have two users for our app: JP and Tim. JP updates the app very often, but Tim happens to skip a few versions. It’s likely that JP has seen every new version of our app, and every schema upgrade in order: he downloaded a version of the app that took him from v0 to v1, and later another update that took him from v1 to v2. In contrast, it’s possible that Tim might download an update of the app that will need to take him from v0 to v2 immediately. Structuring your migration blocks with non-nested if (oldSchemaVersion < X) calls ensures that they will see all necessary upgrades, no matter which schema version they start from.

Another scenario may arise in the case of users who skipped versions of your app. If you delete a property email at version 2 and re-introduce it at version 3, and a user jumps from version 1 to version 3, Realm will not be able to automatically detect the deletion of the email property, as there will be no mismatch between the schema on disk and the schema in the code for that property. This will lead to Tim’s Person object having a v3 address property that has the contents of the v1 address property. This may not be a problem, unless you changed the internal storage representation of that property between v1 and v3 (say, went from an ISO address representation to a custom one). To avoid this, we recommend you nil out the email property on the if (oldSchemaVersion < 3) statement, guaranteeing that all Realms upgraded to version 3 will have a correct dataset.

Encryption

Realm supports encrypting the database file on disk with AES-256+SHA2 by supplying a 64-byte encryption key when creating a Realm.

// Generate a random encryption key
var key = Data(count: 64)
_ = key.withUnsafeMutableBytes { bytes in
  SecRandomCopyBytes(kSecRandomDefault, 64, bytes)
}

// Open the encrypted Realm file
let config = Realm.Configuration(encryptionKey: key)
do {
  let realm = try Realm(configuration: config)
  // Use the Realm as normal
  let dogs = realm.objects(Dog.self).filter("name contains 'Fido'")
} catch let error as NSError {
  // If the encryption key is wrong, `error` will say that it's an invalid database
  fatalError("Error opening realm: \(error)")
}

This makes it so that all of the data stored on disk is transparently encrypted and decrypted with AES-256 as needed, and verified with a SHA-2 HMAC. The same encryption key must be supplied every time you obtain a Realm instance.

See our encryption sample app for an end-to-end app that generates an encryption key, stores it securely in the keychain, and uses it to encrypt a Realm.

There is a small performance hit (typically less than 10% slower) when using encrypted Realms.

Testing and Debugging

Configuring the Default Realm

The easiest way to use and test Realm apps is to use the default Realm. To avoid overriding application data or leaking state between tests, you can simply set the default Realm to a new file for each test.

import XCTest

// A base class which each of your Realm-using tests should inherit from rather
// than directly from XCTestCase
class TestCaseBase: XCTestCase {
  override func setUp() {
    super.setUp()

    // Use an in-memory Realm identified by the name of the current test.
    // This ensures that each test can't accidentally access or modify the data
    // from other tests or the application itself, and because they're in-memory,
    // there's nothing that needs to be cleaned up.
    Realm.Configuration.defaultConfiguration.inMemoryIdentifier = self.name
  }
}

Injecting Realm Instances

Another way to test Realm-related code is to have all the methods you’d like to test accept a Realm instance as an argument, so that you can pass in different Realms when running the app and when testing it. For example, suppose your app has a method to GET a user profile from a JSON API and you’d like to test that the local profile is properly created:

// Application Code
func updateUserFromServer() {
  let url = URL(string: "http://myapi.example.com/user")
  URLSession.shared.dataTask(with: url!) { data, _, _ in
    let realm = try! Realm()
    createOrUpdateUser(in: realm, with: data!)
  }
}

public func createOrUpdateUser(in realm: Realm, with data: Data) {
  let object = try! JSONSerialization.jsonObject(with: data) as! [String: String]
  try! realm.write {
    realm.create(User.self, value: object, update: true)
  }
}

// Test Code

let testRealmURL = URL(fileURLWithPath: "...")

func testThatUserIsUpdatedFromServer() {
  let config = Realm.Configuration(fileURL: testRealmURL)
  let testRealm = try! Realm(configuration: config)
  let jsonData = "{\"email\": \"help@realm.io\"}".data(using: .utf8)!
  createOrUpdateUser(in: testRealm, with: jsonData)
  let expectedUser = User()
  expectedUser.email = "help@realm.io"
  XCTAssertEqual(testRealm.objects(User.self).first!, expectedUser,
                 "User was not properly updated from server.")
}

Debugging

Debugging your Realm apps is easy, with the ability to view your app’s data in the Realm Studio.

Debugging apps using Realm’s Swift API must be done through the LLDB console.

Note that although the LLDB script installed via our Xcode Plugin allows inspecting the contents of your Realm variables in Xcode’s UI, this doesn’t yet work for Swift. Instead, those variables will show incorrect data. You should instead use LLDB’s po command to inspect the contents of data stored in a Realm.

Avoid Linking Realm and Tested Code in Test Targets

Since you’re using Realm as a dynamic framework, you’ll need to make sure your unit test target can find Realm. You can do this by adding the parent path to RealmSwift.framework to your unit test’s “Framework Search Paths”.

If your tests fail with an exception message "Object type 'YourObject' is not managed by the Realm", it’s likely because you’ve linked the Realm framework directly to your test target, which should not be done. Unlinking Realm from your test target should address that.

You should also make sure to only compile your model class files in your application or framework targets; never add them to your unit test targets. Otherwise, those classes will be duplicated when testing, which can lead to difficult to debug issues (see this issue for details).

You’ll need to make sure all the code you need to test is exposed to your unit test targets (use the public access modifier or @testable). See this Stack Overflow answer for details.

Current Limitations

Here’s a list of our most commonly hit limitations.

Please refer to our GitHub issues for a more comprehensive list of known issues.

General Limits

Realm aims to strike a balance between flexibility and performance. In order to accomplish this goal, realistic limits are imposed on various aspects of storing information in a Realm. For example:

1. Class names are limited to a maximum of 57 UTF8 characters.
2. Property names are limited to a maximum of 63 UTF8 characters.
3. NSData and String properties cannot hold data exceeding 16MB in size. To store larger amounts of data, either break it up into 16MB chunks or store it directly on the file system, storing paths to these files in the Realm. An exception will be thrown at runtime if your app attempts to store more than 16MB in a single property.
4. Any single Realm file cannot be larger than the amount of memory your application would be allowed to map in iOS — this changes per device, and depends on how fragmented the memory space is at that point in time (there is a radar open about this issue: rdar://17119975). If you need to store more data, you can map it over multiple Realm files.
5. String sorting and case insensitive queries are only supported for character sets in ‘Latin Basic’, ‘Latin Supplement’, ‘Latin Extended A’, ‘Latin Extended B’ (UTF-8 range 0-591).

Threads

Although Realm files can be accessed by multiple threads concurrently, you cannot hand over Realms, Realm objects, queries, and results between threads. Read more about Realm’s threading.

Realm Object Setters & Getters cannot be overriden

Since Realm overrides setters and getters to back properties directly by the underlying database, you cannot override them on your objects. A simple workaround is to create new, Realm-ignored properties, whose accessors can be overriden, and can call other setters/getters.

File size & tracking of intermediate versions

You should expect a Realm database to take less space on disk than an equivalent SQLite database. If your Realm file is much larger than you expect, it may be because you have a Realm that is referring to an older version of the data in the database.

In order to give you a consistent view of your data, Realm only updates the active version accessed at the start of a run loop iteration. This means that if you read some data from the Realm and then block the thread on a long-running operation while writing to the Realm on other threads, the version is never updated and Realm has to hold on to intermediate versions of the data which you may not actually need, resulting in the file size growing with each write. The extra space will eventually be reused by future writes, or may be compacted — for example by calling Realm().writeCopyToPath(_:encryptionKey:).

To avoid this issue, you may call invalidate to tell Realm that you no longer need any of the objects that you’ve read from the Realm so far, which frees us from tracking intermediate versions of those objects. The Realm will update to the latest version the next time it is accessed.

You may also see this problem when accessing Realm using Grand Central Dispatch. This can happen when a Realm ends up in a dispatch queue’s autorelease pool as those pools may not be drained for some time after executing your code. The intermediate versions of data in the Realm file cannot be reused until the Realm object is deallocated. To avoid this issue, you should use an explicit autorelease pool when accessing a Realm from a dispatch queue.

Realm doesn’t have auto-incrementing properties

Realm doesn’t have a mechanism for thread-/process-safe auto-incrementing properties commonly used in other databases when generating primary keys. However, in most situations where a unique auto-generated value is desired, it isn’t necessary to have sequential, contiguous, integer IDs.

In these cases, a unique string primary key is typically sufficient. A common pattern is to set the default property value to NSUUID().UUIDString to generate unique string IDs.

Another common motivation for auto-incrementing properties is to preserve order of insertion. In some situations, this can be accomplished by appending objects to a List or by using a createdAt property with a default value of NSDate().

List and RealmOptional properties aren’t accessible from Objective‑C

If you need to access your Realm Swift models from Objective‑C, your List and RealmOptional properties will cause the auto-generated Objective‑C header (-Swift.h) to fail to compile because of the use of generics. You can work around this known Swift bug by annotating your List and RealmOptional properties as @nonobjc, which will hide them from the auto-generated Objective‑C header (-Swift.h).

Adding custom initializers to Object subclasses

When creating your model Object subclasses, you may sometimes want to add your own custom initialization methods for added convenience.

Due to some present limitations with Swift introspection, these methods cannot be designated initializers for the class. Instead, they need to be marked as convenience initializers using the Swift keyword of the same name:

class MyModel: Object {
    dynamic var myValue = ""

    convenience init(myValue: String) {
        self.init() //Please note this says 'self' and not 'super'
        self.myValue = myValue
    }
}

Encrypted Realms cannot be accessed by multiple processes simultaneously

This includes iOS Extensions. To work around this, use unencrypted Realms, which can be shared across processes. You can make use of the Security and CommonCrypto system frameworks to encrypt and decrypt data stored in NSData properties on Realm objects.

We’re tracking lifting this limitation in both the Realm Cocoa issue tracker (#1693) and the Realm Core issue tracker (#1845).

Recipes

We’ve put together some recipes showing how to use Realm to accomplish a few specific tasks. We add more recipes regularly, so check back often. If there’s an example you’d like to see, please open an issue on GitHub.

• Building a To-Do App with Realm
• Testing Realm Apps
• Sharing Data between WatchKit & your App with Realm
• Building an iOS Clustered Map View in Swift
• Building an iOS Search Controller in Swift
• Building a Grid Layout with UICollectionView and Realm Swift
• Unidirectional Data Flow in Swift

The Realm Mobile Platform

The Realm Mobile Platform extends the Realm Mobile Database across the network, enabling automatic synchronization of data across devices. In order to do this a new set of types and classes are provided that support these synchronized Realms; these new classes are additive to the existing Realm Mobile Database and are covered here.

Users

The Realm User (SyncUser) is a central concept in the Realm Object Server. To open realms on a server you first need to log in as an authorized user. The SyncUser can be authenticated to a shared Realm via a username/password scheme or through a number of additional authentication methods.

Creating and logging in a user requires 2 values:

1. the URL of the Realm Server you wish to connect to
2. a SyncCredentials with the authentication information that uniquely identifies a user (e.g., username+password, access key, etc.)

Creating the Server URL

This is an NSURL representing the location of the Realm Server:

let serverURL = NSURL(string: "http://my.realmServer.com:9080")!

Learn more about this in the authentication documentation.

Authentication

For information on which authentication providers are supported, please see the Realm Object Server Authentication docs.

Here are some examples of credentials configured for authentication with various supported providers:

let usernameCredentials = SyncCredentials.usernamePassword(username: "username", password: "password")
let googleCredentials   = SyncCredentials.google(token: "Google token")
let facebookCredentials = SyncCredentials.facebook(token: "Facebook token")
let cloudKitCredentials = SyncCredentials.cloudKit(token: "CloudKit token")

Most of these credentials simply take an authentication token provided by that service, which you must obtain in your application.

The username and password credentials type is unique because it is entirely managed by the Realm Server, giving you full control over your app’s user management. It’s also special in that it expects certain AuthenticationActions to either register, login or perform either action upon authentication.

Authenticating the User

Now, with all the required parameters the user can now be connected to the Realm Object Server and open any synchronized Realm they have access to:

SyncUser.logIn(with: credentials,
               server: serverURL) { user, error in
  if let user = user {
    // can now open a synchronized Realm with this user
  } else if let error = error {
    // handle error
  }
}

Working with Users

The Realm Mobile Platform allows a single application to be used by multiple unique users within a the context of single application on a device. Think, for example, of an email client app that supports connecting multiple separate accounts. Multiple users can be authenticated at any given time, with all active users being available via User.all().

Logging Out

When your application user wants to log out of their account, you may call User.logOut() and their data will be locally discarded once any pending local changes have been fully synchronized with the object server.

Opening a Synchronized Realm

You use the same configuration object and Realm constructors as with standalone Realms to open a synced one. Synced Realms must set the syncConfiguration property with both an authenticated SyncUser and the Realm URL. The Realm URL may contain the tilde character (~), which will be transparently expanded to represent the user’s unique identifier. This scheme easily allows you to write your app to cater to its individual users. Synced Realms cannot have an inMemoryIdentifier or fileURL configured. How synchronized Realms are cached on disk is entirely managed by the framework.

// Create the configuration
let syncServerURL = URL(string: "realm://localhost:9080/~/userRealm")!
let config = Realm.Configuration(syncConfiguration: SyncConfiguration(user: user, realmURL: syncServerURL))

// Open the remote Realm
let realm = try! Realm(configuration: config)
// Any changes made to this Realm will be synced across all devices!

Access Control

The Realm Mobile Platform provides flexible access control mechanisms to restrict which users are allowed to sync against which Realm files. This can be used, for example, to create collaborative apps where multiple users write to the same Realm. It can also be used to share data in a publisher/subscriber scenario where a single writing user shares data with many users with read permissions.

There are three axes that control the access level (permissions) of a given Realm:

• mayRead indicates that the user is allowed to read from the Realm,
• mayWrite indicates that the user is allowed to write to the Realm,
• mayManage indicates that the user is allowed to change the permissions for the Realm.

Unless permissions are explicitly modified, only the owner of a Realm can access it. The only exception is admin users: They are always granted all permissions to all Realms on the server.

Please refer to the general Realm Object Server documentation on Access Control to learn more about the concept.

Management Realm

All access level management operations can be performed by writing to the Management Realm. The Management Realm is just like a regular synchronized Realm, but that the Realm Object Server is specifically designed to react to by default. Permission Change objects can be added to the Realm to apply those changes to the access control settings of a Realm file.

To obtain the management Realm for a given Sync User, call its SyncUser.managementRealm() method.

Modifying Permissions

To modify the access control settings for a Realm file, add a SyncPermissionChange object to the Management Realm.

let managementRealm = try! user.managementRealm()
try! managementRealm.write {
  let permissionChange = SyncPermissionChange(realmURL: realmURL,    // The remote Realm URL on which to apply the changes
                                              userID: anotherUserID, // The user ID for which these permission changes should be applied
                                              mayRead: true,         // Grant read access
                                              mayWrite: true,        // Grant write access
                                              mayManage: false)      // Grant management access
  managementRealm.add(permissionChange)
}

To apply the permission changes for all Realms managed by the Sync User, specify a realmURL value of *. To apply the permission changes for all Sync Users authorized with the Object Server, specify a userID value of *.

Once the Object Server has processed the operations encoded in the SyncPermissionChange object, it will set that object’s status and statusMessage properties.

To be notified of the result of the permission change operation, simply observe the permission change object like any other Realm object (like KVO or collection notifications). See Notifications for details.

Here’s one way to be notified of the status of permission change operations:

token = managementRealm.objects(SyncPermissionChange.self).filter("id = %@", permissionChange.id).addNotificationBlock { notification in
  if case .update(let changes, _, _, _) = notification, let change = changes.first {
    // Object Server processed the permission change operation
    switch change.status {
    case .notProcessed: break // handle case
    case .success: break // handle case
    case .error: break // handle case
    }
    print(change.statusMessage) // contains error or informational message
  }
}

Logging

Realm supports a number of logging levels, these can be selected by getting a reference to the sync manager and setting the logging to the desired verbosity as follows:

SyncManager.shared.logLevel = .off

The logging levels are documented in the Realm Object Server configuration documentation.

Error reporting

Most Realm APIs support completion blocks which can be used to catch errors locally (at the site of the API call), or a global error handler can be declared as follows:

SyncManager.shared.errorHandler = { error, session in
  // handle error
}

Migrations

Automatic migrations are supported for synced Realms, but the schema version number must be incremented when making a change. At present, only additive changes are supported, such as adding a class or property to an existing class. Custom migration blocks will never be invoked.

Conflict Resolution

Conflict resolution is documented in the Realm Object Server documentation.

FAQ

How big is the Realm library?

Once your app is built for release, Realm should only add around 1MB to its size. The releases we distribute are significantly larger because they include support for iOS, watchOS and tvOS simulators, some debug symbols, and bitcode, which are all stripped by Xcode automatically when you build your app.

Is Realm open source?

Yes! Realm’s internal C++ storage engine and the language SDKs over it are entirely open source and licensed under Apache 2.0.

Realm also optionally includes a closed-source sync component, but that is not required to use Realm as an embedded database.

I see a network call to Mixpanel when I run my app, what is that?

Realm collects anonymous analytics when your app is run with a debugger attached, or when it runs in a simulator. This is completely anonymous and helps us improve the product by flagging which versions of Realm, iOS, OS X, or which language you target and which versions we can deprecate support for. This call does not run when your app is in production, or running on your user’s devices — only from inside your simulator or when a debugger is attached. You can see exactly how & what we collect, as well as the rationale for it in our source code.

Why doesn’t Realm support Swift structs as models?

There are a number of reasons why Realm doesn’t currently support this.

One is that Realm is designed to have “live” objects, a concept which is fundamentally incompatible with detached/in-memory structs. There are a number of features provided by Realm which are rendered impossible by this detachment: liveness of data, reactiveness of APIs, low memory footprint of data, performance of operations, lazy & cheap access to partial data, lack of data serialization/deserialization, keeping potentially complex object graphs synchronized, etc.

That being said, it is sometimes useful to detach objects from its backing Realm. Unfortunately, this is more often needed to work around temporary limitations in our library rather than as an ideal design decision (such as thread-confinement). This is why we’ve worked hard to ensure that standalone/detached Realm objects behave exactly like plain old NSObjects. We support making “in-memory copies” of Realm objects by exposing an initializer that creates a standalone object via KVC copying of a persisted object’s properties. For example:

let standaloneModelObject = MyModel(value: persistedModelObject)

Finally, we’d love to be able to offer an immutable, non-thread-confined, value-semantics Swift struct interface to Realm Objects. But Swift’s current language machinery, as well as some minor cosmetic limitations in our core database engine, prevent us from doing so without sacrificing all of the advantages of Realm’s “live” features outlined above. We’re working on addressing those internal shortcomings at the moment, and we’re hopeful that the property behaviors the Swift core team is currently working on (apple/swift#1297) will provide the machinery necessary for us to fully support Realm-backed Swift structs.

Troubleshooting

Crash Reporting

We encourage you to use a crash reporter in your application. Many Realm operations could potentially fail at runtime (like any other disk IO), so collecting crash reports from your application will help identify areas where either you (or us) can improve error handling and fix crashing bugs.

Most commercial crash reporters have the option of collecting logs. We strongly encourage you to enable this feature. Realm logs metadata information (but no user data) when throwing exceptions and in irrecoverable situations, and these messages can help debug when things go wrong.

Reporting Realm Issues

If you’ve found an issue with Realm, please either file an issue on GitHub or email us at help@realm.io with as much information as possible for us to understand and reproduce your issue.

The following information is very useful to us:

1. Goals.
2. Expected results.
3. Actual results.
4. Steps to reproduce.
5. Code sample that highlights the issue (full Xcode projects that we can compile ourselves are ideal).
6. Version of Realm / Xcode / OS X.
7. Version of involved dependency manager (CocoaPods / Carthage).
8. Platform, OS version & architecture on which the bug happens (e.g. 64-bit iOS 8.1).
9. Crash logs & stack traces. See Crash Reporting above for details.

Reinstalling Via Dependency Managers

If you’ve installed Realm via CocoaPods or Carthage and you’re experiencing build errors, then it’s likely that you’re either using an unsupported version of that dependency manager, Realm’s integration into the project didn’t succeed, or part of your build tools have stale caches.

If that is the case, please try removing the folders the dependency manager created and installing again.

You can also try deleting derived data and cleaning the build folder in Xcode; this can fix issues caused by updating build tool versions or making changes to your project setup such as adding a new target, sharing dependencies across targets, etc. To clean the build folder, hold down the ‘Option’ key while opening the ‘Product’ menu, then choose ‘Clean Build Folder…’. You can also type ‘Clean’ into the Xcode help search menu and select the ‘Clean Build Folder…’ menu item when it shows up in the search results.

CocoaPods

Realm can be installed via CocoaPods 0.39.0 or greater.

If you have troubles with your CocoaPods integration, it might help to reset the integration state. To achieve that simply run the following commands in Terminal out of your project directory:

pod cache clean Realm
pod cache clean RealmSwift
pod deintegrate || rm -rf Pods
pod install --verbose
rm -rf ~/Library/Developer/Xcode/DerivedData

You can also use cocoapods-deintegrate instead of deleting the Pods directory. With CocoaPods 1.0, this comes as preinstalled plugin. If you’re using an older version, you may consider installing it by gem install cocoapods-deintegrate. You can run it by pod deintegrate. That removes all traces of CocoaPods from your Xcode project.

Carthage

Realm can be installed via Carthage 0.9.2 or later.

To remove all Carthage-managed dependencies from your project, simply run the following commands in Terminal out of your project directory:

rm -rf Carthage
rm -rf ~/Library/Developer/Xcode/DerivedData
carthage update

Realm Core Binary Fails to Download

When building Realm, part of the process includes downloading the core library as a static binary and integrating it into the realm-cocoa project.

It’s been reported that in certain instances, the core binary fails to download with the following error:

Downloading core failed. Please try again once you have an Internet connection.

This error can occur due to any of the following reasons:

1. Your IP address range is from a region that is on the list of United States embargoes. In order to comply with U.S. law, Realm has not been made available in that region. For more information, please see our license.
2. You are located in mainland China, and due to the country-wide firewall are not able to properly access CloudFlare or Amazon AWS S3 services at the moment. Please see this Realm-Cocoa Issue for more information.
3. Amazon AWS S3 could be experiencing service issues. Please check the AWS Service Health Dashboard and try again later.