The first alpha of supabase-swift v3 is here. v3 is a major update of the whole SDK. It has many breaking changes. Try it in a branch of your app, not in production. APIs can still change before 3.0.0.
Try it
.package(url: "https://github.com/supabase/supabase-swift", exact: "3.0.0-alpha.1")You need Xcode 26 and Swift 6.2 or later. Your package graph must allow swift-crypto 4.0.0 or later.
Then follow the v3 migration guide. Expect many compile errors at first; most of them are renames. Read each "Silent changes" list too. Those changes compile but behave differently.
Highlights
Auth
- Session handling is rebuilt. Auth refreshes tokens on a schedule, follows the app lifecycle, and signs you out only when a refresh fails and the session has expired.
- A locked Keychain no longer signs the user out.
AuthModelgives SwiftUI an@Observableview of the auth status.events()gives a stream of auth changes that drops no events.- One OAuth entry point with
WebAuthenticationSessionPresenterfor SwiftUI. - Clearer sign-up and sign-in methods with named results, MFA recovery codes, and passkeys under
client.passkeys. getClaimsverifies ES256 and RS256 tokens on the device.
Database (PostgREST)
- An experimental typed query API. Declare tables with
@Table, then filter, order, and select with key paths and closures.@Relationship,@SelectionOf,@Aggregate, and@Functioncover embeds, column subsets, aggregates, and RPC. supabase gen types --lang swiftgenerates the@Tablestructs from your schema.- Live queries:
stream(_:where:)and theLiveQueryobservable keep query results up to date with Realtime. - The typed API is opt-in. Use
@_spi(Experimental) import Supabase.
Storage
- Resumable uploads (TUS) with pause, resume, and cancel (experimental).
- Upload progress, uploads from an
HTTPBodystream or aTransferableitem, and streamed downloads. - Object versioning, bucket lifecycle rules, CDN cache purge, and
ImageTransformwith gravity and focal point. - Vector buckets and analytics buckets (alpha).
Realtime
- The engine is rebuilt on actors.
RealtimeClientandRealtimeChannelare actors. - Status enums tell you why a connection changed. The client checks the socket when the app returns to the foreground and when the network changes.
broadcast,track, anduntrackareasync throws. Presence state stays on the channel.- Typed Postgres changes with
postgresChanges(for:where:).
Functions
- The module is rebuilt around
FunctionBodyandFunctionResponse.stream(_:body:options:)returns a streamed response.
Every module
- One HTTP layer built on swift-http-types. Use
ClientTransportandClientMiddlewareto change requests, in place of thefetch:closures. - Each module throws one error type (
AuthError,PostgrestError,StorageError,FunctionsError,RealtimeError) with akind, HTTP details, and the underlying error. - Logging uses swift-log. Debug builds log warnings and errors by default.
- One retry policy with jittered backoff for Auth, PostgREST, and Storage reads.
- Request timeouts are set per client and per call.
- Client initializers throw on an invalid configuration.
- All APIs that were deprecated in v2 are removed.
- A SwiftUI
\.supabaseenvironment value.
Tell us what you think
Your feedback shapes the final API. Open a v3 alpha feedback issue for bugs, API you find hard to use, or migration problems.
v2 still gets fixes on the release/v2 branch.
Full changelog: v2.55.7...v3.0.0-alpha.1