<p align="center">
<a href="https://supabase.io">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/supabase-logo-wordmark--dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/supabase-logo-wordmark--light.svg">
<img alt="Supabase Logo" width="300" src="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/logo-preview.jpg">
</picture>
</a>
<h1 align="center">Supabase Swift SDK</h1>
<p align="center">
<a href="https://supabase.com/docs/guides/getting-started">Guides</a>
·
<a href="https://supabase.com/docs/reference/swift/introduction">Reference Docs</a>
</p>
</p>
<div align="center">
[](https://swiftpackageindex.com/supabase/supabase-swift)
[](https://swiftpackageindex.com/supabase/supabase-swift)
[](https://coveralls.io/github/supabase/supabase-swift?branch=main)
</div>
## Libraries
| Library | Description |
|----------------|----------------------------------------------|
| **Supabase** | Full client — includes all libraries below |
| **Auth** | User authentication and session management |
| **PostgREST** | Query your Postgres database via REST |
| **Realtime** | Subscribe to database changes over WebSocket |
| **Storage** | Manage files and objects |
| **Functions** | Invoke Supabase Edge Functions |
## Quick Start
### Requirements
- iOS 16.0+ / macOS 13.0+ / tvOS 16+ / watchOS 9+ / visionOS 1+
- Xcode 26.0+
- Swift 6.2+
> [!IMPORTANT]
> Check the [Support Policy](#support-policy) to learn when dropping Xcode, Swift, and platform versions will not be considered a **breaking change**.
### Installation
Add `supabase-swift` as a Swift Package Manager dependency:
<!-- x-release-please-start-version -->
```swift
let package = Package(
...
dependencies: [
.package(
url: "https://github.com/supabase/supabase-swift.git",
from: "3.0.0-alpha.1"
),
],
targets: [
.target(
name: "YourTargetName",
dependencies: [
.product(name: "Supabase", package: "supabase-swift")
]
)
]
)
```
<!-- x-release-please-end -->
If you're using Xcode, [use this guide](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app) to add `supabase-swift` to your project. Use `https://github.com/supabase/supabase-swift.git` for the URL when Xcode asks.
You can also add individual libraries (`Auth`, `Functions`, `PostgREST`, `PostgrestMacros`, `Realtime`, `Storage`) instead of the full `Supabase` product.
### Initialize the client
```swift
let client = try SupabaseClient(
supabaseURL: URL(string: "https://xyzcompany.supabase.co")!,
supabaseKey: "your-publishable-key"
)
```
### Initialize with custom options
```swift
let client = try SupabaseClient(
supabaseURL: URL(string: "https://xyzcompany.supabase.co")!,
supabaseKey: "your-publishable-key",
configuration: SupabaseClient.Configuration(
database: .init(
schema: "public"
),
auth: .init(
storage: MyCustomAuthStorage()
),
global: .init(
headers: ["x-my-custom-header": "my-app-name"],
http: .init(transport: URLSessionTransport(session: URLSession.myCustomSession))
)
)
)
```
### Sign in and track the session
```swift
// Sign in. The session is stored for you.
try await client.auth.signIn(email: "user@example.com", password: "secret")
// React to every change: sign-in, sign-out, token refresh, and more.
for await change in client.auth.events() {
print(change.event, change.session?.user.email ?? "signed out")
}
```
In SwiftUI, `AuthModel` (iOS 17, macOS 14, tvOS 17, watchOS 10, visionOS 1 or later) is an
`@Observable` view of the session. Gate your root view on its `status`:
```swift
@State private var auth = AuthModel(client: client.auth)
var body: some View {
switch auth.status {
case .loading: ProgressView()
case .signedOut: SignInView()
case .signedIn: HomeView()
}
}
```
Send every auth link that opens your app to `handleRedirect`. It handles OAuth callbacks,
magic links, and password-reset links, and it is safe to call twice with the same URL. A
password-reset link signs the user in, so check the result to show an "update password" screen:
```swift
.onOpenURL { url in
Task {
if case .signedIn(_, verification: .recovery)? = try await client.handleRedirect(url) {
isPasswordRecovery = true
}
}
}
```
On Apple platforms the session is stored in the Keychain. On iOS, tvOS, watchOS and visionOS it
stays on the device. On Linux, Android and Windows the default storage keeps the session in
memory, so pass your own `AuthStorage` to keep it across launches.
### Invoke an Edge Function
```swift
struct Answer: Decodable { let text: String }
// JSON in, typed JSON out
let answer: Answer = try await client.functions.invoke("ask", body: .json(["prompt": "hi"]))
// Raw response: status, headers, bytes
let response = try await client.functions.invoke("report", options: .init(method: .get))
print(response.status, response.body.count)
```
### Stream a response
```swift
let response = try await client.functions.stream("chat", body: .json(["prompt": "hi"]))
for try await chunk in response.body {
// chunk boundaries follow the network; frame server-sent events yourself
}
```
### Generate database types
`supabase gen types --lang swift` writes `@Table` structs for your schema. It runs the
`supabase-typegen` executable, which ships with each supabase-swift release. The CLI reads your
supabase-swift version from `Package.resolved` and downloads the matching build itself. You need
to install it by hand only when the CLI cannot do that, for example without network access. It then
uses the `supabase-typegen` it finds on your `PATH`. Install the build that matches the
supabase-swift version your project uses:
<!-- x-release-please-start-version -->
```bash
VERSION=3.0.0-alpha.1 # your supabase-swift version
ASSET=supabase-typegen-macos-universal.tar.gz # or supabase-typegen-linux-x86_64.tar.gz
mkdir -p ~/.local/bin
curl -fsSL "https://github.com/supabase/supabase-swift/releases/download/v$VERSION/$ASSET" | tar -xz -C ~/.local/bin
supabase-typegen --version
```
<!-- x-release-please-end -->
Put `~/.local/bin` on your `PATH` if it is not there yet. Then generate the file:
```bash
supabase gen types --lang swift --local > Sources/App/Database.swift
```
On macOS, a binary you download with a browser is quarantined, and Gatekeeper blocks it. `curl`
does not set the quarantine flag. To clear it from a browser download, run
`xattr -d com.apple.quarantine ~/.local/bin/supabase-typegen`.
Additional examples are available in the [Examples](https://github.com/supabase/supabase-swift/tree/main/Examples) directory.
## Support Policy
### Xcode
We only support Xcode versions that are currently eligible for submitting apps to the App Store. Once a specific version of Xcode is no longer supported, its removal from Supabase **won't be treated as a breaking change** and will occur in a minor release.
### Swift
The minimum supported Swift version corresponds to the minor version released with the oldest-supported Xcode version. When a Swift version reaches its end of support, it will be dropped in a **minor release**, and **this won't be considered a breaking change**.
### Platforms
We maintain support for the four latest major versions of each platform, including the current version.
When a platform version is no longer supported, Supabase will drop it in a **minor release**, and **this won't count as a breaking change**. For instance, iOS 14 will no longer be supported after the release of iOS 18, allowing its removal in a minor update.
For macOS, the named yearly releases are treated as major versions for this policy, regardless of their version numbers.
> [!IMPORTANT]
> Android, Linux and Windows work but aren't officially supported, and may stop working in future versions of the library.
## Supabase Service Compatibility
The Supabase Swift SDK only guarantees compatibility with the latest release of each Supabase service, unless a minimum supported version is explicitly listed below.
Older service releases are supported on a best-effort basis, but compatibility is not guaranteed.
If you self-host Supabase, we recommend upgrading your services to their latest releases when upgrading the SDK.
| Service | Library | Server releases | Lowest supported version |
| --------- | -------------------------------- | -------------------------------------------------------------------------- | ------------------------ |
| Auth | [`Auth`](Sources/Auth) | [supabase/auth](https://github.com/supabase/auth/releases) | Latest release |
| Storage | [`Storage`](Sources/Storage) | [supabase/storage](https://github.com/supabase/storage/releases) | Latest release |
| Functions | [`Functions`](Sources/Functions) | [supabase/edge-runtime](https://github.com/supabase/edge-runtime/releases) | Latest release |
| PostgREST | [`PostgREST`](Sources/PostgREST) | [PostgREST/postgrest](https://github.com/PostgREST/postgrest/releases) | Latest release |
| Realtime | [`Realtime`](Sources/Realtime) | [supabase/realtime](https://github.com/supabase/realtime/releases) | Latest release |
## Contributing
We welcome contributions! Please see the steps below.
1. Fork the repo and clone it locally.
2. Create a feature branch (`git checkout -b feature/my-feature`).
3. Make your changes and add tests.
4. Run `./scripts/format.sh` to format Swift code.
5. Run `PLATFORM=IOS XCODEBUILD_ARGUMENT=test ./scripts/xcodebuild.sh` to verify tests pass.
6. Commit using [Conventional Commits](https://www.conventionalcommits.org/) (e.g. `feat(auth): add PKCE support`).
7. Open a pull request against `main`.
## Support
- **Documentation**: [supabase.com/docs/reference/swift](https://supabase.com/docs/reference/swift/introduction)
- **Community**: [GitHub Discussions](https://github.com/supabase/supabase/discussions)
- **Issues**: [GitHub Issues](https://github.com/supabase/supabase-swift/issues)
- **Discord**: [Supabase Discord](https://discord.supabase.com)
## License
This project is licensed under the MIT License — see the [LICENSE](./LICENSE) file for details.
---
<div align="center">
**[Website](https://supabase.com) • [Documentation](https://supabase.com/docs) • [Community](https://github.com/supabase/supabase/discussions) • [Twitter](https://twitter.com/supabase)**
</div>