✅ Sign-up for a free cluster at → <a href="https://mdb.link/free-0SjuYcdGEgQ" target="_blank" rel="noreferrer">https://mdb.link/free-0SjuYcdGEgQ</a>
✅ Get help on our Community Forums → <a href="https://mdb.link/community-0SjuYcdGEgQ" target="_blank" rel="noreferrer">https://mdb.link/community-0SjuYcdGEgQ</a>

Learn how to build an iOS app using SwiftUI and the Atlas Device SDK (formerly Realm) for local persistence. You can find the code and step by step instructions in the online Lab: <a href="https://mdb.link/swiftui-atlas-sdk" target="_blank" rel="noreferrer">https://mdb.link/swiftui-atlas-sdk</a>

Subscribe to MongoDB YouTube → <a href="https://mdb.link/subscribe" target="_blank" rel="noreferrer">https://mdb.link/subscribe</a>

Swift

Sync your iOS SwiftUI App with MongoDB Atlas using Atlas Device Sync | Part 2

✅ Sign-up for a free cluster at → <a href="https://mdb.link/free-wFEO_tfjRHs" target="_blank" rel="noreferrer">https://mdb.link/free-wFEO_tfjRHs</a>
✅ Get help on our Community Forums → <a href="https://mdb.link/community-wFEO_tfjRHs" target="_blank" rel="noreferrer">https://mdb.link/community-wFEO_tfjRHs</a>

Learn how to build an iOS app using SwiftUI and the Atlas Device SDK (formerly Realm) for local persistence. You can find the code and step by step instructions in the online Lab: <a href="https://mdb.link/swiftui-atlas-sdk" target="_blank" rel="noreferrer">https://mdb.link/swiftui-atlas-sdk</a>

Subscribe to MongoDB YouTube → <a href="https://mdb.link/subscribe" target="_blank" rel="noreferrer">https://mdb.link/subscribe</a>

Sync your iOS SwiftUI App with MongoDB Atlas using Atlas Device Sync | Part 1

Diego Freniche

Senior Developer Advocate

In a [past post](https://www.mongodb.com/developer/quickstart/document-swift-powered-frameworks-using-docc/) of this series, we showed how easy it was to generate documentation for our frameworks and libraries using DocC and the benefits of doing it. We also saw the different content we can add, like articles, how-tos, and references for our functions, classes, and structs.

But once generated, you end up with an archived DocC folder that is not _that_ easy to share. You can compress it, email it, put it somewhere in the cloud so it can be downloaded, but this is not what we want. We want:

* Automatic (and continuous) generation of our DocC documentation bundle.
* Automatic (and continuous) posting of that documentation to the web, so it can be read online. 

## What’s in a DocC bundle?

A `.doccarchive` archive is, like many other things in macOS, a folder. [Clone the repository we created with our documentation](https://github.com/mongodb-developer/realm-binary-tree-docc) and look inside `BinaryTree.doccarchive` from a terminal. 

```bash
git clone https://github.com/mongodb-developer/realm-binary-tree-docc 
cd BinaryTree.doccarchive
```

You’ll see:

```
..
├── css
│   ├── …
│   └── tutorials-overview.7d1da3df.css
├── data
│   ├── documentation
│   │   ├── binarytree
│   │   │   ├── …
│   │   │   └── treetraversable-implementations.json
│   └── tutorials
│       ├── binarytree
│       │   ├── …
│       │   └── traversingtrees.json
│       └── toc.json
├── downloads
├── favicon.ico
├── favicon.svg
├── images
│   ├── …
│   └── tree.png
├── img
│   ├── …
│   └── modified-icon.5d49bcfe.svg
├── index
│   ├── availability.index
│   ├── data.mdb
│   ├── lock.mdb
│   └── navigator.index
├── index.html
├── js
│   ├── chunk-2d0d3105.459bf725.js
│   ├ …
│   └── tutorials-overview.db178ab9.js
├── metadata.json
├── theme-settings.json
└── videos
```

This is a single-page web application. Sadly, we can’t just open `index.html` and expect it to render correctly. As [Apple explains in the documentation](https://developer.apple.com/documentation/Xcode/distributing-documentation-to-external-developers), for this to work, it has to be served from a proper web server, with a few [rewrite rules](https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html#rewriterule) added: 

> To host a documentation archive on your website, do the following:
> 
> 1. Copy the documentation archive to the directory that your web server uses to serve files. In this example, the documentation archive is SlothCreator.doccarchive.
> 1. Add a rule on the server to rewrite incoming URLs that begin with /documentation or /tutorial to SlothCreator.doccarchive/index.html.
> 1. Add another rule for incoming requests to support bundled resources in the documentation archive, such as CSS files and image assets.

They even add a sample configuration to use with the Apache `httpd` server. So, to recap:

* We can manually generate our documentation and upload it to a web server.
* We need to add the rewrite rules described in Apple’s documentation for the DocC bundle to work properly.

Each time we update our documentation, we need to generate it and upload it. Let’s generate our docs automatically.


## Automating generation of our DocC archive using GitHub Actions

We’ll continue using our [Binary Tree Package](https://github.com/mongodb-developer/realm-binary-tree) as an example to generate the documentation. We’ll add a GitHub Action to generate docs on each new push to main. This way, we can automatically refresh our documentation with the latest changes introduced in our library.

To add the action, we’ll click on the `Actions` button in our repo. In this case, a Swift Action is offered as a template to start. We’ll choose that one:

![Get started with GitHub screen, showing a “Suggested for this repository” Action for Swift projects.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/hosting_docc_01_edc5a3fe4b.png)

After clicking on `Configure`, we can start tweaking our action. A GitHub action is just a set of steps that GitHub runs in a container for us. There are predefined steps, or we can just write commands that will work in our local terminal. What we need to do is:

* Get the latest version of our code.
* Build out our documentation archive.
* Find where the `doccarchive` has been generated.
* Copy that archive to a place where it can be served online.

We’ll call our action `docc.yml`. GitHub actions are YAML files, [as the documentation tells us](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions). After adding them to our repository, they will be stored in `.github/workflows/`. So, they’re just text files we can edit locally and push to our repo.


### Getting the latest version of our code

This is the easy part. Every time a Github action starts, it creates a new, empty container and clones our repo. So, our code is there, ready to be compiled, pass all tests, and does everything we need to do with it.

Our action starts with:

```yaml

name: Generate DocC
on:
  push:
    branches: [ main ]
    
jobs:
  Build-Github-Actions:
    runs-on: macos-latest

    steps:
    - name: Git Checkout
      uses: actions/checkout@v2
```

So, here:

* We gave the action the name “Generate DocC”.
* Then we select when it’ll run, i.e., on any pushes to `main`.
* We run this on a macOS container, as we need Xcode.
* The first step is to clone our repo. We use a predefined action, `checkout`, that GitHub provides us with.


### Building out our documentation archive

Now that our code is in place, we can use `xcodebuild` to build the DocC archive. We can [build our projects from the command line](https://developer.apple.com/library/archive/technotes/tn2339/_index.html), run our tests, or in this case, build the documentation.

```bash
xcodebuild docbuild -scheme BinaryTree -derivedDataPath ./docbuild -destination 'platform=iOS Simulator,OS=latest,name=iPhone 13 mini'
```

Here we’re building to generate DocC (`docbuild` parameter), choosing the `BinaryTree` scheme in our project, putting all generated binaries in a folder at hand (`docbuild`), and using an iPhone 13 mini as Simulator. When we build our documentation, we need to compile our library too. That’s why we need to choose the Simulator (or device) used for building.


### Find where the `doccarchive` has been generated

If everything goes well, we’ll have our documentation built inside `docbuild`. We’ll search for it, as each build will generate a different hash to store the results of our build. And this is, on each run, a clean machine. To find the archive, we use:

```bash
find ./docbuild -type d -iname "BinaryTree.doccarchive"
```


### Copy our documentation to a place where it can be served online

Now that we know where our DocC archive is, it’s time to put it in a different repository. The idea is we’ll have one repository for our code and one for our generated DocC bundle. Netlify will read from this second repository and host it online.

So, we clone the repository that will hold our documentation with:

```bash
git clone https://github.com/mongodb-developer/realm-binary-tree-docc
```

So, yes, now we have two repositories, one cloned at the start of the action and now this one that holds only the documentation. We copy over the newly generated DocC archive:

          

```bash
cp -R "$DOCC_DIR" realm-binary-tree-docc
```

And we commit all changes:

```bash
cd realm-binary-tree-docc
git add .
git commit -m "$DOC_COMMIT_MESSAGE"
git status
```

Here, `$DOC_COMMIT_MESSAGE` is just a variable we populate with the last commit message from our repo and current date. But it can be any message.

After this, we need to push the changes to the documentation repository.

```bash
git config --get remote.origin.url
git remote set-url origin https://${{ secrets.API_TOKEN_GITHUB}}@github.com/mongodb-developer/realm-binary-tree-docc

git push origin
```

Here we first print our `origin` (the repo where we’ll be pushing our changes) with

```bash
git config --get remote.origin.url
```

This command will show the origin of a git repository. It will print the URL of our code repository. But this is not where we want to push. We want to push to the _documentation_ repository. So, we set the origin pointing to [https://github.com/mongodb-developer/realm-binary-tree-docc](https://github.com/mongodb-developer/realm-binary-tree-docc). As we will need permission to push changes, we authenticate using a Personal Access Token. From [Github Documentation on Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token):

> You should create a personal access token to use in place of a password with the command line or with the API.


![Github Settings page to add Personal Access Tokens](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/hosting_docc_02_79756268e0.png)


Luckily, Github Actions [has a way to store these secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets), so they’re publicly accessible. Just go to your repository’s Settings and expand Secrets. You’ll see an “Actions” option. There you can give your secret a name to be used later in your actions.


![Repository Secrets, showing API_TOKEN_GITHUB](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/hosting_docc_03_830c4af9aa.png)

For reference, [this is the complete action I’ve used](https://github.com/mongodb-developer/realm-binary-tree/blob/main/.github/workflows/main.yml).


## Hosting our DocC archives in Netlify

As shown in this [excellent post](https://josephduffy.co.uk/posts/hosting-docc-archives) by [Joseph Duffy](https://twitter.com/Joe_Duffy), we'll be hosting our documentation in [Netlify](https://www.netlify.com/). Creating a free account is super easy. In this case, I advise you to use your Github credentials to log in Netlify. This way, adding a new site that reads from a Github repo will be super easy. Just add a new site and select Import an existing project. You can then choose Github, and once authorized, you’ll be able to select one of your repositories. 

Now I set it to deploy with “Any pull request against your production branch / branch deploy branches.” So, every time your repo changes, Netlify will pick up the change and host it online (if it’s a web app, that is).

But we’re missing just one detail. Remember I mentioned before that we need to add some rewrite rules to our hosted documentation? We’ll add those in a file called [`netlify.toml`](https://github.com/mongodb-developer/realm-binary-tree-docc/blob/main/netlify.toml). This file looks like:

```toml
[build]
publish = "BinaryTree.doccarchive/"

[[redirects]]
from = "/documentation/*"
status = 200
to = "/index.html"

[[redirects]]
from = "/tutorials/*"
status = 200
to = "/index.html"

[[redirects]]
from = "/data/documentation.json"
status = 200
to = "/data/documentation/binarytree.json"

[[redirects]]
force = true
from = "/"
status = 302
to = "/documentation/"

[[redirects]]
force = true
from = "/documentation"
status = 302
to = "/documentation/"

[[redirects]]
force = true
from = "/tutorials"
status = 302
to = "/tutorials/"
```

To use it in your projects, just review the lines:

```toml
publish = "BinaryTree.doccarchive/"
…
to = "/data/documentation/binarytree.json"
```

And change them accordingly.


## Recap

In this post, we’ve seen how to:

* Add a Github Action to a [code repository](https://github.com/mongodb-developer/realm-binary-tree) that continuously builds a DocC documentation bundle every time we push a change to the code.
* That action will in turn push that newly built documentation to a [documentation repository](https://github.com/mongodb-developer/realm-binary-tree-docc) for our library.
* That documentation repository will be set up in Netlify and add some rewrite rules so we'll be able to [host it online](https://binary-tree-doc.netlify.app/documentation/).

Don’t wait and add continuous generation of your library’s documentation to your CI pipeline!


Learn how to use Github Actions to generate the DocC documentation for our Swift libraries and publish it to be accessed online using Netlify.

Continuously Building and Hosting our Swift DocC Documentation Using Github Actions and Netlify

Michael Lynn

Principal Developer Advocate

This article will help you build a command line executable tool that manipulates data in a MongoDB database.

Build a Command Line Tool With Swift and MongoDB

Rachelle Palmer

Product Lead, Developer Experience

> Some features mentioned below will be deprecated on Sep. 30, 2025. [Learn more](https://www.mongodb.com/products/updates/product-support-deprecation?tck=notice_product_deprecation_2024).

MongoDB is halting development on our server-side Swift driver. We remain excited about Swift and will continue our development of our mobile Swift SDK.

We released our server-side Swift driver in 2020 as an open source project and are incredibly proud of the work that our engineering team has contributed to the Swift community over the last four years. Unfortunately, today we are announcing our decision to stop development of the MongoDB server-side Swift driver. We understand that this news may come as a disappointment to the community of current users.

There are still ways to use MongoDB with Swift:

 - Use the MongoDB driver with server-side Swift applications as is 
 - Use the [MongoDB C Driver](https://www.mongodb.com/docs/drivers/c/) directly in your server-side Swift projects
 - Usage of another community Swift driver, mongokitten

Community members and developers are welcome to fork our existing driver and add features as you see fit - the Swift driver is under the Apache 2.0 license and [source code is available on GitHub](https://github.com/mongodb/mongo-swift-driver). For those developing client/mobile applications, MongoDB offers the [Realm Swift SDK](https://www.mongodb.com/docs/realm/sdk/swift/) with real time sync to MongoDB Atlas.

We would like to take this opportunity to express our heartfelt appreciation for the enthusiastic support that the Swift community has shown for MongoDB. Your loyalty and feedback have been invaluable to us throughout our journey, and we hope to resume development on the server-side Swift driver in the future.

MongoDB is halting development on our server-side Swift driver. We remain excited about Swift and will continue our development of our mobile Swift SDK.

Halting Development on MongoDB Swift Driver

# Adding Realm as a Dependency to an iOS Framework


## Introduction

In this post we’ll review how we can add RealmSwift as a dependency to our libraries, using two different methods: Xcode assistants and the Swift Package Manager.


## The Problem 

I have a little, nice Binary Tree library. I know that I will use it for a later project, and that it'll be used at least in a macOS and iOS app. Maybe also a Vapor web app. So I decided to create a Framework to hold this code. But some of my model classes there need to be persisted in some way locally in the phone later. The Realm library is perfect for this, as I can start working with regular objects and store them locally and, later, if I need a ~~no code~~ really simple & quick to implement backend solution I can use Atlas Device Sync.

But the problem is, how do we add Realm as a dependency in our Frameworks?


## Solution 1: Use Xcode to Create the Framework and Add Realm with SPM

The first way to create the Framework is just to create a new Xcode Project. Start Xcode and select `File > New > Project`. In this case I’ll change to the iOS tab, scroll down to the Framework & Library section, then select Framework. This way I can share this Framework between my iOS app and its extensions, for instance.

![Choosing a template for the project](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_dependency_framework_3_38b52507fe.png)

Now we have a new project that holds our code. This project has two targets, one to build the Framework itself and a second one to run our Unit Tests. Every time we write code we should test it, but this is especially important for reusable code, as one bug can propagate to multiple places.

To add Realm/Swift as a dependency, open your project file in the File Navigator. Then click on the Project Name and change to the Swift Packages tab. Finally click on the + button to add a new package. 

![Adding Realm as a Package to the Project, step by step](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/add_realm_swift_framework_c6525c705c.gif)

In this case, we’ll add Realm Cocoa, a package that contains two libraries. We’re interested in  Realm Swift: [https://github.com/realm/realm-cocoa](https://github.com/realm/realm-cocoa). We want one of the latest versions, so we’ll choose “Up to major version” 10.0.0. Once the resolution process is done, we can select RealmSwift.

Nice! Now that the package is added to our Framework we can compile our code containing Realm Objects without any problems!


## Solution 2: create the Framework using SPM and add the dependency directly in Package.swift

The other way to author a framework is to create it using the Swift Package Manager. We need to add a Package Manifest (the Package.swift file), and follow a certain folder [structure](https://developer.apple.com/documentation/xcode/creating_a_standalone_swift_package_with_xcode). We have two options here to create the package:



*   Use the Terminal
*   Use Xcode


### Creating the Package from Terminal



*   Open Terminal / CLI
*   Create a folder with `mkdir yourframeworkname`
*   Enter that folder with `cd yourframeworkname`
*   Run `swift package init`
*   Once created, you can open the package with `open Package.swift`

    
![Terminal showing the results of running above commands](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_dependency_framework_2_b01503b34b.png)


### Creating the Package using Xcode

You can also use Xcode to do all this for you. Just go to `File > New > Swift Package`, give it a name and you’ll get your package with the same structure.


![Xcode showing the newly created Package.swift](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/realm_dependency_framework_1_146e545d92.png)



### Adding Realm as a dependency

So we have our Framework, with our library code and we can distribute it easily using Swift Package Manager. Now, we need to add Realm Swift. We don’t have the nice assistant that Xcode shows when you create the Framework using Xcode, so we need to add it manually to `Package.swift`

The complete `Package.swift` file


```swift
let package = Package(
    name: "BinaryTree",
    platforms: [
        .iOS(.v14)
    ],
    products: [
        // Products define the executables and libraries a package produces, and make them visible to other packages.
        .library(
            name: "BinaryTree",
            targets: ["BinaryTree"]),
    ],
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        .package(name: "Realm", url: "https://github.com/realm/realm-cocoa", from: "10.7.0")
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages this package depends on.
        .target(
            name: "BinaryTree",
            dependencies: [.product(name: "RealmSwift", package: "Realm")]),
        .testTarget(
            name: "BinaryTreeTests",
            dependencies: ["BinaryTree"]),
    ]
)
```


Here, we declare a package named “BinaryTree”, supporting iOS 14


```swift
let package = Package(
    name: "BinaryTree",
    platforms: [
        .iOS(.v14)
    ],
```


As this is a library, we declare the products we’re going to build, in this case it’s just one target called `BinaryTree`.


```swift
products: [
        // Products define the executables and libraries a package produces, and make them visible to other packages.
        .library(
            name: "BinaryTree",
            targets: ["BinaryTree"]),
    ],
```


Now, the important part: we declare Realm as a dependency in our library. We’re giving this dependency the short name “Realm” so we can refer to it in the next step.


```swift
dependencies: [
        // Dependencies declare other packages that this package depends on.
        .package(name: "Realm", url: "https://github.com/realm/realm-cocoa", from: "10.7.0")
    ],
```


In our target, we use the previously defined `Realm` dependency.


```swift
.target(
            name: "BinaryTree",
            dependencies: [.product(name: "RealmSwift", package: "Realm")]),
```


And that’s all! Now our library can be used as a Swift Package normally, and it will include automatically Realm.


## Recap

In this post we’ve seen different ways to create a Framework, directly from Xcode or as a Swift Package, and how to add `Realm` as a dependency to that Framework. This way, we can write code that uses Realm and distribute it quickly using SPM. 

In our next post in this series we’ll document this library using the new Documentation Compiler (DocC) from Apple. Stay tuned and thanks for reading!

If you have questions, please head to our [developer community website](https://developer.mongodb.com/) where the Realm engineers and the Realm/MongoDB community will help you build your next big idea with Realm and MongoDB.


Adding Realm to a project is how we usually work. But sometimes, we want to create a framework that uses Realm. How do we do that?

Adding Realm as a Dependency to an iOS Framework

Kaitlin Mahar

Lead Engineer

Recently, [Rachelle Palmer](https://www.linkedin.com/in/rachellepalmer/), Senior Product Manager for MongoDB Drivers sat down with [Kaitlin Mahar](https://www.linkedin.com/in/kaitlinmahar/), Lead Engineer for the `Swift` and `Rust` drivers to discuss some of the exciting developments in the `Swift` space. This article details that conversation.

Swift is a well documented, easy to use and convenient language focused on iOS app development. As one of the top ten languages, it's more popular than Ruby, Go, or Rust, but keeps a fairly low profile - it's the underestimated backbone of millions of applications, from Airbnb to LinkedIn. With its simple syntax and strong performance profile, Swift is versatile enough to be used for many use cases and applications, and we've watched with great interest as the number of customers using Swift with MongoDB has grown.

Swift can also be used for more than mobile, and we've seen a growing number of developers worldwide use Swift for backend development - software engineers can easily extend their skills with this concise, open source language. Kaitlin Mahar, and I decided we'd like to share more about MongoDB's commitment and involvement with the Swift community and how that influences some of the initiatives on our Swift driver roadmap.

**Rachelle (RP):** I want to get right to the big announcement! Congratulations on joining the Swift Server Working Group (SSWG). What is the SSWG and what are some of the things that the group is thinking about right now?

**Kaitlin (KM):** The SSWG is a steering team focused on promoting the use of Swift on the server. Joining the SSWG is an honor and a privilege for me personally - through my work on the driver and attendance at conferences like [Serverside.swift](https://www.serversideswift.info/), I've become increasingly involved in the community over the last couple of years and excited about the huge potential I see for Swift on the server, and being a part of the group is a great opportunity to get more deeply involved in this area. There are representatives in the group from Apple, [Vapor](https://vapor.codes/) (a popular Swift web framework), and Amazon. The group right now is primarily focused on guiding the development of a robust ecosystem of libraries and tools for server-side Swift. We run an incubation process for such projects, focused on providing overall technical direction, ensuring compatibility between libraries, and promoting best practices.

To that end, one thing we're thinking about right now is [connection pooling](https://forums.swift.org/t/generic-connection-pool/39161). The ability to pool connections is very important for a number of server-side use cases, and right now developers who need a pool have to implement one from scratch. A generalized library would make it far easier to, for example, write a new database driver in Swift. Many SSWG members as well as the community at large are interested in such a project and I'm very excited to see where it goes.

A number of other foundational libraries and tools are being worked on by the community as well, and we've been spending a lot of time thinking about and discussing those: for example, [standardized APIs to support tracing](https://forums.swift.org/t/current-state-of-swift-tracing/39830), and a new library called [Swift Service Lifecycle](https://swift.org/blog/swift-service-lifecycle/) which helps server applications manage their startup and shutdown sequences.

**RP:** When we talk with customers about using Swift for backend development, asking how they made that choice, it seems like the answers are fairly straightforward: with limited time and limited resources, it was the fastest way to get a web app running with a team of iOS developers. Do you feel like Swift is compelling to learn if you aren't an iOS developer though? Like, as a first language instead of Python?

**KM:** Absolutely! My first language was Python, and I see a lot of things I love about Python in Swift: it's succinct and expressive, and it's easy to quickly pick up on the basics. At the same time, Swift has a really powerful and strict type system similar to what you might have used in compiled languages like Java before, which makes it far harder to introduce bugs in your code, and forces you to address edge cases (for example, null values) up front. People often say that Swift borrows the best parts of a number of other languages, and I agree with that. I think it is a great choice whether it is your first language or fifth language, regardless of if you're interested in iOS development or not.

**RP:** Unquestionably, I think there's a great match here - we have MongoDB which is really easy and quick to get started with, and you have Swift which is a major win for developer productivity.

**RP:** What's one of your favorite Swift features?

**KM:** Enums with associated values are definitely up there for me. We use these in the driver a lot. They provide a very succinct way to express that particular values are present under certain conditions. For example, MongoDB allows users to specify either a string or a document as a "hint" about what index to use when executing a query. Our API clearly communicates these choices to users by defining our `IndexHint` type like this:

``` swift
public enum IndexHint {
   /// Specifies an index to use by its name.
   case indexName(String)
   /// Specifies an index to use by a specification `BSONDocument` containing the index key(s).
   case indexSpec(BSONDocument)
}
```

This requires the user to explicitly specify which version of a hint they want to use, and requires that they provide a value of the correct corresponding type along with it.

**RP:** I'd just like to say that mine is the `MemoryLayout` type. Being able to see the memory footprint of a class that you've defined is really neat. We're also excited to announce that our top priority for the next 6-9 months is rewriting our driver to be purely in Swift. For everyone who is wondering, why wasn't our official Swift driver "all Swift" initially? And why change now?

**KM:** We initially chose to wrap libmongoc as it provided a solid, reliable core and allowed us to deliver a great experience at the API level to the community sooner. The downside of that was of course, for every feature we want to do, the C driver had to implement it first sometimes this slowed down our release cadence. We also feel that writing driver internals in pure Swift will enhance performance, and give better memory safety - for example, we won't have to spend as much time thinking about properly freeing memory when we're done using it.

If you're interested in learning more about Swift, and how to use Swift for your development projects with MongoDB, here are some resources to check out:

-   [Introduction to Server-Side Swift and Building a Command Line Executable](https://www.youtube.com/watch?v=cHB8hzUSCpE)
-   [The Swift driver GitHub](https://github.com/mongodb/mongo-swift-driver)

Kaitlin will also be on an upcoming [MongoDB Podcast episode](https://mongodb.com/podcast) to talk more about working with Swift so make sure you subscribe and stay tuned!

If you have questions about the Swift Driver, or just want to interact with other developers using this and other drivers, visit us [in the MongoDB Community](https://community.mongodb.com) and be sure to introduce yourself and say hello!

Swift is a well-documented, easy-to-use, convenient language focused on iOS app development. Get an update on MongoDB's ongoing commitment to Swift.

An Update on MongoDB's Ongoing Commitment to Swift

Andrew Morgan

Staff Developer Advocate

## Introduction

[Murphy's law](https://en.wikipedia.org/wiki/Murphy%27s_law) dictates that as soon as your mobile app goes live, you'll receive a request to add a new feature. Then another. Then another.

This is fine if these features don't require any changes to your data schema. But, that isn't always the case.

Fortunately, Realm has built-in functionality to make schema migration easier.

This tutorial will step you through updating an existing mobile app to add some new features that require changes to the schema. In particular, we'll look at the Realm migration code that ensures that no existing data is lost when the new app versions are rolled out to your production users.

We'll use the [Scrumdinger app that I modified in a previous post to show how Apple's sample Swift app could be ported to Realm](https://www.mongodb.com/developer/how-to/realm-swiftui-scrumdinger-migration/). The starting point for the app can be found in [this branch of our Scrumdinger repo](https://github.com/realm/Scrumdinger/tree/realm) and the final version is in [this branch](https://github.com/realm/Scrumdinger/tree/new-schema).

Note that the app we're using for this post doesn't use [Atlas Device Sync](https://www.mongodb.com/docs/atlas/app-services/sync/learn/overview/). If it did, then the schema migration process would be very different—that's covered in [Migrating Your iOS App's **Synced** Realm Schema in Production](https://www.mongodb.com/developer/how-to/realm-sync-migration/).

## Prerequisites

This tutorial has a dependency on [Realm-Cocoa 10.13.0+](https://github.com/realm/realm-cocoa/releases).

## Baseline App/Realm Schema

As a reminder, the starting point for this tutorial is the ["realm" branch of the Scrumdinger repo](https://github.com/realm/scrumdinger/tree/realm).

![Animated gif of the original Scrumdinger app in action](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/scrumdinger_original_b6a15f10ea.gif)

There are two Realm model classes that we'll extend to add new features to Scrumdinger. The first, [DailyScrum](https://github.com/realm/Scrumdinger/blob/realm/Scrumdinger/Models/DailyScrum.swift), represents one scrum:

``` swift
class DailyScrum: Object, ObjectKeyIdentifiable {
   @Persisted var title = ""
   @Persisted var attendeeList = RealmSwift.List<String>()
   @Persisted var lengthInMinutes = 0
   @Persisted var colorComponents: Components?
   @Persisted var historyList = RealmSwift.List<History>()


   var color: Color { Color(colorComponents ?? Components()) }
   var attendees: [String] { Array(attendeeList) }
   var history: [History] { Array(historyList) }
   ...
}
```

The second, [History](https://github.com/realm/Scrumdinger/blob/realm/Scrumdinger/Models/History.swift), represents the minutes of a meeting from one of the user's scrums:

``` swift
class History: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var date: Date?
   @Persisted var attendeeList = List<String>()
   @Persisted var lengthInMinutes: Int = 0
   @Persisted var transcript: String?
   var attendees: [String] { Array(attendeeList) }
   ...
}
```

We can use [Realm Studio](https://docs.mongodb.com/realm/studio/) to examine the contents of our Realm database after the `DailyScrum` and `History` objects have been created:

![DailyScrum data shown in RealmStudio](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Daily_Scrum_original_117e226072.png)

![History data shown in RealmStudio](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/History_original_fcc4e0b78d.png)

[Accessing Realm Data on iOS Using Realm Studio](https://www.mongodb.com/developer/how-to/realm-ios-database-access-using-realm-studio/) explains how to locate and open the Realm files from your iOS simulator.

## Schema Change #1—Mark Scrums as Public/Private

The first new feature we've been asked to add is a flag to indicate whether each scrum is public or private:

![Screen capture highlighting the new status - set to "Private"](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Scrumdinger_show_privacy_00eb2f407b.png)

![Screen capture showing the user setting the meeting status to "Public"](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Scrumdinger_edit_privacy_8df1447d57.png)

This feature requires the addition of a new `Bool` named `isPublic` to [DailyScrum](https://github.com/realm/Scrumdinger/blob/new-schema/Scrumdinger/Models/DailyScrum.swift):

``` swift
class DailyScrum: Object, ObjectKeyIdentifiable {
   @Persisted var title = ""
   @Persisted var attendeeList = RealmSwift.List<String>()
   @Persisted var lengthInMinutes = 0
   @Persisted var isPublic = false
   @Persisted var colorComponents: Components?
   @Persisted var historyList = RealmSwift.List<History>()


   var color: Color { Color(colorComponents ?? Components()) }
   var attendees: [String] { Array(attendeeList) }
   var history: [History] { Array(historyList) }
   ...
}
```

Remember that our original version of Scrumdinger is already in production, and the embedded Realm database is storing instances of `DailyScrum`. We don't want to lose that data, and so we must migrate those objects to the new schema when the app is upgraded.

Fortunately, Realm has built-in functionality to automatically handle the addition and deletion of fields. When adding a field, Realm will use a default value (e.g., `0` for an `Int`, and `false` for a `Bool`).

If we simply upgrade the installed app with the one using the new schema, then we'll get a fatal error. That's because we need to tell Realm that we've updated the schema. We do that by setting the schema version to 1 (the version defaulted to 0 for the original schema):

``` swift
@main
struct ScrumdingerApp: SwiftUI.App {
   var body: some Scene {
       WindowGroup {
           NavigationView {
               ScrumsView()
                   .environment(\.realmConfiguration,
                       Realm.Configuration(schemaVersion: 1))
           }
       }
   }
}
```

After upgrading the app, we can use [Realm Studio](https://docs.mongodb.com/realm/studio/) to confirm that our `DailyScrum` object has been updated to initialize `isPublic` to `false`:

![RealmStudio showing that the new, isPublic field has been initialised to false](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Daily_Scrum_updated_19c30fabd6.png)

## Schema Change #2—Store The Number of Attendees at Each Meeting

The second feature request is to show the number of attendees in the history from each meeting:

![Screen capture showing that the number of attendees is now displayed in the meeting minutes](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Scrumdinger_History_Change_5218655494.png)

We could calculate the count every time that it's needed, but we've decided to calculate it just once and then store it in our [History](https://github.com/realm/Scrumdinger/blob/new-schema/Scrumdinger/Models/History.swift) object in a new field named `numberOfAttendees`:

``` swift
class History: EmbeddedObject, ObjectKeyIdentifiable {
   @Persisted var date: Date?
   @Persisted var attendeeList = List<String>()
   @Persisted var numberOfAttendees = 0
   @Persisted var lengthInMinutes: Int = 0
   @Persisted var transcript: String?
   var attendees: [String] { Array(attendeeList) }
   ...
}
```

We increment the schema version to 2. Note that the schema version applies to all Realm objects, and so we have to set the version to 2 even though this is the first time that we've changed the schema for `History`.

If we leave it to Realm to initialize `numberOfAttendees`, then it will set it to 0—which is not what we want. Instead, we provide a `migrationBlock` which initializes new fields based on the old schema version:

``` swift
@main
struct ScrumdingerApp: SwiftUI.App {
   var body: some Scene {
       WindowGroup {
           NavigationView {
               ScrumsView()
                   .environment(\.realmConfiguration, Realm.Configuration(
                       schemaVersion: 2,
                       migrationBlock: { migration, oldSchemaVersion in
                            if oldSchemaVersion < 1 {
                                // Could init the `DailyScrum.isPublic` field here, but the default behavior of setting
                                // it to `false` is what we want.
                            }
                            if oldSchemaVersion < 2 {
                                migration.enumerateObjects(ofType: History.className()) { oldObject, newObject in
                                    let attendees = oldObject!["attendeeList"] as? RealmSwift.List<DynamicObject>
                                    newObject!["numberOfAttendees"] = attendees?.count ?? 0
                                }
                            }
                            if oldSchemaVersion < 3 {
                                // TODO: This is where you'd add you're migration code to go from version
                                // to version 3 when you next modify the schema
                            }
                        }
                   ))
           }
       }
   }
}
```

Note that all other fields are migrated automatically.

It's up to you how you use data from the previous schema to populate fields in the new schema. E.g., if you wanted to combine `firstName` and `lastName` from the previous schema to populate a `fullName` field in the new schema, then you could do so like this:

``` swift
migration.enumerateObjects(ofType: Person.className()) { oldObject, newObject in
   let firstName = oldObject!["firstName"] as! String
   let lastName = oldObject!["lastName"] as! String
   newObject!["fullName"] = "\(firstName) \(lastName)"
}
```

We can't know what "old version" of the schema will be already installed on a user's device when it's upgraded to the latest version (some users may skip some versions,) and so the `migrationBlock` must handle all previous versions. Best practice is to process the incremental schema changes sequentially:

* `oldSchemaVersion < 1` : Process the delta between v0 and v1
* `oldSchemaVersion < 2` : Process the delta between v1 and v2
* `oldSchemaVersion < 3` : Process the delta between v2 and v3
* ...

Realm Studio shows that our code has correctly initialized `numberOfAttendees`:

![Realm Studio showing that the numberOfAttendees field has been set to 2 – matching the number of attendees in the meeting history](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/History_new_11564ec4b0.png)

## Conclusion

It's almost inevitable that any successful mobile app will need some schema changes after it's gone into production. Realm makes adapting to those changes simple, ensuring that users don't lose any of their existing data when upgrading to new versions of the app.

For changes such as adding or removing fields, all you need to do as a developer is to increment the version with each new deployed schema. For more complex changes, you provide code that computes the values for fields in the new schema using data from the old schema.

This tutorial stepped you through adding two new features that both required schema changes. You can view the final app in the [new-schema branch of the Scrumdinger repo](https://github.com/realm/Scrumdinger/tree/new-schema).

## Next Steps

This post focussed on schema migration for an iOS app. You can find some [more complex examples in the repo](https://github.com/realm/realm-cocoa/tree/master/examples/ios/swift/Migration).

If you're working with an app for a different platform, then you can find instructions in the docs:

* [Node.js](https://docs.mongodb.com/realm/sdk/node/examples/modify-an-object-schema/)
* [Android](https://docs.mongodb.com/realm/sdk/android/examples/modify-an-object-schema/)
* [iOS](https://docs.mongodb.com/realm/sdk/android/examples/modify-an-object-schema/)
* [.NET](https://docs.mongodb.com/realm/sdk/dotnet/examples/modify-an-object-schema/)
* [React Native](https://docs.mongodb.com/realm/sdk/react-native/examples/modify-an-object-schema/)

If you've any questions about schema migration, or anything else related to Realm, then please post them to our [community forum](https://www.mongodb.com/community/forums/c/realm-sdks/58).

Learn how to safely update your iOS app's Realm schema to support new functionality—without losing any existing data

Migrating Your iOS App's Realm Schema in Production

How to incorporate Realm into your iOS App. Building a chat app with SwiftUI and Realm-Cocoa

Building a Mobile Chat App Using Realm – Integrating Realm into Your App

The [Realm](https://www.realm.io) makes it much
faster to develop mobile applications. [Realm
Studio](https://github.com/realm/realm-studio) is a desktop app that
lets you view, manipulate, and import data held within your mobile app's
Realm database.

This article steps through how to track down the locations of your iOS
Realm database files, open them in Realm Studio, view the data, and make
changes. If you're developing an Android app, then finding the Realm
database files will be a little different (we'll follow up with an
Android version later), but if you can figure out how to locate the
Realm file, then the instructions on using Realm Studio should work.

## Prerequisites

If you want to build and run the app for yourself, this is what you'll
need:

-   A Mac.
-   Xcode – any reasonably recent version will work.
-   Realm Studio 10.1.0+ – earlier versions had an issue when working
    with Realms using [Atlas Device
    Sync](https://www.mongodb.com/app-services/device-sync).

I'll be using the data and schema from my existing
[RChat](https://github.com/ClusterDB/RChat) iOS app. You can use any
Realm-based app, but if you want to understand more about RChat, check
out [Building a Mobile Chat App Using Realm – Data Architecture](/how-to/realm-swiftui-ios-chat-app) and
[Building a Mobile Chat App Using Realm – Integrating Realm into Your App](/how-to/building-a-mobile-chat-app-using-realm).

## Walkthrough

This walkthrough shows you how to:

- [Install & Run Realm Studio](#install---run-realm-studio)
- [Track Down Realm Data Files – Xcode Simulator](#track-down-realm-data-files---xcode-simulator)
- [Track Down Realm Data Files – Real iOS Devices](#track-down-realm-data-files---real-ios-devices)
- [View Realm Data](#view-realm-data)
- [Add, Modify, and Delete Data](#add--modify--and-delete-data)

### Install & Run Realm Studio

I'm using [Realm Studio
10.1.1](https://studio-releases.realm.io/v10.1.1) to create this
article. If you have 10.1.0 installed, then that should work too.

If you don't already have Realm Studio 10.1.0+ installed, then [download
it here](https://studio-releases.realm.io/) and install.

That's it.

But, when you open the app, you're greeted by this:

![Realm Studio Splash Screen](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/Realm-Studio-Splash-Screen.png)

There's a single button letting me "Open Realm file," and when I click
on it, I get a file explorer where I can browse my laptop's file system.

Where am I supposed to find my Realm file? I cover that in the next
section.

### Track Down Realm Data Files – Xcode Simulator

If you're running your app in one of Xcode's simulators, then the Realm
files are stored in your Mac's file system. They're typically somewhere
along the lines of
`~/Library/Developer/CoreSimulator/Devices/???????/data/Containers/Data/Application/???????/Documents/mongodb-realm/???????/????????/???????.realm`.

The scientific way to find the file's location is to add some extra code
to your app or to use a breakpoint.

While my app's in development, I'll normally print the location of a
Realm's file whenever I open it. Don't worry if you're not explicitly
opening your Realm(s) in your code (e.g., if you're using the default
realm) as I'll cover the file search approach soon. This is the code to
add to your app once you've opened your realm – `realm`:

``` swift
print("User Realm User file location: \(realm.configuration.fileURL!.path)")
```

If you don't want to edit the code, then an Xcode breakpoint delivers
the same result:

![XCode breakpoint to find realm file](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/xcode-breakpoint-to-find-realm-file.png)

Once you have the file location, open it in Realm Studio from the
terminal:

``` bash
open /Users/andrew.morgan/Library/Developer/CoreSimulator/Devices/E7526AFE-E886-490A-8085-349C8E8EDC5B/data/Containers/Data/Application/C3ADE2F2-ABF0-4BD0-9F47-F21894E850DB/Documents/mongodb-realm/rchat-saxgm/60099aefb33c57e9a9828d23/%22user%3D60099aefb33c57e9a9828d23%22.realm
```

Less scientific but simpler is to take advantage of the fact that the
data files will always be of type `realm` and located somewhere under
`~/Library/Developer/CoreSimulator/Devices`. Open Finder in that folder:
`open ~/Library/Developer/CoreSimulator/Devices` and then create a
"saved search" so that you can always find all of your realm files.
You'll most often be looking for the most recent one.

![Create saved search](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/Create-Saved-Search.gif)

The nice thing about this approach is that you only need to create the
search once. Then click on "Realms," find the file you need, and then
double-click it to open it in Realm Studio.

### Track Down Realm Data Files – Real iOS Devices

Unfortunately, you can't use Realm Studio to interact with live Realm
files on a real iOS device.

What we can do is download a copy of your app's Realm files from your
iOS device to your laptop. You need to connect your iOS device to your
Mac, agree to trust the computer, etc.

Once connected, you can use Xcode to download a copy of the "Container"
for your app. Open the Xcode device manager—"Window/Devices and
Simulators." Find your device and app, then download the container:

![Download iOS app container](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/Download-iOS-app-container.gif)

Note that you can only access the containers for apps that you've built
and installed through Xcode, not ones you've installed through the App
Store.

Right-click the downloaded file and "Show Package Contents." You'll find
your Realm files under
`AppData/Documents/mongodb-realm/<app-name>/?????`. Find the file for
the realm you're interested in and double-click it to open it in Realm
Studio.

### View Realm Data

After opening a Realm file, Realm Studio will show a window with all of
the top-level Realm Object classes in use by your app. In this example,
the realm I've opened only contains instances of the `Chatster` class.
There's a row for each `Chatster` Object that I'd created through the
app:

![Top level chatster view](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/top-level-chatster-view.png)

If there are a lot of objects, then you can filter them using a simple
[query
syntax](https://docs.mongodb.com/realm-legacy/docs/javascript/latest/api/tutorial-query-language.html):

![Janey search](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/Janey-search.png)

If the Realm Object class contains a `List` or an `EmbeddedObject`, then
they will show as blue links—in this example, `conversations` and
`userPreferences` are a list of `Conversation` objects and an embedded
`UserPreferences` object respectively:

![User object](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/user-object.png)

Clicking on one of the `UserPreferences` links brings up the contents of
the embedded object:

![User preferences object](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/user-preferences-object.png)

### Add, Modify, and Delete Data

The ability to view your Realm data is invaluable for understanding
what's going on inside your app.

Realm Studio takes it a step further by letting you add, modify, and
delete data. This ability helps to debug and test your app.

As a first example, I click on "Create ChatMessage" to add a new message
to a conversation:

![Create chat message button](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/create-chatmessage-button.png)

Fill out the form and click "Create" to add the new `ChatMessage`
object:

![Create new message](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/create-new-message.png)

We can then observe the effect of that change in our app:

![Add message](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/add-message.gif)

I could have tested that change using the app, but there are different
things that I can try using Realm Studio.

I haven't yet included the ability to delete or edit existing messages,
but I can now at least test that this view can cope when the data
changes:

![Modify chat objects](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/old_images/how-to/realm-studio/modify-chat-objects.gif)

## Summary

In this article, we've seen how to find and open your iOS Realm data
files in Realm Studio. We've viewed the data and then made changes and
observed the iOS app reacting to those changes.

Realm Studio has several other useful features that I haven't covered
here. As it's a GUI, it's fairly easy to figure out how to use them, and
the [docs](https://docs.realm.io/sync/realm-studio) are available if you
get stuck. These functions include:

-   Import data into Realm from a CSV file.
-   Export your Realm data as a JSON file.
-   Edit the schema.
-   Open the Realm file from an app and export the schema in a different
    language. We used this for the [WildAid O-FISH
    project](https://github.com/wildaid). I created the schema in the
    iOS app, and another developer exported a Kotlin version of the
    schema from Realm Studio to use in the Android app.

## References

-   [GitHub Repo for RChat App](https://github.com/ClusterDB/RChat).
-   Read [Building a Mobile Chat App Using Realm – Data Architecture](/how-to/realm-swiftui-ios-chat-app) to understand the data model and partitioning strategy behind the RChat app.
-   Read [Building a Mobile Chat App Using Realm – Integrating Realm into Your App](/how-to/building-a-mobile-chat-app-using-realm) to learn how to create the RChat app.
-   If you're building your first SwiftUI/Realm app, then check out [Build Your First iOS Mobile App Using Realm, SwiftUI, & Combine](/how-to/realm-swiftui-combine-first-app).
-   [GitHub Repo for Realm-Cocoa SDK](https://github.com/realm/realm-cocoa).
-   [Realm Cocoa SDK documentation](https://realm.io/docs/swift/latest/).
-   [MongoDB's Realm documentation](https://docs.mongodb.com/realm/).

>
>
>If you have questions, please head to our [developer community
>website](https://community.mongodb.com/) where the MongoDB engineers and
>the MongoDB community will help you build your next big idea with
>MongoDB.
>
>


Discover how to access and manipulate your iOS App's Realm data using the Realm Studio GUI.

Accessing Realm Data on iOS Using Realm Studio

 I recently [revealed on Twitter](https://twitter.com/k__mahar/status/1494118397491269636) something that may have come as a surprise to many of my followers from the Swift/iOS community: I had never written an iOS app before! I've been writing Swift for a few years now but have focused entirely on [library development](https://www.youtube.com/watch?v=9-fdbG9jNt4) and [server-side Swift](https://www.swift.org/server/).

A highly compelling feature of Swift is that it allows you to write an iOS app and a corresponding backend – a complete, end-to-end application – all in the same language. This is similar to how using [Node.js](https://nodejs.org/en/) for a web app backend allows you to write Javascript everywhere.

To test this out and learn about iOS development, I decided to build a full-stack application entirely in Swift. I settled on a familiar CRUD app I've created a web version of before, an application that allows the user to manage a list of kittens and information about them.

I chose to build the app using the following components:
* A backend server, written using the popular Swift web framework [Vapor](https://vapor.codes/) and using the [MongoDB Swift driver](https://github.com/mongodb/mongo-swift-driver) via [MongoDBVapor](https://github.com/mongodb/mongodb-vapor) to store data in MongoDB
* An iOS application built with [SwiftUI](https://developer.apple.com/xcode/swiftui/) and using [SwiftBSON](https://github.com/mongodb/swift-bson) to support serializing/deserializing data to/from [extended JSON](https://docs.mongodb.com/manual/reference/mongodb-extended-json/), a version of JSON with MongoDB-specific extensions to simplify type preservation
* A [SwiftPM](https://www.swift.org/package-manager/) package containing the code I wanted to share between the two above components

I was able to combine all of this into a single code base with a folder structure as follows:
```
FullStackSwiftExample/
├── Models/
│   ├── Package.swift
│   └── Sources/
│       └── Models/
│           └── Models.swift
├── Backend/
│   ├── Package.swift
│   └── Sources/
│       ├── App/
│       │   ├── configure.swift
│       │   └── routes.swift
│       └── Run/
│           └── main.swift
└── iOSApp/
    └── Kittens/
        ├── KittensApp.swift
        ├── Utilities.swift
        ├── ViewModels/
        │   ├── AddKittenViewModel.swift
        │   ├── KittenListViewModel.swift
        │   └── ViewUpdateDeleteKittenViewModel.swift
        └── Views/
            ├── AddKitten.swift
            ├── KittenList.swift
            └── ViewUpdateDeleteKitten.swift
```

Overall, it was a great learning experience for me, and although the app is pretty basic, I'm proud of what I was able to put together! [Here](https://github.com/mongodb/mongo-swift-driver/tree/main/Examples/FullStackSwiftExample) is the finished application, instructions to run it, and documentation on each component.

In the rest of this post, I'll discuss some of my takeaways from this experience.

## 1. Sharing data model types made it straightforward to consistently represent my data throughout the stack.

As I mentioned above, I created a shared SwiftPM package for any code I wanted to use both in the frontend and backend of my application. In that package, I defined `Codable` types modeling the data in my application, for example:

```swift
/**
* Represents a kitten.
* This type conforms to `Codable` to allow us to serialize it to and deserialize it from extended JSON and BSON.
* This type conforms to `Identifiable` so that SwiftUI is able to uniquely identify instances of this type when they
* are used in the iOS interface.
*/
public struct Kitten: Identifiable, Codable {
   /// Unique identifier.
   public let id: BSONObjectID

   /// Name.
   public let name: String

   /// Fur color.
   public let color: String

   /// Favorite food.
   public let favoriteFood: CatFood

   /// Last updated time.
   public let lastUpdateTime: Date

   private enum CodingKeys: String, CodingKey {
       // We store the identifier under the name `id` on the struct to satisfy the requirements of the `Identifiable`
       // protocol, which this type conforms to in order to allow usage with certain SwiftUI features. However,
       // MongoDB uses the name `_id` for unique identifiers, so we need to use `_id` in the extended JSON
       // representation of this type.
       case id = "_id", name, color, favoriteFood, lastUpdateTime
   }
}
```

When you use separate code/programming languages to represent data on the frontend versus backend of an application, it's easy for implementations to get out of sync.  But in this application, since the same exact model type gets used for the frontend **and** backend representations of kittens, there can't be any inconsistency.

Since this type conforms to the `Codable` protocol, we also get a single, consistent definition for a kitten's representation in external data formats. The formats used in this application are:
* [Extended JSON](https://docs.mongodb.com/manual/reference/mongodb-extended-json/), which the frontend and backend use to communicate via HTTP, and
* [BSON](https://docs.mongodb.com/manual/reference/bson-types/), which the backend and MongoDB use to communicate

For a concrete example of using a model type throughout the stack, when a user adds a new kitten via the UI, the data flows through the application as follows:
1. The iOS app creates a new `Kitten` instance containing the user-provided data
1. The `Kitten` instance is serialized to extended JSON via `ExtendedJSONEncoder` and sent in a POST request to the backend
1. The Vapor backend deserializes a new instance of `Kitten` from the extended JSON data using `ExtendedJSONDecoder`
1. The `Kitten` is passed to the MongoDB driver method `MongoCollection<Kitten>.insertOne()`
1. The MongoDB driver uses its built-in `BSONEncoder` to serialize the `Kitten` to BSON and send it via the MongoDB [wire protocol](https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/) to the database

With all these transformations, it can be tricky to ensure that both the frontend and backend remain in sync in terms of how they model, serialize, and deserialize data.  Using Swift everywhere and sharing these `Codable` data types allowed me to avoid those problems altogether in this app.

## 2. Working in a single, familiar language made the development experience seamless.

Despite having never built an iOS app before, I found my existing Swift experience made it surprisingly easy to pick up on the concepts I needed to implement the iOS portion of my application. I suspect it's more common that someone would go in the opposite direction, but I think iOS experience would translate well to writing a Swift backend too!

I used several Swift language features such as [protocols](https://docs.swift.org/swift-book/LanguageGuide/Protocols.html), [trailing closures](https://docs.swift.org/swift-book/LanguageGuide/Closures.html), and [computed properties](https://docs.swift.org/swift-book/LanguageGuide/Properties.html) in both the iOS and backend code. I was also able to take advantage of Swift's new built-in features for [concurrency](https://docs.swift.org/swift-book/LanguageGuide/Concurrency.html) throughout the stack. I used the `async` APIs on [`URLSession`](https://developer.apple.com/documentation/foundation/urlsession) to send HTTP requests from the frontend, and I used Vapor and the MongoDB driver's `async` APIs to handle requests on the backend.  It was much easier to use a consistent model and syntax for concurrent, asynchronous programming throughout the application than to try to keep straight in my head the concurrency models for two different languages at once.

In general, using the same language really made it feel like I was building a single application rather than two distinct ones, and greatly reduced the amount of context-switching I had to do as I alternated between work on the frontend and backend. 

## 3. SwiftUI and iOS development are really cool!

Many of my past experiences trying to cobble together a frontend for school or personal projects using HTML and Javascript were frustrating.  This time around, the combination of using my favorite programming language and an elegant, declarative framework made writing the frontend very enjoyable. More generally, it was great to finally learn a bit about iOS development and what most people writing Swift and that I know from the Swift community do!

---

In conclusion, my first foray into iOS development building this full-stack Swift app was a lot of fun and a great learning experience. It strongly demonstrated to me the benefits of using a single language to build an entire application, and using a language you're already familiar with as you venture into programming in a new domain.

I've included a list of references below, including a link to the example application. Please feel free to get in touch with any questions or suggestions regarding the application or the MongoDB libraries listed below – the best way to get in touch with me and my team is by filing a [GitHub issue](https://github.com/mongodb/mongo-swift-driver/issues/new/choose) or [Jira ticket](http://jira.mongodb.org/browse/SWIFT)!

## References
* [Example app source code](https://github.com/mongodb/mongo-swift-driver/tree/main/Examples/FullStackSwiftExample)
* [MongoDB Swift driver](https://github.com/mongodb/mongo-swift-driver) and [documentation](https://mongodb.github.io/mongo-swift-driver/docs/current/MongoSwift/index.html)
* [MongoDBVapor](https://github.com/mongodb/mongodb-vapor) and [documentation](https://mongodb.github.io/mongodb-vapor/current/index.html)
* [SwiftBSON](https://github.com/mongodb/swift-bson) and [documentation](https://mongodb.github.io/swift-bson/docs/current/SwiftBSON/index.html)
* [Vapor](https://vapor.codes/)
* [SwiftUI](https://developer.apple.com/xcode/swiftui/)

Curious about mobile and server-side swift? Use this tutorial and example code!

Building a Full Stack application with Swift

It's a MongoDB axiom that you get the best performance and scalability by storing together the data that's most commonly accessed together.

The simplest and most obvious approach to achieve this is to embed all related data into a single document. This works great in many cases, but there are a couple of scenarios where it can become inefficient:

* (Very) many to many relationships. This can lead to duplicated data. This duplication is often acceptable — storage is comparatively cheap, after all. It gets more painful when the duplicated data is frequently modified. You then have the cost of updating every document which embeds that data.
* Reading small parts of large documents. Even if your query is only interested in a small fraction of fields in a document, the whole document is brought into cache — taking up memory that could be used more effectively.
* Large, mutable documents. Whenever your application makes a change to a document, the entire document must be written back to disk at some point (could be combined with other changes to the same document). WiredTiger writes data to disk in 4 KB blocks after compression — that typically maps to a 16-20 KB uncompressed document. If you're making lots of small edits to a 20+ KB document, then you may be wasting disk IO.

If embedding all of the data in a single document isn't the right pattern for your application, then consider the single-collection design. The single-collection pattern can deliver comparable read performance to embedded documents, while also optimizing for updates.

There are variants on the single-collection pattern, but for this post, I focus on the key aspects:

* Related data that's queried together is stored in the same collection.
* The documents can have different structures.
* Indexes are added so that all of the data for your frequent queries can be fetched with a single index lookup.

At this point, your developer brain may be raising questions about how your application code can cope with this. It's common to read the data from a particular collection, and then have the MongoDB driver convert that document into an object of a specific class. How does that work if the driver is fetching documents with different shapes from the same collection? This is the primary thing I want to demonstrate in this post. 

I'll be using Swift, but the same principles apply to other languages. To see how to do this with Java/Spring Data, take a look at [Single-Collection Designs in MongoDB with Spring Data](https://www.mongodb.com/developer/languages/java/java-single-collection-springpart1/).

## Running the example code

I recently started using the [MongoDB Swift Driver](https://www.mongodb.com/docs/drivers/swift/) for the first time. I decided to build a super-simple Mac desktop app that lets you browse your collections (which [MongoDB Compass](https://www.mongodb.com/products/compass) does a **much** better job of) and displays Change Stream events in real time (which Compass doesn't currently do).

You can download the code from the [Swift-Change-Streams repo](https://github.com/mongodb-developer/Swift-Change-Streams). Just build and run from Xcode.

Provide your connection-string and then browse your collections. Select the "Enable change streams" option to display change events in real time.

![A simple desktop browser, connecting to a MongoDB cluster, browsing the collections, and enabling Change Streams. We then see change-stream events shown in the tool. Changes showup as a yellow JSON document which shows the changes as well as the new doc. Inserts show as green, and deletes as red.
](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Mongo_DB_swift_a13687ce13.gif)

The app will display data from most collections as generic JSON documents, with no knowledge of the schema. There's a special case for a collection named "Collection" in a database named "Single" — we'll look at that next.

### Sample data

The Simple.Collection collection needs to contain these (or similar) documents:

```json
{ _id: 'basket1', docType: 'basket', customer: 'cust101' }
{ _id: 'basket1-item1', docType: 'item', name: 'Fish', quantity: 5 }
{ _id: 'basket1-item2', docType: 'item', name: 'Chips', quantity: 3 }
```

This data represents a shopping basket with an `_id` of "basket1". There are two items associated with `basket1 — basket1-item1` and `basket1-item2`. A single query will fetch all three documents for the basket (find all documents where `_id` starts with "basket1"). There is always an index on the `_id` attribute, and so that index will be used.

Note that all of the data for a basket in this dataset is extremely small — **well** below the 16-20K threshold — and so in a real life example, I'd actually advise embedding everything in a single document instead. The single-collection pattern would make more sense if there were a large number of line items, and each was large (e.g., if they embedded multiple thumbnail images).

Each document also has a `docType` attribute to identify whether the document refers to the basket itself, or one of the associated items. If your application included a common query to fetch just the basket or just the items associated with the basket, then you could add a composite index: `{ _id: 1, docType: 1}`.

Other uses of the `docType` field include:

* A prompt to help humans understand what they're looking at in the collection.
* Filtering the data returned from a query to just certain types of documents from the collection.
* Filtering which types of documents are included when using MongoDB Compass to examine a collection's schema.
* Allowing an application to identify what type of document its received. The application code can then get the MongoDB driver to unmarshal the document into an object of the correct class. This is what we'll look at next.

### Handling different document types from the same collection

We'll use the same desktop app to see how your code can discriminate between different types of documents from the same collection.

The app has hardcoded knowledge of what a basket and item documents looks like. This allows it to render the document data in specific formats, rather than as a JSON document:

![The desktop tool is showing documents from the "Single.Collection" collection. Rather than showing the document as generic JSON, the app shows tiles for the basket and for each of the 2 items. Each tile renders data from the associated document in a format that makes sense for that document type.
](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/different_doc_types_2fb553a6ab.png)

The code to determine the document `docType` and convert the document to an object of the appropriate class can be found in [CollectionView.swift](https://github.com/mongodb-developer/Swift-Change-Streams/blob/main/MongoDBSwift/Views/CollectionView.swift). 

CollectionView fetches all of the matching documents from MongoDB and stores them in an array of `BSONDocument`s:

```swift
@State private var docs = [BSONDocument]()
```

The application can then loop over each document in `docs`, checks the `docType` attribute, and then decides what to do based on that value:

```swift
List(docs, id: \.hashValue) { doc in
    if path.dbName == "Single" && path.collectionName == "Collection" {      
        if let docType = doc["docType"] {
            switch docType {
            case "basket":
                if let basket = basket(doc: doc) {
                    BasketView(basket: basket)
                }
            case "item":
                if let item = item(doc: doc) {
                    ItemView(item: item)
                }
            default:
                Text("Unknown doc type")
            }
        }
    } else {
        JSONView(doc: doc)
    }
}
```

If `docType == "basket"`, then the code converts the generic doc into a `Basket` object and passes it to `BasketView` for rendering.

This is the `Basket` class, including initializer to create a `Basket` from a `BSONDocument`: 

```swift
struct Basket: Codable {
    let _id: String
    let docType: String
    let customer: String
    
    init(doc: BSONDocument) {
        do {
            self = try BSONDecoder().decode(Basket.self, from: doc)
        } catch {
            _id = "n/a"
            docType = "basket"
            customer = "n/a"
            print("Failed to convert BSON to a Basket: \(error.localizedDescription)")
        }
    }
}
```

Similarly for `Item`s:

```swift
struct Item: Codable {
    let _id: String
    let docType: String
    let name: String
    let quantity: Int
    
    init(doc: BSONDocument) {
        do {
            self = try BSONDecoder().decode(Item.self, from: doc)
        } catch {
            _id = "n/a"
            docType = "item"
            name = "n/a"
            quantity = 0
            print("Failed to convert BSON to a Item: \(error.localizedDescription)")
        }
    }
}
```

The sub-views can then use the attributes from the properly-typed object to render the data appropriately:

```swift
struct BasketView: View {
    let basket: Basket
    
    var body: some View {
        VStack {
            Text("Basket")
                .font(.title)
            Text("Order number: \(basket._id)")
            Text("Customer: \(basket.customer)")
        }
        .padding()
        .background(.secondary)
        .clipShape(RoundedRectangle(cornerRadius: 15.0))
    }
}
```

```swift
struct ItemView: View {
    let item: Item
    
    var body: some View {
        VStack {
            Text("Item")
                .font(.title)
            Text("Item name: \(item.name)")
            Text("Quantity: \(item.quantity)")
        }
        .padding()
        .background(.secondary)
        .clipShape(RoundedRectangle(cornerRadius: 15.0))
    }
}
```

### Conclusion

The single-collection pattern is a way to deliver read and write performance when embedding or [other design patterns](https://learn.mongodb.com/courses/m320-mongodb-data-modeling) aren't a good fit.

This pattern breaks the 1-1 mapping between application classes and MongoDB collections that many developers might assume. This post shows how to work around that:

* Extract a single docType field from the BSON document returned by the MongoDB driver.
* Check the value of docType and get the MongoDB driver to map the BSON document into an object of the appropriate class.

Questions? Comments? Head over to our [Developer Community](https://www.mongodb.com/community/forums/) to continue the conversation!

You can improve application performance by storing together data that’s accessed together. This can be done through embedding sub-documents, or by storing related documents in the same collection — even when they have different shapes. This post explains how to work with these polymorphic MongoDB collections from your Swift app.

Working with the MongoDB Single-Collection Pattern in Swift

My day job is to work with our biggest customers to help them get the best out of MongoDB when creating new applications or migrating existing ones. Their use cases often need side effects to be run whenever data changes — one of the most common requirements is to maintain an audit trail.

When customers are using MongoDB Atlas, it's a no-brainer to recommend [Atlas Triggers](https://www.mongodb.com/docs/atlas/triggers/). With triggers, you provide the code, and Atlas makes sure that it runs whenever the data you care about changes. There's no need to stand up an app server, and triggers are very efficient as they run alongside your data.

Unfortunately, there are still some workloads that customers aren't ready to move to the public cloud. For these applications, I recommend [change streams](https://www.mongodb.com/docs/manual/changeStreams/). Change streams are the underlying mechanism used by Triggers and many other MongoDB technologies — Kafka Connector, Charts, Spark Connector, Atlas Search, anything that needs to react to data changes.

Using change streams is surprisingly easy. Ask the MongoDB Driver to open a change stream and it returns a database cursor. Listen to that cursor, and your application receives an event for every change in your collection.

This post shows you how to use change streams from a Swift application. The principles are exactly the same for other languages. You can find a lot more on change streams at [Developer Center](https://www.mongodb.com/developer/products/mongodb/change-streams/).

## Running the example code

I recently started using the [MongoDB Swift Driver](https://www.mongodb.com/docs/drivers/swift/) for the first time. I decided to build a super-simple Mac desktop app that lets you browse your collections (which [MongoDB Compass](https://www.mongodb.com/products/compass) does a **much** better job of) and displays change stream events in real time (which Compass doesn't currently do).

You can download the code from the [Swift-Change-Streams repo](https://github.com/mongodb-developer/Swift-Change-Streams). Just build and run from Xcode.

Provide your connection-string and then browse your collections. Select the "Enable change streams" option to display change events in real time.

![A simple desktop browser, connecting to a MongoDB cluster, browsing the collections, and enabling Change Streams. We then see change-stream events shown in the tool. Changes showup as a yellow JSON document which shows the changes as well as the new doc. Inserts show as green, and deletes as red.
](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/Mongo_DB_swift_a13687ce13.gif)

### The code

You can find this code in [CollectionView.swift](https://github.com/mongodb-developer/Swift-Change-Streams/blob/main/MongoDBSwift/Views/CollectionView.swift).

We need a variable to store the change stream (a database cursor)

```swift
@State private var changeStream: ChangeStream<ChangeStreamEvent<BSONDocument>>?
```

as well as one to store the latest change event received from the change stream (this will be used to update the UI):

```swift
@State private var latestChangeEvent: ChangeStreamEvent<BSONDocument>?
```

The `registerChangeStream` function is called whenever the user checks or unchecks the change stream option:

```swift
func registerChangeStream() async {
    // If the view already has an active change stream, close it down
    if let changeStream = changeStream {
        _ = changeStream.kill()
        self.changeStream = nil
    }
    if enabledChangeStreams {
        do {
            let changeStreamOptions = ChangeStreamOptions(fullDocument: .updateLookup)
            changeStream = try await collection?.watch(options: changeStreamOptions)
            _ = changeStream?.forEach({ changeEvent in
                withAnimation {
                    latestChangeEvent = changeEvent
                    showingChangeEvent = true
                    Task {
                        await loadDocs()
                    }
                }
            })
        } catch {
            errorMessage = "Failed to register change stream: \(error.localizedDescription)"
        }
    }
}
```

The function specifies what data it wants to see by creating a `ChangeStreamOptions` structure — you can see the available options in the [Swift driver docs](https://mongodb.github.io/mongo-swift-driver/docs/current/MongoSwift/Structs/ChangeStreamOptions.html). In this app, I specify that I want to receive the complete new document (in addition to the deltas) when a document is updated. Note that the full document is always included for insert and replace operations.

The code then calls `watch` on the current collection. Note that you can also [provide an aggregation pipeline as a parameter](https://www.mongodb.com/docs/manual/changeStreams/#modify-change-stream-output) named `pipeline` when calling `watch`. That pipeline can filter and reshape the events your application receives.

Once the asynchronous watch function completes, the `forEach` loop processes each change event as it's received.

When the loop updates our `latestChangeEvent` variable, the change is automatically propagated to the `ChangeEventView`:

```swift
 ChangeEventView(event: latestChangeEvent)
```

You can see all of the code to display the change event in [`ChangeEventView.swift`](https://github.com/mongodb-developer/Swift-Change-Streams/blob/main/MongoDBSwift/Views/ChangeEventView.swift). I'll show some highlights here.

The view receives the change event from the enclosing view (`CollectionView`):

```swift
let event: ChangeStreamEvent<BSONDocument>
```

The code looks at the `operationType` value in the event to determine what color to use for the window:

```swift
var color: Color {
    switch event.operationType {  
    case .insert:
        return .green
    case .update:
        return .yellow
    case .replace:
        return .orange
    case .delete:
        return .red
    default:
        return .teal
    }
}
```

`documentKey` contains the `_id` value for the document that was changed in the MongoDB collection:

```swift
if let documentKey = event.documentKey {
   ...
        Text(documentKey.toPrettyJSONString())
   ...
    }
}
```

If the database operation was an update, then the delta is stored in `updateDescription`:

```swift
if let updateDescription = event.updateDescription {
    ...
        Text(updateDescription.updatedFields.toPrettyJSONString())
    ...
    }
}
```

The complete document after the change was applied in MongoDB is stored in `fullDocument`:

```swift
if let fullDocument = event.fullDocument {
    ...
        Text(fullDocument.toPrettyJSONString())
    ...
    }
}
```

If the processing of the change events is a critical process, then you need to handle events such as your process crashing. 

The `_id.resumeToken` in the `ChangeStreamEvent` is a token that can be used when starting the process to continue from where you left off. Simply provide this token to the [`resumeAfter`](https://mongodb.github.io/mongo-swift-driver/docs/current/MongoSwift/Structs/ChangeStreamOptions.html#/s:10MongoSwift19ChangeStreamOptionsV11resumeAfterAA11ResumeTokenVSgvp) or [`startAfter`](https://mongodb.github.io/mongo-swift-driver/docs/current/MongoSwift/Structs/ChangeStreamOptions.html#/s:10MongoSwift19ChangeStreamOptionsV10startAfterAA11ResumeTokenVSgvp) options when opening the change stream. Note that this assumes that the events you've missed haven't rotated out of the [Oplog](https://www.mongodb.com/docs/manual/core/replica-set-oplog/).

### Conclusion

Use Change Streams (or Atlas triggers, if you're able) to simplify your code base by decoupling the handling of side-effects from each place in your code that changes data.

After reading this post, you've hopefully realized just how simple it is to create applications that react to data changes using MongoDB Change Streams. Questions? Comments? Head over to our [Developer Community](https://www.mongodb.com/community/forums/tags/c/data/drivers-odms/7/swift) to continue the conversation!

Change streams let you run your own logic when data changes in your MongoDB collections.  This post shows how to consume MongoDB change stream events from your Swift app.

Working with Change Streams from Your Swift Application

A general-purpose, multi-paradigm, compiled programming language. Swift is a powerful programming language for Apple devices.

Swift

Featured

Sync your iOS SwiftUI App with MongoDB Atlas using Atlas Device Sync | Part 2

Sync your iOS SwiftUI App with MongoDB Atlas using Atlas Device Sync | Part 1

Halting Development on MongoDB Swift Driver

All Swift Content