Swift Reference v1.0

swift Client Library

supabase-swiftView on GitHub

This reference documents every object and method available in Supabase's Swift library, supabase-swift. You can use supabase-swift to interact with your Postgres database, listen to database changes, invoke Deno Edge Functions, build login and user management functionality, and manage large files.


Initializing

You can initialize Supabase with the SupabaseClient by passing your Project URL and Project Key. You can find these under your Project SettingsAPI Settings The Supabase client is your entrypoint to the rest of the Supabase functionality and is the easiest way to interact with everything we offer within the Supabase ecosystem.


_10
let client = SupabaseClient(supabaseURL: URL(string: "https://xyzcompany.supabase.co")!, supabaseKey: "public-anon-key")


Fetch data

  • By default, Supabase projects will return a maximum of 1,000 rows. This setting can be changed in Project API Settings. It's recommended that you keep it low to limit the payload size of accidental or malicious requests. You can use range() queries to paginate through your data.
  • select() can be combined with Modifiers
  • select() can be combined with Filters
  • If using the Supabase hosted platform apikey is technically a reserved keyword, since the API gateway will pluck it out for authentication. It should be avoided as a column name.
  • The recommended solution for getting data is to use the value property which will return a decoded model. Create a Codable to easily decode your database responses.

_10
struct Country: Decodable {
_10
let id: Int
_10
let name: String
_10
}
_10
_10
let countries: [Country] = try await supabase.database
_10
.from("countries")
_10
.select()
_10
.execute()
_10
.value


Insert data


_11
struct Country: Encodable {
_11
let id: Int
_11
let name: String
_11
}
_11
_11
let country = Country(id: 1, name: "Denmark")
_11
_11
try await supabase.database
_11
.from("countries")
_11
.insert(country)
_11
.execute()


Update data

  • update() should always be combined with Filters to target the item(s) you wish to update.

_10
try await supabase.database
_10
.from("countries")
_10
.update(["name": "Australia"])
_10
.eq("id", value: 1)
_10
.execute()


Upsert data

  • Primary keys must be included in values to use upsert.

_10
struct Country: Encodable {
_10
let id: Int
_10
let name: String
_10
}
_10
try await supabase.database
_10
.from("countries")
_10
.upsert(Country(id: 1, name: "Albania"))
_10
.execute()


Delete data

  • delete() should always be combined with filters to target the item(s) you wish to delete.
  • If you use delete() with filters and you have RLS enabled, only rows visible through SELECT policies are deleted. Note that by default no rows are visible, so you need at least one SELECT/ALL policy that makes the rows visible.

_10
try await supabase.database
_10
.from("countries")
_10
.delete()
_10
.eq("id", value: 1)
_10
.execute()


Call a Postgres function

You can call Postgres functions as Remote Procedure Calls, logic in your database that you can execute from anywhere. Functions are useful when the logic rarely changes—like for password resets and updates.


_10
create or replace function hello_world() returns text as $$
_10
select 'Hello world';
_10
$$ language sql;


_10
let value: String = try await supabase.database
_10
.rpc("hello_world")
_10
.execute()
_10
.value


Using filters

Filters allow you to only return rows that match certain conditions.

Filters can be used on select(), update(), upsert(), and delete() queries.

If a Postgres function returns a table response, you can also apply filters.

Implement URLQueryRepresentable protocol in your own types to be able to use them as filter value.

Supported filtes are: eq, neq, gt, gte, lt, lte, like, ilike, is, in, cs, cd, sl, sr, nxl, nxr, adj, ov, fts, plfts, phfts, wfts. Check available operators in PostgREST.


_10
try await supabase.database
_10
.from("cities")
_10
.select("name, country_id")
_10
.eq("name", value: "The Shire") // Correct
_10
_10
try await supabase.database
_10
.from("citites")
_10
.eq("name", value: "The Shire") // Incorrect
_10
.select("name, country_id")


Match an associated value


_10
try await supabase.database
_10
.from("countries")
_10
.select("name")
_10
.match(["id": 2, "name": "Albania"])


Don't match the filter

Finds all rows that don't satisfy the filter.

  • .not() expects you to use the raw PostgREST syntax for the filter names and values.


    _10
    .not("name", operator: .eq, value: "Paris")
    _10
    .not("arraycol", operator: .cs, value: #"{"a","b"}"#) // Use Postgres array {} for array column and 'cs' for contains.
    _10
    .not("rangecol", operator: .cs, value: "(1,2]") // Use Postgres range syntax for range column.
    _10
    .not("id", operator: .in, value: "(6,7)") // Use Postgres list () and 'in' for in_ filter.
    _10
    .not("id", operator: .in, value: "(\(mylist.join(separator: ",")))") // You can insert a Swift list array.


_10
try await supabase.database
_10
.from("countries")
_10
.select()
_10
.not("name", operator: .is, value: "")
_10
.execute()


Match at least one filter

or() expects you to use the raw PostgREST syntax for the filter names and values.


_10
.or(#"id.in.(5,6,7), arraycol.cs.{"a","b"}"#) // Use `()` for `in` filter, `{}` for array values and `cs` for `contains()`.
_10
.or(#"id.in.(5,6,7), arraycol.cd.{"a","b"}"#) // Use `cd` for `containedBy()`


_10
try await supabase.database
_10
.from("countries")
_10
.select("name")
_10
.or("id.eq.2,name.eq.Algeria")


Match the filter

filter() expects you to use the raw PostgREST syntax for the filter values.


_10
.filter("id", operator: .in, value: "(5,6,7)") // Use `()` for `in` filter
_10
.filter("arraycol", operator: .cs, value: #"{"a","b"}"#) // Use `cs` for `contains()`, `{}` for array values


_10
try await supabase.database
_10
.from("countries")
_10
.select()
_10
.filter("name", operator: .in, value: #"("Algeria","Japan")"#)


Using modifiers

Filters work on the row level—they allow you to return rows that only match certain conditions without changing the shape of the rows. Modifiers are everything that don't fit that definition—allowing you to change the format of the response (e.g. returning a CSV string).

Modifiers must be specified after filters. Some modifiers only apply for queries that return rows (e.g., select() or rpc() on a function that returns a table response).


Return data after inserting

Perform a SELECT on the query result.


_10
try await database.database
_10
.from("countries")
_10
.upsert(CountryModel(id: 1, name: "Algeria"))
_10
.select()
_10
.execute()


Order the results

Order the query result by column.


_10
try await supabase.database
_10
.from("countries")
_10
.select("id, name")
_10
.order("id", ascending: false)
_10
.execute()


Limit the number of rows returned

Limit the query result by count.


_10
try await supabase.database
_10
.from("countries")
_10
.select("id, name")
_10
.limit(1)
_10
.execute()


Limit the query to a range

Limit the query result by from and to inclusively.


_12
try await supabase.database
_12
.from("countries")
_12
.select(
_12
"""
_12
name,
_12
cities (
_12
name
_12
)
_12
"""
_12
)
_12
.range(from: 0, to: 1)
_12
.execute()


Retrieve one row of data

By default PostgREST returns all JSON results in an array, even when there is only one item, use single() to return the first object unenclosed by an array.


_10
try await supabase.database
_10
.from("countries")
_10
.select("name")
_10
.limit(1)
_10
.single()
_10
.execute()


Retrieve as a CSV


_10
try await supabase
_10
.from("countries")
_10
.select()
_10
.csv()
_10
.execute()


Overview

  • The auth methods can be accessed via the supabase.auth namespace.

_10
let supabase = SupabaseClient(supabaseURL: URL(string: "https://xyzcompany.supabase.co")!, supabaseKey: "public-anon-key")
_10
let auth = supabase.auth


Create a new user

  • By default, the user needs to verify their email address before logging in. To turn this off, disable Confirm email in your project.
  • Confirm email determines if users need to confirm their email address after signing up.
    • If Confirm email is enabled, a user is returned but session is null.
    • If Confirm email is disabled, both a user and a session are returned.
  • When the user confirms their email address, they are redirected to the SITE_URL by default. You can modify your SITE_URL or add additional redirect URLs in your project.
  • If signUp() is called for an existing confirmed user:
    • If Confirm email is enabled in your project, an obfuscated/fake user object is returned.
    • If Confirm email is disabled, the error message, User already registered is returned.
  • To fetch the currently logged-in user, refer to getUser().

_10
try await supabase.auth.signUp(
_10
email: "example@email.com",
_10
password: "example-password"
_10
)


Listen to auth events

  • Types of auth events: INITIAL_SESSION, SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED, PASSWORD_RECOVERY, MFA_CHALLENGE_VERIFIED
  • The INITIAL_SESSION can be used to allow you to invoke the callback function when authStateChanges is first called.

_10
for await (event, session) in await supabase.auth.authStateChanges {
_10
print(event, session)
_10
}


Sign in a user

  • Requires either an email and password or a phone number and password.

_10
try await supabase.auth.signIn(
_10
email: "example@email.com",
_10
password: "example-password"
_10
)


Sign in with ID Token


_10
let session = try await supabase.auth.signInWithIdToken(
_10
credentials: OpenIDConnectCredentials(
_10
provider: .apple,
_10
idToken: "your-id-token",
_10
nonce: "your nonce"
_10
)
_10
)


Sign in a user through OTP

  • This method is used for passwordless sign-ins where a OTP is sent to the user's email or phone number.
  • If the user doesn't exist, signInWithOTP() will signup the user instead. To restrict this behavior, you can set shouldCreateUser to false.
  • If you're using an email, you can configure whether you want the user to receive a magiclink or a OTP.
  • If you're using phone, you can configure whether you want the user to receive a OTP.
  • The magic link's destination URL is determined by the SITE_URL.
  • See redirect URLs and wildcards to add additional redirect URLs to your project.
  • Magic links and OTPs share the same implementation. To send users a one-time code instead of a magic link, modify the magic link email template to include {{ .Token }} instead of {{ .ConfirmationURL }}.
  • When using magic links, specify a redirectTo that matches a configured url scheme in your iOS app, so Supabase can correctly redirect back to your app.
  • See our Twilio Phone Auth Guide for details about configuring WhatsApp sign in.

_10
try await supabase.auth.signInWithOTP(
_10
email: "example@email.com",
_10
redirectTo: URL(string: "my-app-scheme://")!
_10
)


Sign in a user through OAuth

  • This method is used for signing in using a third-party provider.
  • Supabase supports many different third-party providers.

_13
let url = try await supabase.auth.getOAuthSignInURL(provider: .github)
_13
_13
let session = ASWebAuthenticationSession(url: url, callbackURLScheme: "my-app-scheme") { url, error in
_13
guard let url else { return }
_13
_13
Task {
_13
try await supabase.auth.session(from: url)
_13
}
_13
}
_13
_13
session.presentationContextProvider = self // yours ASWebAuthenticationPresentationContextProviding implementation.
_13
_13
session.start()


Sign out a user

  • In order to use the signOut() method, the user needs to be signed in first.

_10
try await supabase.auth.signOut()


Verify and log in through OTP

  • The verifyOTP method takes in different verification types. If a phone number is used, the type can either be sms or phone_change. If an email address is used, the type can be one of the following: signup, magiclink, recovery, invite, email_change, or email.
  • The verification type used should be determined based on the corresponding auth method called before verifyOTP to sign up / sign-in a user.

_10
try await supabase.auth.verifyOTP(
_10
phone: "+13334445555",
_10
token: "123456",
_10
type: .sms
_10
)


Retrieve a session

  • Returns the session, refreshing it if necessary. If no session can be found, a GoTrueError.sessionNotFound error is thrown.

_10
try await supabase.auth.session


Retrieve a new session

  • This method will refresh the session whether the current one is expired or not.

_10
let session = try await supabase.auth.refreshSession()


Retrieve a user

  • This method is useful for checking if the user is authorized because it validates the user's access token JWT on the server.
  • Fetches the user object from the database instead of local session.
  • Should be used only when you require the most current user data. For faster results, session.user is recommended.

_10
let user = try await supabase.auth.user()


Update a user

  • In order to use the updateUser() method, the user needs to be signed in first.
  • By default, email updates sends a confirmation link to both the user's current and new email. To only send a confirmation link to the user's new email, disable Secure email change in your project's email auth provider settings.

_10
try await supabase.auth.update(user: UserAttributes(email: "new@email.com"))


Set the session data

  • setSession() takes in a refresh token and uses it to get a new session.
  • The refresh token can only be used once to obtain a new session.
  • Refresh token rotation is enabled by default on all projects to guard against replay attacks.
  • You can configure the REFRESH_TOKEN_REUSE_INTERVAL which provides a short window in which the same refresh token can be used multiple times in the event of concurrency or offline issues.

_10
try await supabase.auth.setSession(accessToken: "access_token", refreshToken: "refresh_token")


Exchange an auth code for a session

  • Used when flowType is set to pkce in client options.

_10
try await supabase.auth.exchangeCodeForSession(authCode: "34e770dd-9ff9-416c-87fa-43b31d7ef225")


Auth MFA

This section contains methods commonly used for Multi-Factor Authentication (MFA) and are invoked behind the supabase.auth.mfa namespace.

Currently, we only support time-based one-time password (TOTP) as the 2nd factor. We don't support recovery codes but we allow users to enroll more than 1 TOTP factor, with an upper limit of 10.

Having a 2nd TOTP factor for recovery frees the user of the burden of having to store their recovery codes somewhere. It also reduces the attack surface since multiple recovery codes are usually generated compared to just having 1 backup TOTP factor.


Enroll a factor

  • Currently, totp is the only supported factorType. The returned id should be used to create a challenge.
  • To create a challenge, see mfa.challenge().
  • To verify a challenge, see mfa.verify().
  • To create and verify a challenge in a single step, see mfa.challengeAndVerify().

_15
let response = try await supabase.auth.mfa.enroll(
_15
params: MFAEnrollParams(
_15
issuer: "optional issuer",
_15
friendlyName: "optional friendly name"
_15
)
_15
)
_15
_15
// Use the id to create a challenge.
_15
// The challenge can be verified by entering the code generated from the authenticator app.
_15
// The code will be generated upon scanning the qrCode or entering the secret into the authenticator app.
_15
let id = response.id
_15
let type = response.type
_15
let qrCode = response.totp?.qrCode
_15
let secret = response.totp?.secret
_15
let uri = response.totp?.uri


Create a challenge


_10
let response = try await supabase.auth.mfa.challenge(
_10
params: MFAChallengeParams(
_10
factorId: "34e770dd-9ff9-416c-87fa-43b31d7ef225"
_10
)
_10
)


Verify a challenge


_10
let session = try await supabase.auth.mfa.verify(
_10
params: MFAVerifyParams(
_10
factorId: "34e770dd-9ff9-416c-87fa-43b31d7ef225",
_10
challengeId: "4034ae6f-a8ce-4fb5-8ee5-69a5863a7c15",
_10
code: "123456"
_10
)
_10
)


Create and verify a challenge


_10
let session = try await supabase.auth.mfa.challengeAndVerify(
_10
params: MFAChallengeAndVerifyParams(
_10
factorId: "34e770dd-9ff9-416c-87fa-43b31d7ef225",
_10
code: "123456"
_10
)
_10
)


Unenroll a factor


_10
let response = try await supabase.auth.mfa.unenroll(
_10
params: MFAUnenrollParams(
_10
factorId: "34e770dd-9ff9-416c-87fa-43b31d7ef225"
_10
)
_10
)


Get Authenticator Assurance Level

  • Authenticator Assurance Level (AAL) is the measure of the strength of an authentication mechanism.
  • In Supabase, having an AAL of aal1 refers to having the 1st factor of authentication such as an email and password or OAuth sign-in while aal2 refers to the 2nd factor of authentication such as a time-based, one-time-password (TOTP).
  • If the user has a verified factor, the nextLevel field will return aal2, else, it will return aal1.

_10
let aal = try await supabase.auth.mfa.getAuthenticatorAssuranceLevel()
_10
let currentLevel = aal.currentLevel
_10
let nextLevel = aal.nextLevel
_10
let currentAuthenticationMethods = aal.currentAuthenticationMethods


Invokes a Supabase Edge Function.

Invoke a Supabase Edge Function.

  • Requires an Authorization header.
  • When you pass in a body to your function, we automatically attach the Content-Type header for String, and Data. If it doesn't match any of these types we assume the payload is json, serialize it and attach the Content-Type header as application/json. You can override this behaviour by passing in a Content-Type header of your own.

_11
struct Response: Decodable {
_11
// Expected response definition
_11
}
_11
_11
let response: Response = try await supabase.functions
_11
.invoke(
_11
"hello",
_11
options: FunctionInvokeOptions(
_11
body: ["foo": "bar"]
_11
)
_11
)


Subscribe to channel

  • By default, Broadcast and Presence are enabled for all projects.
  • By default, listening to database changes is disabled for new projects due to database performance and security concerns. You can turn it on by managing Realtime's replication.
  • You can receive the "previous" data for updates and deletes by setting the table's REPLICA IDENTITY to FULL (e.g., ALTER TABLE your_table REPLICA IDENTITY FULL;).
  • Row level security is not applied to delete statements. When RLS is enabled and replica identity is set to full, only the primary key is sent to clients.

_19
let channel = supabase
_19
.realtime
_19
.channel("room1")
_19
_19
channel
_19
.on("broadcast", filter: ChannelFilter(event: "cursor-pos")) { message in
_19
print("Cursor position received!", message.payload)
_19
}
_19
.subscribe { status, error in
_19
if status == .subscribed {
_19
Task {
_19
await channel.send(
_19
type: .broadcast,
_19
event: "cursor-pos",
_19
payload: ["x": Double.random(in: 0...1), "y": Double.random(in: 0...1)]
_19
)
_19
}
_19
}
_19
}


Unsubscribe from a channel

  • Removing a channel is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.

_10
supabase.realtime.remove(myChannel)


Unsubscribe from all channels

  • Removing channels is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.

_10
supabase.realtime.removeAllChannels()


Retrieve all channels


_10
let channels = supabase.realtime.channels


Broadcast a message

Broadcast a message to all connected clients to a channel.

  • When using REST you don't need to subscribe to the channel

_13
supabase.realtime
_13
.channel("room1")
_13
.subscribe { status, error in
_13
if status == .subscribed {
_13
Task {
_13
await channel.send(
_13
type: "broadcast",
_13
event: "cursor-pos",
_13
payload: ["x": Double.random(in: 0...1), "y": Double.random(in: 0...1)]
_13
)
_13
}
_13
}
_13
}


Create a bucket

  • RLS policy permissions required:
    • buckets table permissions: insert
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

_10
try await supabase.storage
_10
.createBucket(
_10
"avatars",
_10
options: BucketOptions(
_10
public: false,
_10
allowedMimeTypes: ["image/png"],
_10
fileSizeLimit: 1024
_10
)
_10
)


Retrieve a bucket

  • RLS policy permissions required:
    • buckets table permissions: select
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

_10
let bucket = try await supabase.storage
_10
.getBucket("avatars")


List all buckets

  • RLS policy permissions required:
    • buckets table permissions: select
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

_10
try await supabase.storage
_10
.listBuckets()


Update a bucket

  • RLS policy permissions required:
    • buckets table permissions: select and update
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

_10
try await supabase.storage
_10
.updateBucket(
_10
"avatars",
_10
options: BucketOptions(
_10
public: false,
_10
fileSizeLimit: 1024,
_10
allowedMimeTypes: ["image/png"]
_10
)
_10
)


Delete a bucket

  • RLS policy permissions required:
    • buckets table permissions: select and delete
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

_10
try await supabase.storage
_10
.deleteBucket("avatars")


Empty a bucket

  • RLS policy permissions required:
    • buckets table permissions: select
    • objects table permissions: select and delete
  • Refer to the Storage guide on how access control works

_10
try await supabase.storage
_10
.emptyBucket("avatars")


Upload a file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: only insert when you are uploading new files and select, insert and update when you are upserting files
  • Refer to the Storage guide on how access control works

_13
let fileName = "avatar1.png"
_13
_13
try await supabase.storage
_13
.from("avatars")
_13
.upload(
_13
path: "public/\(fileName)",
_13
file: fileData,
_13
options: FileOptions(
_13
cacheControl: "3600",
_13
contentType: "image/png",
_13
upsert: false
_13
)
_13
)


Download a file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: select
  • Refer to the Storage guide on how access control works

_10
let data = try await supabase.storage
_10
.from("avatars")
_10
.download(path: "folder/avatar1.png")


List all files in a bucket

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: select
  • Refer to the Storage guide on how access control works

_10
let files = try await supabase.storage
_10
.from("avatars")
_10
.list(
_10
path: "folder",
_10
options: SearchOptions(
_10
limit: 100,
_10
offset: 0,
_10
sortBy: SortBy(column: "name", order: "asc")
_10
)
_10
)


Replace an existing file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: update and select
  • Refer to the Storage guide on how access control works

_13
let fileName = "avatar1.png"
_13
_13
try await supabase.storage
_13
.from("avatars")
_13
.update(
_13
path: "public/\(fileName)",
_13
file: fileData,
_13
options: FileOptions(
_13
cacheControl: "3600",
_13
contentType: "image/png",
_13
upsert: true
_13
)
_13
)


Move an existing file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: update and select
  • Refer to the Storage guide on how access control works

_10
try await supabase
_10
.storage
_10
.from("avatars")
_10
.move(from: "public/avatar1.png", to: "private/avatar2.png")


Copy an existing file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: insert and select
  • Refer to the Storage guide on how access control works

_10
try await supabase
_10
.storage
_10
.from("avatars")
_10
.copy(from: "public/avatar1.png", to: "private/avatar2.png")


Delete files in a bucket

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: delete and select
  • Refer to the Storage guide on how access control works

_10
try await supabase.storage
_10
.from("avatars")
_10
.remove(paths: ["folder/avatar1.png"])


Create a signed URL

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: select
  • Refer to the Storage guide on how access control works

_10
let signedURL = try await supabase.storage
_10
.from("avatars")
_10
.createSignedURL(path: "folder/avatar1.png", expiresIn: 60)


Retrieve public URL

  • The bucket needs to be set to public, either via updateBucket() or by going to Storage on supabase.com/dashboard, clicking the overflow menu on a bucket and choosing "Make public"
  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: none
  • Refer to the Storage guide on how access control works

_10
let publicURL = try supabase.storage
_10
.from("public-bucket")
_10
.getPublicURL(path: "folder/avatar1.png")