github supabase/supabase-swift v3.0.0-alpha.1

pre-releaseone hour ago

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.
  • AuthModel gives SwiftUI an @Observable view of the auth status. events() gives a stream of auth changes that drops no events.
  • One OAuth entry point with WebAuthenticationSessionPresenter for SwiftUI.
  • Clearer sign-up and sign-in methods with named results, MFA recovery codes, and passkeys under client.passkeys.
  • getClaims verifies 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 @Function cover embeds, column subsets, aggregates, and RPC.
  • supabase gen types --lang swift generates the @Table structs from your schema.
  • Live queries: stream(_:where:) and the LiveQuery observable 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 HTTPBody stream or a Transferable item, and streamed downloads.
  • Object versioning, bucket lifecycle rules, CDN cache purge, and ImageTransform with gravity and focal point.
  • Vector buckets and analytics buckets (alpha).

Realtime

  • The engine is rebuilt on actors. RealtimeClient and RealtimeChannel are 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, and untrack are async throws. Presence state stays on the channel.
  • Typed Postgres changes with postgresChanges(for:where:).

Functions

  • The module is rebuilt around FunctionBody and FunctionResponse. stream(_:body:options:) returns a streamed response.

Every module

  • One HTTP layer built on swift-http-types. Use ClientTransport and ClientMiddleware to change requests, in place of the fetch: closures.
  • Each module throws one error type (AuthError, PostgrestError, StorageError, FunctionsError, RealtimeError) with a kind, 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 \.supabase environment 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

Don't miss a new supabase-swift release

NewReleases is sending notifications on new releases.