swift Client Library
supabase-swiftView on GitHubThis 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 Settings
→ API 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.
_10let 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 Modifiersselect()
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.
_10struct Country: Decodable {_10 let id: Int_10 let name: String_10}_10_10let countries: [Country] = try await supabase.database_10 .from("countries")_10 .select()_10 .execute()_10 .value
Insert data
_11struct Country: Encodable {_11 let id: Int_11 let name: String_11}_11_11let country = Country(id: 1, name: "Denmark")_11_11try 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.
_10try 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.
_10struct Country: Encodable {_10 let id: Int_10 let name: String_10}_10try 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 throughSELECT
policies are deleted. Note that by default no rows are visible, so you need at least oneSELECT
/ALL
policy that makes the rows visible.
_10try 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.
_10create or replace function hello_world() returns text as $$_10 select 'Hello world';_10$$ language sql;
_10let 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.
_10try await supabase.database_10 .from("cities")_10 .select("name, country_id")_10 .eq("name", value: "The Shire") // Correct_10_10try await supabase.database_10 .from("citites")_10 .eq("name", value: "The Shire") // Incorrect_10 .select("name, country_id")
Match an associated value
_10try 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.
_10try 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()`
_10try 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
_10try 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.
_10try 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.
_10try 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.
_12try 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.
_10try await supabase.database_10 .from("countries")_10 .select("name")_10 .limit(1)_10 .single()_10 .execute()
Retrieve as a CSV
_10try await supabase_10 .from("countries")_10 .select()_10 .csv()_10 .execute()
Overview
- The auth methods can be accessed via the
supabase.auth
namespace.
_10let supabase = SupabaseClient(supabaseURL: URL(string: "https://xyzcompany.supabase.co")!, supabaseKey: "public-anon-key")_10let 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 butsession
is null. - If Confirm email is disabled, both a
user
and asession
are returned.
- If Confirm email is enabled, a
- When the user confirms their email address, they are redirected to the
SITE_URL
by default. You can modify yourSITE_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()
.
_10try 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 whenauthStateChanges
is first called.
_10for 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.
_10try await supabase.auth.signIn(_10 email: "example@email.com",_10 password: "example-password"_10)
Sign in with ID Token
_10let 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 setshouldCreateUser
tofalse
. - 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.
_10try 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.
_13let url = try await supabase.auth.getOAuthSignInURL(provider: .github)_13_13let 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_13session.presentationContextProvider = self // yours ASWebAuthenticationPresentationContextProviding implementation._13_13session.start()
Sign out a user
- In order to use the
signOut()
method, the user needs to be signed in first.
_10try 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 besms
orphone_change
. If an email address is used, the type can be one of the following:signup
,magiclink
,recovery
,invite
,email_change
, oremail
. - The verification type used should be determined based on the corresponding auth method called before
verifyOTP
to sign up / sign-in a user.
_10try 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.
_10try await supabase.auth.session
Retrieve a new session
- This method will refresh the session whether the current one is expired or not.
_10let 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.
_10let 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.
_10try 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 topkce
in client options.
_10try 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 supportedfactorType
. The returnedid
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()
.
_15let 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._15let id = response.id_15let type = response.type_15let qrCode = response.totp?.qrCode_15let secret = response.totp?.secret_15let uri = response.totp?.uri
Create a challenge
- An enrolled factor is required before creating a challenge.
- To verify a challenge, see
mfa.verify()
.
_10let response = try await supabase.auth.mfa.challenge(_10 params: MFAChallengeParams(_10 factorId: "34e770dd-9ff9-416c-87fa-43b31d7ef225"_10 )_10)
Verify a challenge
- To verify a challenge, please create a challenge first.
_10let 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
- An enrolled factor is required before invoking
challengeAndVerify()
. - Executes
mfa.challenge()
andmfa.verify()
in a single step.
_10let 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
_10let 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 whileaal2
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 returnaal2
, else, it will returnaal1
.
_10let aal = try await supabase.auth.mfa.getAuthenticatorAssuranceLevel()_10let currentLevel = aal.currentLevel_10let nextLevel = aal.nextLevel_10let 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
, andData
. If it doesn't match any of these types we assume the payload isjson
, serialize it and attach theContent-Type
header asapplication/json
. You can override this behaviour by passing in aContent-Type
header of your own.
_11struct Response: Decodable {_11 // Expected response definition_11}_11_11let 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
toFULL
(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.
_19let channel = supabase_19 .realtime_19 .channel("room1")_19_19channel_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.
_10supabase.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.
_10supabase.realtime.removeAllChannels()
Retrieve all channels
_10let 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
_13supabase.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
_10try 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
_10let 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
_10try await supabase.storage_10 .listBuckets()
Update a bucket
- RLS policy permissions required:
buckets
table permissions:select
andupdate
objects
table permissions: none
- Refer to the Storage guide on how access control works
_10try 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
anddelete
objects
table permissions: none
- Refer to the Storage guide on how access control works
_10try await supabase.storage_10 .deleteBucket("avatars")
Empty a bucket
- RLS policy permissions required:
buckets
table permissions:select
objects
table permissions:select
anddelete
- Refer to the Storage guide on how access control works
_10try await supabase.storage_10 .emptyBucket("avatars")
Upload a file
- RLS policy permissions required:
buckets
table permissions: noneobjects
table permissions: onlyinsert
when you are uploading new files andselect
,insert
andupdate
when you are upserting files
- Refer to the Storage guide on how access control works
_13let fileName = "avatar1.png"_13_13try 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: noneobjects
table permissions:select
- Refer to the Storage guide on how access control works
_10let 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: noneobjects
table permissions:select
- Refer to the Storage guide on how access control works
_10let 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: noneobjects
table permissions:update
andselect
- Refer to the Storage guide on how access control works
_13let fileName = "avatar1.png"_13_13try 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: noneobjects
table permissions:update
andselect
- Refer to the Storage guide on how access control works
_10try 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: noneobjects
table permissions:insert
andselect
- Refer to the Storage guide on how access control works
_10try 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: noneobjects
table permissions:delete
andselect
- Refer to the Storage guide on how access control works
_10try await supabase.storage_10 .from("avatars")_10 .remove(paths: ["folder/avatar1.png"])
Create a signed URL
- RLS policy permissions required:
buckets
table permissions: noneobjects
table permissions:select
- Refer to the Storage guide on how access control works
_10let 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: noneobjects
table permissions: none
- Refer to the Storage guide on how access control works
_10let publicURL = try supabase.storage_10 .from("public-bucket")_10 .getPublicURL(path: "folder/avatar1.png")