Supabase Swift

https://github.com/supabase/supabase-swift
Admin
A Swift client library for interacting with Supabase, mirroring the design of supabase-js, enabling...
Tokens:97,688
Snippets:665
Trust Score:10
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start Local Supabase Instance

Source: https://github.com/supabase/supabase-swift/blob/main/Examples/README.md

Navigate to the project root and start the local Supabase development environment using the experimental native stack.

```bash
# Navigate to the root directory
cd /path/to/supabase-swift

# Start Supabase local development with the CLI's experimental native stack (macOS, no Docker)
export SUPABASE_EXPERIMENTAL_STACK=1
supabase start --runtime native
```

--------------------------------

### Install supabase-typegen binary manually

Source: https://github.com/supabase/supabase-swift/blob/main/AGENTS.md

Downloads and installs the supabase-typegen binary from the GitHub release. Set VERSION to the supabase-swift version the project uses and ASSET to the appropriate archive for your platform. The command extracts the binary to ~/.local/bin and then verifies the installation with --version.

```bash
VERSION=2.55.1 # the supabase-swift version the project uses
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
```

--------------------------------

### Supabase: Before and After migration example

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the migration for `SupabaseClient.database` and `SupabaseClient.realtime` removal. Use `supabase.from(...)` directly and `supabase.realtimeV2.connect()`.

```swift
// Before
try await supabase.database.from("users").select().execute()
supabase.realtime.connect()

// After
try await supabase.from("users").select().execute()
supabase.realtimeV2.connect()
```

--------------------------------

### Spell Check Setup and Run

Source: https://github.com/supabase/supabase-swift/blob/main/AGENTS.md

One-time setup for cSpell and running the spell-check script. Re-run npm ci only when tools/node/package-lock.json changes.

```bash
npm ci --prefix tools/node   # one-time setup (re-run only when tools/node/package-lock.json changes)
./scripts/spell-check.sh     # cspell - Swift and Markdown sources
```

--------------------------------

### Install supabase-typegen and generate database types

Source: https://github.com/supabase/supabase-swift/blob/main/README.md

Downloads and installs the supabase-typegen executable matching your supabase-swift version, then generates @Table structs for your schema. The CLI reads your supabase-swift version from Package.resolved and downloads the matching build itself; install by hand only when the CLI cannot (e.g., without network access). On macOS, browser downloads are quarantined; use curl or clear the quarantine flag with xattr -d com.apple.quarantine.

```bash
VERSION=2.55.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
```

```bash
supabase gen types --lang swift --local > Sources/App/Database.swift
```

--------------------------------

### Storage: Before and After migration example

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the migration for Storage API changes: `BucketOptions.public` becomes `isPublic`, and `download: Bool` becomes `download: DownloadBehavior` with `.withOriginalName`.

```swift
// Before
let bucket = try await storage.createBucket("avatars", options: .init(public: true))
let url = try await storage.from("avatars").createSignedURL(path: "a.png", expiresIn: 60, download: true)

// After
let bucket = try await storage.createBucket("avatars", options: .init(isPublic: true))
let url = try await storage.from("avatars").createSignedURL(
  path: "a.png", expiresIn: 60, download: .withOriginalName
)
```

--------------------------------

### setHeader(_:forKey:) before and after migration

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the old in-place mutation behavior and the new value-returning behavior. The before example discards the result, which is now a no-op; the after example captures the returned value to preserve the header.

```swift
// Before: mutated the instance in place; the extra header applied to every later request.
storage.from("avatars").setHeader("x-custom-header", forKey: "X-Custom-Header")
try await storage.from("avatars").upload(...) // included the header

// After: returns a new value; the statement above is now a no-op, and the header is
// lost by the next line unless you capture and reuse the returned value.
let avatars = storage.from("avatars").setHeader("x-custom-header", forKey: "X-Custom-Header")
try await avatars.upload(...) // includes the header

// Or chain directly:
try await storage.from("avatars")
  .setHeader("x-custom-header", forKey: "X-Custom-Header")
  .upload(...)
```

--------------------------------

### Start local Supabase native stack on macOS

Source: https://github.com/supabase/supabase-swift/blob/main/AGENTS.md

Sets the SUPABASE_EXPERIMENTAL_STACK environment variable and starts Supabase with the native runtime. This is required for local development and integration tests on macOS. The native stack fails if an older Docker stack is running on the same ports.

```bash
export SUPABASE_EXPERIMENTAL_STACK=1
supabase start --runtime native
```

--------------------------------

### Run integration tests on macOS

Source: https://github.com/supabase/supabase-swift/blob/main/AGENTS.md

Runs the integration test suite on macOS with the required environment variables and Swift flags. The flags enable cross-import overlays for swift-snapshot-testing and require macOS 14. The --eager flag starts services before supabase start returns. The test filter skips verifyOTPForSecureEmailChange and runs tests in parallel.

```bash
export INTEGRATION_TESTS=1  # the suites skip themselves without it
export SUPABASE_EXPERIMENTAL_STACK=1
SWIFT_FLAGS="--triple arm64-apple-macosx14.0 -Xswiftc -Xfrontend -Xswiftc -enable-cross-import-overlays"
cd Tests/IntegrationTests
supabase start --runtime native --eager
cd ../..
swift test $SWIFT_FLAGS --filter IntegrationTests --skip verifyOTPForSecureEmailChange --no-parallel
cd Tests/IntegrationTests
supabase stop
```

--------------------------------

### Sign up with phone and password using curl

Source: https://github.com/supabase/supabase-swift/blob/main/Tests/AuthTests/__Snapshots__/RequestsTests/signUpWithPhoneAndPassword.1.txt

Example curl command for signing up with phone and password using the Supabase GoTrue API. It includes required headers (Apikey, Content-Type, X-Client-Info, X-Supabase-Api-Version) and a JSON payload with channel, custom data, captcha token, password, and phone. The endpoint is http://localhost:54321/auth/v1/signup.

```bash
curl \
	--request POST \
	--header "Apikey: dummy.api.key" \
	--header "Content-Type: application/json" \
	--header "X-Client-Info: gotrue-swift/x.y.z" \
	--header "X-Supabase-Api-Version: 2024-01-01" \
	--data "{\"channel\":\"sms\",\"data\":{\"custom_key\":\"custom_value\"},\"gotrue_meta_security\":{\"captcha_token\":\"dummy-captcha\"},\"password\":\"the.pass\",\"phone\":\"+1 202-918-2132\"}" \
	"http://localhost:54321/auth/v1/signup"
```

--------------------------------

### Swift Testing example test structure

Source: https://github.com/supabase/supabase-swift/blob/main/AGENTS.md

Shows the standard structure for a test suite using Swift Testing, with @Suite, @Test, and #expect assertions. Use this as a template for new test files.

```swift
import Testing
@testable import ModuleName

@Suite
struct FeatureTests {
  @Test
  func featureBehavior() {
    // Arrange
    let input = "test"

    // Act
    let result = feature(input)

    // Assert
    #expect(result == expected)
  }
}
```

--------------------------------

### Manually encode RealtimeMessageV2 fields to JSON

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Before and after examples for encoding a RealtimeMessageV2. The Codable conformance is removed; you must build a JSONObject from the message fields. The after example shows constructing the JSON object with event, join_ref, payload, ref, and topic.

```swift
// Before
let data = try JSONEncoder().encode(message)

// After
let json: JSONObject = [
  "event": .string(message.event),
  "join_ref": message.joinRef.map(JSONValue.string) ?? .null,
  "payload": .object(message.payload),
  "ref": message.ref.map(JSONValue.string) ?? .null,
  "topic": .string(message.topic),
]
let data = try JSONEncoder().encode(json)
```

--------------------------------

### Run verifyOTPForSecureEmailChange integration test

Source: https://github.com/supabase/supabase-swift/blob/main/AGENTS.md

Runs the verifyOTPForSecureEmailChange test against a separate minimal Supabase project. This test requires auth.email.enable_confirmations = true, which conflicts with the main integration suite. The commands start the second project, run the test, and stop it.

```bash
cd Tests/IntegrationTests/supabase-secure-email-change
supabase start --runtime native --eager
cd ../../..
swift test $SWIFT_FLAGS --filter verifyOTPForSecureEmailChange --no-parallel
cd Tests/IntegrationTests/supabase-secure-email-change
supabase stop
```

--------------------------------

### Per-call encoder and decoder overrides for insert and execute

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows how to pass a custom encoder to insert and a custom decoder to execute, overriding the client's default configuration for that single call. The encoder example uses a snake_case key strategy, and the decoder example uses a custom date strategy. These calls compile unchanged when the new arguments are omitted.

```swift
// Encode this one insert with a different key strategy than the client default
try await client.from("todos")
  .insert(todo, encoder: mySnakeCaseEncoder)
  .execute()

// Decode this one response with a different date strategy than the client default
let todos: [Todo] = try await client.from("todos")
  .select()
  .execute(decoder: myCustomDecoder)
  .value
```

--------------------------------

### Implement custom OSLog handler for Logging.Logger

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows how to install a custom LogHandler (MyOSLogHandler) as the backing handler for a Logger to replicate OSLogSupabaseLogger's OSLog integration.

```swift
logger: Logger(label: "myapp") { MyOSLogHandler(label: $0) }
```

--------------------------------

### Enroll WebAuthn Factor with curl

Source: https://github.com/supabase/supabase-swift/blob/main/Tests/AuthTests/__Snapshots__/RequestsTests/mfaEnrollWebAuthn.1.txt

Use this curl command to enroll a WebAuthn factor. It sends a POST request to the /auth/v1/factors endpoint with the required headers (Apikey, Authorization, Content-Type, X-Client-Info, X-Supabase-Api-Version) and a JSON body specifying factor_type as "webauthn" and a friendly_name. The example uses dummy credentials and a localhost URL.

```bash
curl \
	--request POST \
	--header "Apikey: dummy.api.key" \
	--header "Authorization: Bearer accesstoken" \
	--header "Content-Type: application/json" \
	--header "X-Client-Info: gotrue-swift/x.y.z" \
	--header "X-Supabase-Api-Version: 2024-01-01" \
	--data "{\"factor_type\":\"webauthn\",\"friendly_name\":\"My Passkey\"}" \
	"http://localhost:54321/auth/v1/factors"
```

--------------------------------

### Before and after: update without .select() vs with .select()

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the previous behavior where update returned rows by default, and the new behavior where you must chain .select() to get rows back. The first block is the old code, the second is the new code.

```swift
// Before — rows came back even without .select()
let updated: [Todo] = try await client
  .from("todos")
  .update(["done": true])
  .eq("id", value: 1)
  .execute()
  .value
```

```swift
// After — chain .select() to get rows back, as insert already required
let updated: [Todo] = try await client
  .from("todos")
  .update(["done": true])
  .eq("id", value: 1)
  .select()
  .execute()
  .value
```

--------------------------------

### Handling oauthFlowFailed in signInWithOAuth

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the before and after for handling OAuth sign-in failures. Before, the app would die on a missing redirect URL; after, you can catch the AuthError with kind == .oauthFlowFailed and present a setup error.

```swift
// Before — no way to handle this; the app died on the missing redirect URL
let session = try await supabase.auth.signInWithOAuth(provider: .github)

// After
do {
  let session = try await supabase.auth.signInWithOAuth(provider: .github)
} catch let error as AuthError where error.kind == .oauthFlowFailed {
  presentSetupError(error.message)
}
```

--------------------------------

### Remove vsn option from RealtimeClientOptions

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Before and after examples for initializing SupabaseClient without the vsn option. The vsn parameter and RealtimeProtocolVersion enum are removed; the socket URL always uses vsn=2.0.0. Passing vsn: causes a compile error.

```swift
// Before
let client = SupabaseClient(
  supabaseURL: url, supabaseKey: key,
  options: .init(realtime: RealtimeClientOptions(vsn: .v2))
)

// After
let client = SupabaseClient(
  supabaseURL: url, supabaseKey: key,
  options: .init(realtime: RealtimeClientOptions())
)
```

--------------------------------

### curl request to /auth/v1/user with required headers

Source: https://github.com/supabase/supabase-swift/blob/main/Tests/AuthTests/__Snapshots__/RequestsTests/sessionFromURL.1.txt

Use this curl command to test the Supabase Auth user endpoint. It requires the Apikey and Authorization headers, plus X-Client-Info and X-Supabase-Api-Version. The example uses dummy values and a local server URL.

```bash
curl \
	--header "Apikey: dummy.api.key" \
	--header "Authorization: bearer accesstoken" \
	--header "X-Client-Info: gotrue-swift/x.y.z" \
	--header "X-Supabase-Api-Version: 2024-01-01" \
	"http://localhost:54321/auth/v1/user"
```

--------------------------------

### Handle StorageError with HTTPResponse status and headers

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Before/after example for catching storage errors. The after version uses StorageError with optional response, HTTPResponse.Status.code, and HTTPFields subscripting. Note that HTTPResponse has no URL, so log the requested URL instead.

```swift
// Before
do {
  try await supabase.storage.from("avatars").remove(paths: ["a.png"])
} catch let error as HTTPError {
  print(error.response.statusCode)
  print(error.response.allHeaderFields["Content-Type"] as? String)
  print(error.response.url)
}

// After
do {
  try await supabase.storage.from("avatars").remove(paths: ["a.png"])
} catch let error as StorageError {
  print(error.response?.statusCode)
  print(error.response?.headers[.contentType])
  // No URL on the response; log the URL you requested instead.
}
```

--------------------------------

### Replace PostgrestBuilder with any PostgrestExecutableBuilder

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the before and after for a function that returns a Postgrest builder. The old code used the removed PostgrestBuilder type; the new code uses the any PostgrestExecutableBuilder protocol. Also includes a comment about the @discardableResult limitation and an example call that binds the result to avoid an unused result warning.

```swift
// Before
func makeUsersQuery(_ client: PostgrestClient) -> PostgrestBuilder {
  client.from("users").select()
}

// After
func makeUsersQuery(_ client: PostgrestClient) -> any PostgrestExecutableBuilder {
  client.from("users").select()
}

// `PostgrestExecutableBuilder.execute(options:)` is a protocol requirement, so it can't carry
// `@discardableResult` — bind or use the result to avoid an "unused result" warning.
_ = try await makeUsersQuery(client).execute(options: FetchOptions())
```

--------------------------------

### RequestCounter middleware and execute call showing per-attempt interception

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

A ClientMiddleware that increments a counter on each intercept. The example shows that before the change, one intercept ran per execute() call, but after, it runs once per attempt, up to four times for a PostgREST GET that keeps returning 503.

```swift
// A middleware passed through `SupabaseClientOptions.GlobalOptions.http`:
struct RequestCounter: ClientMiddleware {
  let count: LockIsolated<Int>
  func intercept(
    _ request: HTTPRequest, body: HTTPBody?,
    next: nonisolated(nonsending) @Sendable (HTTPRequest, HTTPBody?) async throws
      -> (HTTPResponse, HTTPBody?)
  ) async throws -> (HTTPResponse, HTTPBody?) {
    count.withValue { $0 += 1 }
    return try await next(request, body)
  }
}

// Before — one `intercept` per `execute()`, even when PostgREST retried the request.
// After — one `intercept` per attempt, up to four for a PostgREST GET that keeps getting a 503.
try await supabase.from("todos").select().execute()
```

--------------------------------

### Run the OpenTelemetry demo

Source: https://github.com/supabase/supabase-swift/blob/main/Examples/OpenTelemetryDemo/README.md

Run the demo from the Examples/OpenTelemetryDemo directory. No live Supabase project is needed; requests are intercepted locally.

```sh
cd Examples/OpenTelemetryDemo
swift run
```

--------------------------------

### Initialize SupabaseClient with options

Source: https://github.com/supabase/supabase-swift/blob/main/AGENTS.md

Shows the option builder pattern for configuring SupabaseClient with auth, db, and global options. Use this when creating a client with custom settings.

```swift
SupabaseClient(
  supabaseURL: url,
  supabaseKey: key,
  options: SupabaseClientOptions(
    auth: .init(...),
    db: .init(...),
    global: .init(...)
  )
)
```

--------------------------------

### curl RPC GET with params

Source: https://github.com/supabase/supabase-swift/blob/main/Tests/PostgRESTTests/__Snapshots__/BuildURLRequestTests/testBuildRequest.rpc-call-with-get-and-params.txt

Use this curl command to call the get_array_element RPC function with GET, passing array and index as query parameters. The array parameter is URL-encoded.

```bash
curl \
	--header "Accept: application/json" \
	--header "Content-Type: application/json" \
	--header "X-Client-Info: postgrest-swift/x.y.z" \
	"https://example.supabase.co/rpc/get_array_element?array=%7B37,420,64%7D&index=2"
```

--------------------------------

### FunctionsClient/init(configuration:)

Source: https://github.com/supabase/supabase-swift/blob/main/Sources/Functions/Functions.docc/Standalone.md

Initializes a FunctionsClient with a configuration. Only the URL is required. The initializer traps if the URL has no host.

```APIDOC
## FunctionsClient/init(configuration:)

### Description
Initializes a FunctionsClient with a configuration. Only the URL is required. The initializer traps if the URL has no host.

### Parameters
#### Configuration
- **url** (URL) - Required - The base URL for the Functions service.
- **headers** ([HTTPField.Name: String]) - Optional - Headers to include with every request. Must not carry `Authorization`.
- **region** (Region) - Optional - The region for the Functions service.
- **accessToken** (() async throws -> String?) - Optional - A closure that returns the access token for each request. Called for every request.
- **http** (HTTPClientConfiguration) - Optional - The HTTP client configuration including transport and middlewares.
- **logger** (Logger) - Optional - A swift-log Logger used by the client.
- **decoder** (JSONDecoder) - Optional - The decoder used for JSON-decoding calls.

### Example
```swift
let functions = FunctionsClient(
  configuration: .init(
    url: URL(string: "https://<ref>.supabase.co/functions/v1")!,
    headers: [HTTPField.Name("apikey")!: "sb_publishable_…"],
    region: .usEast1,
    accessToken: { await tokenStore.current }
  )
)
```
```

--------------------------------

### Initialize a SupabaseClient

Source: https://github.com/supabase/supabase-swift/blob/main/README.md

Initializes a SupabaseClient with a supabase URL and publishable key. Replace the placeholder URL and key with your own project credentials.

```swift
let client = SupabaseClient(
    supabaseURL: URL(string: "https://xyzcompany.supabase.co")!,
    supabaseKey: "your-publishable-key"
)
```

--------------------------------

### Swift Component: CodeExample usage

Source: https://github.com/supabase/supabase-swift/blob/main/Examples/README.md

Demonstrates how to use the CodeExample component to display Supabase API calls.

```swift
CodeExample(
  code: """
    // Create a todo
    try await supabase
      .from("todos")
      .insert(Todo(description: "Learn Supabase"))
      .execute()
    """
)
```

--------------------------------

### Before and After: RealtimeClientOptions fetch to http

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the v2 `fetch:` and v3 `http:` for RealtimeClientOptions.

```swift
// Before
let options = RealtimeClientOptions(fetch: { try await session.data(for: $0) })
```

```swift
// After
let options = RealtimeClientOptions(http: .init(transport: URLSessionTransport(session: session)))
```

--------------------------------

### curl GET request to RPC endpoint

Source: https://github.com/supabase/supabase-swift/blob/main/Tests/PostgRESTTests/__Snapshots__/BuildURLRequestTests/testBuildRequest.rpc-call-with-get.txt

Use this curl command to invoke an RPC function via GET. It includes the required Accept and Content-Type headers, plus the X-Client-Info header with the postgrest-swift client identifier. The URL points to the 'sum' RPC function on the Supabase instance.

```bash
curl \
	--header "Accept: application/json" \
	--header "Content-Type: application/json" \
	--header "X-Client-Info: postgrest-swift/x.y.z" \
	"https://example.supabase.co/rpc/sum"
```

--------------------------------

### After (Windows): Implement AuthLocalStorage and pass storage

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the required migration: implement AuthLocalStorage with store, retrieve, and remove methods, then pass it via options.auth.storage when creating SupabaseClient. No reference implementation is provided; implement against your own storage mechanism.

```swift
// After (Windows)
struct MyLocalStorage: AuthLocalStorage {
  func store(key: String, value: Data) throws { /* ... */ }
  func retrieve(key: String) throws -> Data? { /* ... */ }
  func remove(key: String) throws { /* ... */ }
}

let client = SupabaseClient(
  supabaseURL: url,
  supabaseKey: key,
  options: .init(auth: .init(storage: MyLocalStorage()))
)
```

--------------------------------

### curl request for passkey registration options

Source: https://github.com/supabase/supabase-swift/blob/main/Tests/AuthTests/__Snapshots__/RequestsTests/passkeyRegistrationOptions.1.txt

Use this curl command to initiate passkey registration. It sends a POST request to the /auth/v1/passkeys/registration/options endpoint with required headers including Apikey, Authorization, X-Client-Info, and X-Supabase-Api-Version.

```bash
curl \
	--request POST \
	--header "Apikey: dummy.api.key" \
	--header "Authorization: Bearer accesstoken" \
	--header "X-Client-Info: gotrue-swift/x.y.z" \
	--header "X-Supabase-Api-Version: 2024-01-01" \
	"http://localhost:54321/auth/v1/passkeys/registration/options"
```

--------------------------------

### Opt in to replicationReady and listen for system event

Source: https://github.com/supabase/supabase-swift/blob/main/docs/migrations/RealtimeV2 Migration Guide.md

Set `broadcast.replicationReady = true` when creating the channel to have the server emit a `system` event once the Postgres replication connection is established. The event arrives via `channel.system()`; `status == .ok` indicates the connection is ready with message "Replication connection established".

```swift
let channel = supabase.channel("room") {
    $0.broadcast.replicationReady = true
}

Task {
    for await message in channel.system() {
        if message.status == .ok {
            // Replication connection is ready.
        }
    }
}

await channel.subscribe()
```

--------------------------------

### Invoke function with GET method and query parameters

Source: https://github.com/supabase/supabase-swift/blob/main/Sources/Functions/Functions.docc/InvokingFunctions.md

FunctionInvokeOptions/method is an HTTPRequest.Method and FunctionInvokeOptions/query is appended to the URL. A sub-path goes in the name.

```swift
let response = try await supabase.functions.invoke(
  "report/monthly",
  options: .init(method: .get, query: [URLQueryItem(name: "month", value: "2026-09")])
)
let pdf = response.body
```

--------------------------------

### Format Swift Files with swift-format

Source: https://github.com/supabase/supabase-swift/blob/main/AGENTS.md

Formats all Swift files using swift-format. All code should be formatted before committing.

```bash
# Format all Swift files
./scripts/format.sh
```

--------------------------------

### Handling FunctionsError and CancellationError

Source: https://github.com/supabase/supabase-swift/blob/main/Sources/Functions/Functions.docc/HandlingErrors.md

Example of catching FunctionsError and CancellationError when invoking a function, checking the error kind and platform error status.

```APIDOC
## Handling FunctionsError and CancellationError

### Description
Demonstrates how to catch and handle errors from the `FunctionsClient.invoke` method, distinguishing between platform errors, function errors, and cancellations.

### Code Example
```swift
do {
  try await supabase.functions.invoke("flaky")
} catch let error as FunctionsError where error.kind == .server {
  if error.isPlatformError {
    log("platform \(error.code?.rawValue ?? "?") status \(error.response?.statusCode ?? 0)")
  } else if let body = error.response?.body {
    let problem = try? JSONDecoder().decode(Problem.self, from: body)
  }
} catch is CancellationError {
  // the user navigated away
}
```

### Error Handling Notes
- Every failure from `FunctionsClient` is a `FunctionsError` or a `CancellationError`.
- Check `FunctionsError.kind` first.
- The relay check runs before the status check.
- `FunctionsError.code` reads the `sb-error-code` header.
- `FunctionsError.isPlatformError` is `true` for every code except `edgeFunctionError`.
- `FunctionsError.Code` is an open set; compare against static members and keep a fallback branch.
- `FunctionsError.response` carries status, headers, and body for `relay` and `server` kinds.
- The error body is capped at 1 MiB.
- `response.requestID` is the gateway's `sb-request-id`.
- A cancelled task throws `CancellationError` from `invoke`, `stream`, and loops over `FunctionStreamResponse.body`.
- A `URLError(.cancelled)` without task cancellation stays `.transport`.
- A timeout is `.transport` with `URLError(.timedOut)`.
- The SDK never retries an invocation; retry only when the function is idempotent.
```

--------------------------------

### Decode function response with HTTPResponse.Status

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Before/after example for FunctionsClient.invoke decode closure. The after version compares response.status to .ok instead of response.statusCode to 200.

```swift
// Before
let payload = try await supabase.functions.invoke("hello") { data, response in
  guard response.statusCode == 200 else { throw MyError.unexpected }
  return try JSONDecoder().decode(Payload.self, from: data)
}

// After
let payload = try await supabase.functions.invoke("hello") { data, response in
  guard response.status == .ok else { throw MyError.unexpected }
  return try JSONDecoder().decode(Payload.self, from: data)
}
```

--------------------------------

### Before: SupabaseStorageClient.from(_:) ignoring mutated headers

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the old implementation of from(_:) that built StorageFileApi from configuration only, ignoring live header mutations, causing headers set via setHeader to be dropped on list() calls.

```swift
// Before, inside SupabaseStorageClient.from(_:):
public func from(_ id: String) -> StorageFileApi {
  StorageFileApi(bucketId: id, configuration: configuration)  // not the mutated headers
}
```

--------------------------------

### String interpolation of MobileOTPType

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

String interpolation now prints the struct's default description instead of the case name. Use .rawValue explicitly to get the bare string.

```swift
"\(MobileOTPType.sms)"
```

--------------------------------

### FunctionsClient initialization before and after migration

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the old flat initializer and the new Configuration-based initializer. The new one requires wrapping arguments in a Configuration struct and uses HTTPField.Name for headers. Compile errors occur at standalone construction sites; supabase.functions is unaffected. The initializer traps if the URL has no host, and headers must not contain Authorization.

```swift
// Before
let functions = FunctionsClient(
  url: url,
  headers: ["apikey": apiKey],
  region: .usEast1,
  accessToken: { await tokenStore.current }
)
```

```swift
// After
let functions = FunctionsClient(
  configuration: .init(
    url: url,
    headers: [HTTPField.Name("apikey")!: apiKey],
    region: .usEast1,
    accessToken: { await tokenStore.current }
  )
)
```

--------------------------------

### Initialize SupabaseClient with custom options

Source: https://github.com/supabase/supabase-swift/blob/main/README.md

Initializes a SupabaseClient with custom options: a database schema, custom auth storage and PKCE flow type, and global headers with a custom URLSession transport. Requires MyCustomLocalStorage and URLSession.myCustomSession to be defined.

```swift
let client = SupabaseClient(
    supabaseURL: URL(string: "https://xyzcompany.supabase.co")!,
    supabaseKey: "your-publishable-key",
    options: SupabaseClientOptions(
        db: .init(
            schema: "public"
        ),
        auth: .init(
            storage: MyCustomLocalStorage(),
            flowType: .pkce
        ),
        global: .init(
            headers: ["x-my-custom-header": "my-app-name"],
            http: .init(transport: URLSessionTransport(session: URLSession.myCustomSession))
        )
    )
)
```

--------------------------------

### Read ETag header from PostgrestResponse using HTTPFields

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Before/after example for accessing response headers. The after version uses headerFields subscripted by HTTPField.Name (.eTag) instead of value(forHTTPHeaderField:).

```swift
// Before
let response = try await supabase.from("todos").select().execute()
let etag = response.response.value(forHTTPHeaderField: "ETag")

// After
let response = try await supabase.from("todos").select().execute()
let etag = response.response.headerFields[.eTag]
```

--------------------------------

### Before (Windows): SupabaseClient without storage

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the previous Windows code that relied on the default WinCredLocalStorage. This now fails to compile because the default no longer exists on Windows.

```swift
// Before (Windows)
let client = SupabaseClient(supabaseURL: url, supabaseKey: key)
```

--------------------------------

### Array columns still accept NULL members

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Real Postgres arrays may contain NULL, so Optional still conforms to PostgrestArrayElement. This example still compiles and sends `tags=cs.{a,NULL}`.

```swift
// Still compiles, still sends `tags=cs.{a,NULL}`
try await client.from("users").select().contains("tags", value: [Optional("a"), nil]).execute()
```

--------------------------------

### Before: Storage with StorageHTTPSession

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the v2 pattern for Storage using `StorageHTTPSession`.

```swift
// Before
let storage = SupabaseStorageClient(
  configuration: StorageClientConfiguration(
    url: storageURL,
    headers: headers,
    session: StorageHTTPSession(session: session)
  )
)
```

--------------------------------

### Stop Docker-based Supabase stack

Source: https://github.com/supabase/supabase-swift/blob/main/AGENTS.md

Stops an older Docker-based Supabase stack that may be holding the ports needed by the native stack. Run this from the directory that started the Docker stack, with the SUPABASE_EXPERIMENTAL_STACK variable unset.

```bash
env -u SUPABASE_EXPERIMENTAL_STACK supabase stop
```

--------------------------------

### Match AuthError response status code with optional chaining

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Before/after example for pattern matching AuthError. The after version uses a type check and optional chaining on error.response?.statusCode instead of the enum pattern.

```swift
// Before
} catch let AuthError.api(_, _, _, response) where response.statusCode == 429 {

// After
} catch let error as AuthError where error.response?.statusCode == 429 {
```

--------------------------------

### Build Commands for supabase-swift

Source: https://github.com/supabase/supabase-swift/blob/main/AGENTS.md

Commands to build the Swift package using Swift Package Manager or Xcode. Includes options for debug/release configurations, library evolution, and platform-specific builds.

```bash
# Build the package
swift build

# Build for specific configuration
swift build -c debug
swift build -c release

# Build with library evolution
./scripts/build-for-library-evolution.sh

# Build using Xcode
PLATFORM=IOS ./scripts/xcodebuild.sh
PLATFORM=MACOS ./scripts/xcodebuild.sh
```

--------------------------------

### Migrate SupabaseClient logger from SupabaseLogger to Logging.Logger

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the before and after of constructing SupabaseClient with a logger. The before uses a custom SupabaseLogger, the after uses a Logging.Logger with logLevel set to .debug.

```swift
// Before
import Supabase

let client = SupabaseClient(
  supabaseURL: url,
  supabaseKey: key,
  options: .init(global: .init(logger: MyCustomLogger()))
)
```

```swift
// After
import Logging
import Supabase

var logger = Logger(label: "myapp")
logger.logLevel = .debug
let client = SupabaseClient(
  supabaseURL: url,
  supabaseKey: key,
  options: .init(global: .init(logger: logger))
)
```

--------------------------------

### Create FunctionsClient with Configuration

Source: https://github.com/supabase/supabase-swift/blob/main/Sources/Functions/Functions.docc/Standalone.md

Initializes a FunctionsClient with a configuration that requires a URL. The URL must have a host; otherwise the initializer traps. The accessToken closure is called for every request and its non-nil result is sent as Authorization: Bearer unless the request already carries Authorization. Headers must not contain Authorization; use apikey there.

```swift
let functions = FunctionsClient(
  configuration: .init(
    url: URL(string: "https://<ref>.supabase.co/functions/v1")!,
    headers: [HTTPField.Name("apikey")!: "sb_publishable_…"],
    region: .usEast1,
    accessToken: { await tokenStore.current }
  )
)
```

--------------------------------

### Curl Request with Non-Alphanumeric Filter

Source: https://github.com/supabase/supabase-swift/blob/main/Tests/PostgRESTTests/__Snapshots__/BuildURLRequestTests/testBuildRequest.filter-starting-with-non-alphanumeric.txt

Use this curl command to query the 'users' table with a filter on the 'to' column, where the value starts with a non-alphanumeric character (e.g., '+'). The command includes required headers for content type and client info.

```bash
curl \
	--header "Accept: application/json" \
	--header "Content-Type: application/json" \
	--header "X-Client-Info: postgrest-swift/x.y.z" \
	"https://example.supabase.co/users?select=*&to=eq.+16505555555"
```

--------------------------------

### After: Storage with http transport

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the v3 pattern for Storage using `http: .init(transport: URLSessionTransport(session:))`.

```swift
// After
let storage = SupabaseStorageClient(
  configuration: StorageClientConfiguration(
    url: storageURL,
    headers: headers,
    http: .init(transport: URLSessionTransport(session: session))
  )
)
```

--------------------------------

### Stream server-sent events with manual framing

Source: https://github.com/supabase/supabase-swift/blob/main/Sources/Functions/Functions.docc/StreamingResponses.md

Use FunctionsClient.stream to get a FunctionStreamResponse and iterate its body, buffering chunks and splitting on blank lines to frame events. The loop ends when the server closes the connection; [DONE] is an OpenAI convention not handled by the SDK.

```swift
let response = try await supabase.functions.stream("chat", body: .json(prompt))

var buffer = Data()
for try await chunk in response.body {
  buffer.append(contentsOf: chunk)
  while let range = buffer.range(of: Data("\n\n".utf8)) {
    let event = String(decoding: buffer[..<range.lowerBound], as: UTF8.self)
    buffer.removeSubrange(..<range.upperBound)
    let data = event.split(separator: "\n")
      .filter { $0.hasPrefix("data:") }
      .map { $0.dropFirst(5).trimmingCharacters(in: .whitespaces) }
      .joined(separator: "\n")
    if data == "[DONE]" { return }
    await render(data)
  }
}
```

--------------------------------

### Sign In with Email and Password using curl

Source: https://github.com/supabase/supabase-swift/blob/main/Tests/AuthTests/__Snapshots__/RequestsTests/signInWithEmailAndPassword.1.txt

Use this curl command to authenticate a user with email and password. It sends a POST request to the token endpoint with grant_type=password, including the Apikey, Content-Type, X-Client-Info, and X-Supabase-Api-Version headers, and a JSON body containing email, password, and a captcha token.

```bash
curl \
	--request POST \
	--header "Apikey: dummy.api.key" \
	--header "Content-Type: application/json" \
	--header "X-Client-Info: gotrue-swift/x.y.z" \
	--header "X-Supabase-Api-Version: 2024-01-01" \
	--data "{\"email\":\"example@mail.com\",\"gotrue_meta_security\":{\"captcha_token\":\"dummy-captcha\"},\"password\":\"the.pass\"}" \
	"http://localhost:54321/auth/v1/token?grant_type=password"
```

--------------------------------

### Configure Supabase.plist

Source: https://github.com/supabase/supabase-swift/blob/main/Examples/README.md

Define the Supabase URL and publishable key in the Supabase.plist file to connect the app to the local instance.

```xml
<dict>
  <key>SUPABASE_URL</key>
  <string>http://127.0.0.1:54321</string>
  <key>SUPABASE_PUBLISHABLE_KEY</key>
  <string>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0</string>
</dict>
```

--------------------------------

### Invoke a Supabase Edge Function with JSON body and decode response

Source: https://github.com/supabase/supabase-swift/blob/main/Sources/Functions/Functions.docc/Functions.md

Use the FunctionsClient to invoke an Edge Function with a JSON-encoded body and decode the response as a Decodable type. The example defines Encodable and Decodable structs and calls invoke with the function name and body.

```swift
struct Prompt: Encodable { var text: String }
struct Answer: Decodable { var text: String }

let answer: Answer = try await supabase.functions.invoke("ask", body: .json(Prompt(text: "hi")))
```

--------------------------------

### @Table schema: type instead of string (before/after)

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the change where `@Table`'s `schema:` parameter now takes a type conforming to `PostgrestSchema` instead of a string. The example defines a `PrivateSchema` enum and uses it in the `@Table` macro. Relations without a schema belong to `PublicSchema`.

```swift
// Before
@Table("secrets", schema: "private")
struct Secret { ... }

// After
enum PrivateSchema: PostgrestSchema {
  static let name = "private"
}

@Table("secrets", schema: PrivateSchema.self)
struct Secret { ... }
```

--------------------------------

### Switch over PostgrestReturningOptions before and after

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the switch statement over PostgrestReturningOptions before and after the change. After the change, an exhaustive switch requires a default case to handle unrecognized returning modes.

```swift
// Before
switch returning {
case .minimal: ...
case .representation: ...
}

// After
switch returning {
case .minimal: ...
case .representation: ...
default: ...  // a returning mode the SDK doesn't have a case for
}
```

--------------------------------

### curl request for selecting users by email ending with @supabase.co

Source: https://github.com/supabase/supabase-swift/blob/main/Tests/PostgRESTTests/__Snapshots__/BuildURLRequestTests/testBuildRequest.select-all-users-where-email-ends-with-supabase-co.txt

Example curl command for a PostgREST request that selects all users whose email ends with '@supabase.co'. It includes required headers and the query parameter 'email=like.%25@supabase.co' to perform a LIKE pattern match.

```bash
curl \
	--header "Accept: application/json" \
	--header "Content-Type: application/json" \
	--header "X-Client-Info: postgrest-swift/x.y.z" \
	"https://example.supabase.co/users?email=like.%25@supabase.co&select=*"
```

--------------------------------

### curl command for iLikeAnyOf query

Source: https://github.com/supabase/supabase-swift/blob/main/Tests/PostgRESTTests/__Snapshots__/BuildURLRequestTests/testBuildRequest.iLikeAnyOf.txt

Use this curl command to reproduce the request generated by the iLikeAnyOf filter. It sends a GET request to the users endpoint with an email filter using the ilike operator and the any modifier, matching the provided patterns. The X-Client-Info header identifies the postgrest-swift client version.

```bash
curl \
	--header "Accept: application/json" \
	--header "Content-Type: application/json" \
	--header "X-Client-Info: postgrest-swift/x.y.z" \
	"https://example.supabase.co/users?email=ilike(any).%7B%25@supabase.io,%25@supabase.com%7D&select=*"
```

--------------------------------

### Check sdk-compliance.yaml

Source: https://github.com/supabase/supabase-swift/blob/main/AGENTS.md

Checks sdk-compliance.yaml against the current public API locally, without network access. Run before pushing a public-API change.

```bash
# Check sdk-compliance.yaml against the current public API
./scripts/check-compliance.sh
```

--------------------------------

### Apply migrations to remote Supabase project

Source: https://github.com/supabase/supabase-swift/blob/main/Examples/README.md

Commands to link your local environment to a remote project and push database migrations.

```bash
# Link to your project
supabase link --project-ref your-project-ref

# Push migrations to remote
supabase db push

# Optional: Load seed data
supabase db reset --db-url "your-database-url"
```

--------------------------------

### Swift: Before and after get-prefixed accessor calls

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the old and new call syntax for the renamed accessors. The old calls use the `get` prefix (e.g., `getUserById`, `getPublicURL`), while the new calls drop it (e.g., `user(id:)`, `publicURL(path:)`). This change is a compile error, so update all call sites.

```swift
// Before
let user = try await supabase.auth.admin.getUserById(id)
let url = try supabase.storage.from("avatars").getPublicURL(path: "me.png")

// After
let user = try await supabase.auth.admin.user(id: id)
let url = try supabase.storage.from("avatars").publicURL(path: "me.png")
```

--------------------------------

### Replace StorageApi(configuration:) with SupabaseStorageClient(configuration:)

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

StorageApi is no longer public. Construct SupabaseStorageClient instead, which exposes a superset of StorageApi's public surface (configuration, setHeader(_:forKey:), from(_:)).

```swift
// Before
var configuration = PostgrestClient.Configuration(url: url)
configuration.decoder = myDecoder

// After — set it at construction time, or pass a per-call override (see below)
let configuration = PostgrestClient.Configuration(url: url, decoder: myDecoder)
```

--------------------------------

### Check and restart local Supabase services

Source: https://github.com/supabase/supabase-swift/blob/main/Examples/README.md

Use these commands to verify the status of your local Supabase instance and restart services if they are not running correctly.

```bash
# Check status
supabase status

# Restart services
supabase stop
SUPABASE_EXPERIMENTAL_STACK=1 supabase start --runtime native
```

--------------------------------

### Before and after: using setHeader(name:value:) with PostgREST builder

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the old in-place mutation pattern (which now produces a warning and silently drops the header) and the new pattern that reassigns the result. Use the after version to ensure the header is applied.

```swift
// Before — mutated `q` in place, chained call not required
let q = client.from("todos").select()
q.setHeader(name: "X-Foo", value: "1")
try await q.execute()

// After — setHeader/retry return a NEW value; you must use the result
var q = client.from("todos").select()
q = q.setHeader(name: "X-Foo", value: "1")
try await q.execute()
```

--------------------------------

### Before: Auth, PostgREST, Functions with fetch closures

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the v2 pattern where each client takes a `fetch:` closure that calls `session.data(for:)`.

```swift
// Before
let session = URLSession(configuration: configuration)

let auth = AuthClient(
  url: authURL,
  localStorage: localStorage,
  fetch: { try await session.data(for: $0) }
)
let database = PostgrestClient(
  url: databaseURL,
  fetch: { try await session.data(for: $0) }
)
let functions = FunctionsClient(
  url: functionsURL,
  fetch: { try await session.data(for: $0) }
)
```

--------------------------------

### After: Auth, PostgREST, Functions with http transport

Source: https://github.com/supabase/supabase-swift/blob/main/V3_MIGRATION.md

Shows the v3 pattern using `URLSessionTransport` and `http: .init(transport:)` for each client.

```swift
// After
let session = URLSession(configuration: configuration)
let transport = URLSessionTransport(session: session)

let auth = AuthClient(
  url: authURL,
  localStorage: localStorage,
  http: .init(transport: transport)
)
let database = PostgrestClient(
  url: databaseURL,
  http: .init(transport: transport)
)
let functions = FunctionsClient(
  url: functionsURL,
  http: .init(transport: transport)
)
```
Tokens:
Raw