> ## Documentation Index > Fetch the complete documentation index at: https://powersync-sync-streams-nav.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Swift SDK > Use PowerSync in Swift apps. ```text Build with AI icon="sparkles" wrap theme={null} Install the PowerSync Agent Skills with: npx skills add powersync-ja/agent-skills. Then follow the skills to onboard this project to PowerSync using the Swift SDK. ``` Refer to the `powersync-swift` repo on GitHub Full API reference for the SDK Gallery of example projects/demo apps built with PowerSync and Swift Changelog for the SDK Up to v1.13, the Swift SDK wrapped a PowerSync Kotlin XCFramework behind Swift protocols. From v1.14, the SDK has no Kotlin dependency. It is implemented natively in Swift and uses our [Rust core](https://github.com/powersync-ja/powersync-sqlite-core) for the sync protocol and SQLite extension. ## SDK Features * **Real-time streaming of database changes**: Changes made by one user are instantly streamed to all other users with access to that data. This keeps clients automatically in sync without manual polling or refresh logic. * **Direct access to a local SQLite database**: Data is stored locally, so apps can read and write instantly without network calls. This enables offline support and faster user interactions. * **Asynchronous background execution**: The SDK performs database operations in the background to avoid blocking the application’s main thread. This means that apps stay responsive, even during heavy data activity. * **Query subscriptions for live updates**: The SDK supports query subscriptions that automatically push real-time updates to client applications as data changes, keeping your UI reactive and up to date. * **Automatic schema management**: PowerSync syncs schemaless data and applies a client-defined schema using SQLite views. This architecture means that PowerSync SDKs handle schema changes without explicit migrations on the client side. ## Installation You can add the PowerSync Swift package to your project using either `Package.swift` or Xcode: ```swift theme={null} let package = Package( //... dependencies: [ //... .package( url: "https://github.com/powersync-ja/powersync-swift", exact: "" ), ], targets: [ .target( name: "YourTargetName", dependencies: [ .product( name: "PowerSync", package: "powersync-swift" ) ] ) ] ) ``` 1. Follow [this guide](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app#Add-a-package-dependency) to add a package to your project. 2. Use `https://github.com/powersync-ja/powersync-swift.git` as the URL 3. Include the exact version (e.g., `1.0.x`) ## Getting Started **Prerequisites:** Before you start, connect your source database to the PowerSync Service and deploy Sync Streams. These are steps 1-4 in the [Setup Guide](/intro/setup-guide). ### 1. Define the Client-Side Schema The client-side schema defines the tables and columns of the SQLite database that the PowerSync client SDK manages and that your app reads from and writes to. It is usually derived from your backend database schema and your [Sync Streams](/sync/streams/overview), and it can also include [local-only tables](/client-sdks/advanced/local-only-usage). You apply the schema when you instantiate the database in the next step. Schema migrations are not required. The SDK syncs schemaless data and applies the schema to that data with SQLite views. The exception is [raw tables](/client-sdks/advanced/raw-tables), which you create and migrate yourself. **Generate schema automatically** In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance and click the **Connect** button in the top bar to generate the client-side schema in your preferred language. The schema is generated from your Sync Streams. The [CLI](/tools/cli) offers the same function. The generated schema does not include an `id` column. The client SDK creates an `id` column of type `text` automatically, so you do not need to declare it. See [Client ID](/sync/advanced/client-id) for details. The available column types are `text`, `integer`, and `real`. These should match the values produced by your Sync Streams. If a value does not match, it is cast automatically. For details on how source database types map to SQLite types, see [Types](/sync/types). **Example:** ```swift theme={null} import Foundation import PowerSync let LISTS_TABLE = "lists" let TODOS_TABLE = "todos" let lists = Table( name: LISTS_TABLE, columns: [ // ID column is automatically included .text("name"), .text("created_at"), .text("owner_id") ] ) let todos = Table( name: TODOS_TABLE, // ID column is automatically included columns: [ .text("list_id"), .text("photo_id"), .text("description"), // 0 or 1 to represent false or true .integer("completed"), .text("created_at"), .text("completed_at"), .text("created_by"), .text("completed_by") ], indexes: [ Index( name: "list_id", columns: [ IndexedColumn.ascending("list_id") ] ) ] ) let AppSchema = Schema(lists, todos) ``` You do not need to declare an `id` column. PowerSync creates it automatically. ### 2. Instantiate the PowerSync Database Next, instantiate the PowerSync database. PowerSync streams changes from your backend source database into the client-side SQLite database, based on your Sync Streams. Your app reads from and writes to this local database whether the user is online or offline. **Example:** ```swift theme={null} let schema = AppSchema // Comes from the AppSchema defined above let db = PowerSyncDatabase( schema: schema, dbFilename: "powersync-swift.sqlite" ) ``` ### 3. Integrate with Your Backend The backend connector connects the PowerSync client SDK to your application backend. The SDK uses it to: 1. Get an auth token to connect to the PowerSync instance. 2. Upload client-side writes to your backend API. The SDK places every write to the SQLite database in an upload queue and uploads the queue to your backend when the user is connected. Your backend then applies the changes to the source database. The connector must implement two methods: 1. `PowerSyncBackendConnectorProtocol.fetchCredentials` - The SDK calls this method to get authentication credentials. It caches the credentials and calls the method again only when needed, for example on the first connection or when the token is near expiry. See [When `fetchCredentials()` is Called](/configuration/app-backend/client-side-integration#when-fetchcredentials-is-called) for details and [Authentication Setup](/configuration/auth/overview) for how to generate credentials. 2. `PowerSyncBackendConnectorProtocol.uploadData` - The SDK calls this method whenever it has client-side writes to upload to your backend API. Implement how those writes are processed and uploaded. See [When `uploadData()` is Called](/configuration/app-backend/client-side-integration#when-uploaddata-is-called) for triggers, throttling, and retry behavior, and [Writing Client Changes](/handling-writes/writing-client-changes) for the app backend implementation. **Example:** ```swift theme={null} import PowerSync final class MyConnector: PowerSyncBackendConnectorProtocol { func fetchCredentials() async throws -> PowerSyncCredentials? { // implement fetchCredentials to obtain the necessary credentials to connect to your backend // See an example implementation in https://github.com/powersync-ja/powersync-swift/blob/main/Demo/PowerSyncExample/PowerSync/SupabaseConnector.swift return PowerSyncCredentials( endpoint: "Your PowerSync instance URL or self-hosted endpoint", // Use a development token (see Authentication Setup https://docs.powersync.com/configuration/auth/development-tokens) // to get up and running quickly token: "An authentication token" ) } func uploadData(database: PowerSyncDatabaseProtocol) async throws { // Implement uploadData to send local changes to your backend service // You can omit this method if you only want to sync data from the server to the client // See an example implementation under Usage Examples (sub-page) // See https://docs.powersync.com/handling-writes/writing-client-changes for considerations. } } ``` Connect the PowerSync database to sync data with your backend: ```swift theme={null} let connector = MyConnector() try await db.connect(connector: connector) ``` This section assumes that you use PowerSync to sync your backend source database with SQLite in your app. To manage a local SQLite database without sync, instantiate the PowerSync database without calling `connect()` and see the [Local-Only](/client-sdks/advanced/local-only-usage) guide. ### 4. Subscribe to Sync Streams Streams defined with `auto_subscribe: true` start syncing as soon as the client connects. For all other streams, your app must subscribe before their data downloads. The basic pattern is: subscribe to a stream, wait for its data to sync, then unsubscribe when the data is no longer needed. ```swift theme={null} // Subscribe to a stream with parameters let sub = try await db.syncStream(name: "list_todos", params: ["list_id": .string("abc123")]).subscribe() // Wait for the initial data to sync try await sub.waitForFirstSync() // The stream's rows are now in the local SQLite database. // TODO: Read the todos for this list with a local query. // When the data is no longer needed try await sub.unsubscribe() ``` After you unsubscribe, the synced data stays in the local database for the stream's time-to-live (TTL), which is 24 hours by default. If the app subscribes again within that time, the data is already available. See [Client-Side Usage](/sync/streams/client-usage) for framework hooks, per-subscription sync status, custom TTLs, priority overrides, and connection parameters. ## Using PowerSync: CRUD Functions Once the PowerSync database is connected and your streams have synced, the data is in the local SQLite database. The most commonly used CRUD functions to interact with your SQLite data are: * [PowerSyncDatabase.get](/client-sdks/reference/swift#fetching-a-single-item-powersync-get-/-powersync-getoptional) - get (`SELECT`) a single row from a table. * [PowerSyncDatabase.getOptional](/client-sdks/reference/swift#fetching-a-single-item-powersync-get-/-powersync-getoptional) - get (`SELECT`) a single row from a table and return `nil` if not found. * [PowerSyncDatabase.getAll](/client-sdks/reference/swift#querying-items-powersync-getall) - get (`SELECT`) a set of rows from a table. * [PowerSyncDatabase.watch](/client-sdks/reference/swift#watching-queries-powersync-watch) - execute a read query every time a dependent table changes. * [PowerSyncDatabase.execute](/client-sdks/reference/swift#mutations-powersync-execute) - execute a write (`INSERT`/`UPDATE`/`DELETE`) query. ### Fetching a Single Item (PowerSync.get / PowerSync.getOptional) The `get` method executes a read-only (SELECT) query and returns a single result. It throws an exception if no result is found. Use `getOptional` to return a single optional result (returns `nil` if no result is found). ```swift theme={null} // Find a list by ID func getList(_ id: String) async throws -> ListContent { try await db.get( sql: "SELECT * FROM \(LISTS_TABLE) WHERE id = ?", parameters: [id], mapper: { cursor in ListContent( id: try cursor.getString(name: "id")!, name: try cursor.getString(name: "name")!, createdAt: try cursor.getString(name: "created_at")!, ownerId: try cursor.getString(name: "owner_id")! ) } ) } ``` ### Querying Items (PowerSync.getAll) The `getAll` method executes a read-only (SELECT) query and returns a set of rows. ```swift theme={null} // Get all lists func getLists() async throws -> [ListContent] { try await db.getAll( sql: "SELECT * FROM \(LISTS_TABLE)", parameters: [], mapper: { cursor in ListContent( id: try cursor.getString(name: "id")!, name: try cursor.getString(name: "name")!, createdAt: try cursor.getString(name: "created_at")!, ownerId: try cursor.getString(name: "owner_id")! ) } ) } ``` ### Watching Queries (PowerSync.watch) The `watch` method executes a read query whenever a change to a dependent table is made. ```swift theme={null} func watchPendingLists() throws -> AsyncThrowingStream<[ListContent], Error> { try db.watch( sql: "SELECT * FROM lists WHERE state = ?", parameters: ["pending"], ) { cursor in try ListContent( id: cursor.getString(name: "id"), name: cursor.getString(name: "name"), ) } } ``` ### Mutations (PowerSync.execute) The `execute` method executes a write query (INSERT, UPDATE, DELETE) and returns the results (if any). ```swift theme={null} func insertTodo(_ todo: NewTodo, _ listId: String) async throws { try await db.execute( sql: "INSERT INTO \(TODOS_TABLE) (id, created_at, created_by, description, list_id, completed) VALUES (uuid(), datetime(), ?, ?, ?, ?)", parameters: [connector.currentUserID, todo.description, listId, todo.isComplete] ) } func updateTodo(_ todo: Todo) async throws { try await db.execute( sql: "UPDATE \(TODOS_TABLE) SET description = ?, completed = ?, completed_at = datetime(), completed_by = ? WHERE id = ?", parameters: [todo.description, todo.isComplete, connector.currentUserID, todo.id] ) } func deleteTodo(id: String) async throws { try await db.writeTransaction(callback: { transaction in _ = try transaction.execute( sql: "DELETE FROM \(TODOS_TABLE) WHERE id = ?", parameters: [id] ) }) } ``` ## Configure Logging You can supply your own logger. It must conform to the [LoggerProtocol](https://powersync-ja.github.io/powersync-swift/documentation/powersync/loggerprotocol): ```swift theme={null} let logger = DefaultLogger(minSeverity: .debug) let db = PowerSyncDatabase( schema: schema, dbFilename: "powersync-swift.sqlite", logger: logger ) ``` The `DefaultLogger` supports the following severity levels: `.debug`, `.info`, `.warn`, `.error`. ## App Groups and App Extensions By default, the Swift SDK stores databases in `applicationSupportDirectory`. If you want to share local databases between multiple apps in an app group, provide an absolute path (starting with `/`) as `dbFilename` when calling `PowerSyncDatabase`. The path should point towards a file in the app group's [shared container](https://developer.apple.com/documentation/xcode/configuring-app-groups#Access-an-app-groups-shared-container). Support for app groups and extensions was added in version 1.15, and is experimental. With app groups and extensions, multiple processes might access the database at the same time. SQLite uses shared memory and file locking to make this safe, but there are still concerns that aren't relevant when the database is only accessed from a single context: 1. Concurrent writes to the database are not allowed. Within a process, the PowerSync SDK uses Swift actors to schedule writes. Outside of SQLite using file locks, there is no additional coordination for multi-process access. * Consider using [`PRAGMA busy_timeout`](https://sqlite.org/pragma.html#pragma_busy_timeout) to make SQLite wait longer. * Be ready to handle `SQLITE_BUSY` errors if multiple processes attempt to write to the database. 2. Do not call `connect()` in more than one process: If two processes attempt to connect to the PowerSync Service for the same database, this wastes resources and can also lead to concurrency issues. If you share databases with extensions or app groups, ensure there is only one context responsible for connecting. 3. Avoid multiple versions of the Swift SDK: While the SQLite file format is stable and databases can safely be accessed from multiple processes using their own SQLite version, the PowerSync SDK is not designed with this in mind. In particular, opening the same database file from multiple processes can cause PowerSync-internal migrations to get reverted. This is not a concern for app extensions released as part of the same bundle, but something to be aware of for app groups. ## Custom HTTP Clients and Headers PowerSync uses a streaming HTTP response to connect to the PowerSync Service. By default, the Swift SDK uses `URLSession.shared` to run HTTP requests. You can provide a custom `URLSession` as a sync option. This can be used to add custom HTTP headers, for example: ```swift theme={null} let config = URLSessionConfiguration.ephemeral config.httpAdditionalHeaders = ["x-my-custom-header": "example"] let session = URLSession(configuration: config) try await db.connect( connector: connector, options: ConnectOptions( clientConfiguration: SyncClientConfiguration( urlSession: session ) ) ) ``` For more information, see Apple's documentation on [`URLSessionConfiguration`](https://developer.apple.com/documentation/foundation/urlsessionconfiguration). ## Additional Usage Examples For more usage examples including accessing connection status, monitoring sync progress, and waiting for initial sync, see the [Usage Examples](/client-sdks/usage-examples) page. ## ORM Support PowerSync officially supports the [GRDB](/client-sdks/orms/swift/grdb) library for Swift. Additionally, [Asier G. Morato](https://github.com/asiergmorato) contributed a [Swift Data integration](https://github.com/powersync-community/swift-data) for PowerSync, allowing Swift Data models to be persisted and synced through a PowerSync database. The integration is community-owned and not officially supported by PowerSync. ## Troubleshooting See [Troubleshooting](/debugging/troubleshooting) for pointers to debug common issues. ## Supported Platforms See [Supported Platforms -> Swift SDK](/resources/supported-platforms#swift). ## Upgrading the SDK Update the version number in `Package.swift` or via Xcode Package Dependencies as documented in the installation instructions: [Installation](/client-sdks/reference/swift#installation). **Upgrading to v1.14**: This release removes the internal Kotlin dependency and re-implements the SQLite connection pool logic natively in Swift. The public API is unchanged, but the internals are a full rewrite. We recommend testing queries in your app after upgrading to this version.