Python Client Library

You can initialize a new Supabase client using the create_client() method.

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.

• By default, Supabase projects return a maximum of 1,000 rows. This setting can be changed in your project's 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 Filters
• select() can be combined with Modifiers
• apikey is a reserved keyword if you're using the Supabase Platform and should be avoided as a column name.

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

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

• 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.
• When using delete().in_(), specify an array of values to target multiple rows with a single query. This is particularly useful for batch deleting entries that share common criteria, such as deleting users by their IDs. Ensure that the array you provide accurately represents all records you intend to delete to avoid unintended data removal.

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.

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

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.

Match only rows where column is equal to value.

Match only rows where column is not equal to value.

Match only rows where column is greather than value.

Match only rows where column is greater than or equal to value.

Match only rows where column is less than value.

Match only rows where column is less than or equal to value.

Match only rows where column matches pattern case-sensitively.

Match only rows where column matches pattern case-insensitively.

Match only rows where column IS value.

Match only rows where column is included in the values array.

Only relevant for jsonb, array, and range columns. Match only rows where column contains every element appearing in value.

Only relevant for jsonb, array, and range columns. Match only rows where every element appearing in column is contained by value.

Only relevant for range columns. Match only rows where every element in column is greater than any element in range.

Only relevant for range columns. Match only rows where every element in column is either contained in range or greater than any element in range.

Only relevant for range columns. Match only rows where every element in column is less than any element in range.

Only relevant for range columns. Match only rows where every element in column is less than any element in range.

Only relevant for range columns. Match only rows where column is mutually exclusive to range and there can be no element between the two ranges.

Only relevant for array and range columns. Match only rows where column and value have an element in common.

Only relevant for text and tsvector columns. Match only rows where column matches the query string in query.

• For more information, see Postgres full text search.

Match only rows where each column in query keys is equal to its associated value. Shorthand for multiple .eq()s.

Match only rows which doesn't satisfy the filter. not_ expects you to use the raw PostgREST syntax for the filter values.

1
2
.not_.in_('id', '(5,6,7)')  # Use `()` for `in` filter.not_.contains('arraycol', '{"a","b"}')  # Use `{}` for array values

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

1
2
.or_('id.in.(5,6,7), arraycol.cs.{"a","b"}')  # Use `()` for `in` filter, `{}` for array values and `cs` for `contains()`..or_('id.in.(5,6,7), arraycol.cd.{"a","b"}')  # Use `cd` for `containedBy()`

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

1
2
.filter('id', 'in', '(5,6,7)')  # Use `()` for `in` filter.filter('arraycol', 'cs', '{"a","b"}')  # Use `cs` for `contains()`, `{}` for array values

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).

Order the query result by column.

Limit the query result by starting at an offset (start) and ending at the offset (end). Only records within this range are returned. This respects the query order and if there is no order clause the range could behave unexpectedly.

The start and end values are 0-based and inclusive: range(1, 3) will include the second, third and fourth rows of the query.

Return data as a single object instead of an array of objects.

Return data as a single object instead of an array of objects.

Return data as a string in CSV format.

For debugging slow queries, you can get the Postgres EXPLAIN execution plan of a query using the explain() method. This works on any query, even for rpc() or writes.

Explain is not enabled by default as it can reveal sensitive information about your database. It's best to only enable this for testing environments but if you wish to enable it for production you can provide additional protection by using a pre-request function.

Follow the Performance Debugging Guide to enable the functionality on your project.

• The auth methods can be accessed via the supabase.auth namespace.
• By default, the supabase client sets persist_session to true and attempts to store the session in memory.
• Any email links and one-time passwords (OTPs) sent have a default expiry of 24 hours. We have the following rate limits in place to guard against brute force attacks.
• The expiry of an access token can be set in the "JWT expiry limit" field in your project's auth settings. A refresh token never expires and can only be used once.

• 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.
• By default, when the user confirms their email address, they are redirected to the SITE_URL. You can modify your SITE_URL or add additional redirect URLs in your project.
• If sign_up() is called for an existing confirmed user:
  • When both Confirm email and Confirm phone (even when phone provider is disabled) are enabled in your project, an obfuscated/fake user object is returned.
  • When either Confirm email or Confirm phone (even when phone provider is disabled) is disabled, the error message, User already registered is returned.
• To fetch the currently logged-in user, refer to get_user().

• Returns an anonymous user
• It is recommended to set up captcha for anonymous sign-ins to prevent abuse. You can pass in the captcha token in the options param.

Log in an existing user with an email and password or phone and password.

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

Allows signing in with an OIDC ID token. The authentication provider used should be enabled and configured.

• Requires either an email or phone number.
• 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, sign_in_with_otp() will signup the user instead. To restrict this behavior, you can set should_create_user in SignInWithPasswordlessCredentials.options 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 }}.

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

• Before you can call this method you need to establish a connection to an identity provider. Use the CLI commands to do this.
• If you've associated an email domain to the identity provider, you can use the domain property to start a sign-in flow.
• In case you need to use a different way to start the authentication flow with an identity provider, you can use the provider_id property. For example:
  • Mapping specific user email addresses with an identity provider.
  • Using different hints to identity the identity provider to be used by the user, like a company-specific page, IP address or other tracking information.

• In order to use the sign_out() method, the user needs to be signed in first.
• By default, sign_out() uses the global scope, which signs out all other sessions that the user is logged into as well.
• Since Supabase Auth uses JWTs for authentication, the access token JWT will be valid until it's expired. When the user signs out, Supabase revokes the refresh token and deletes the JWT from the client-side. This does not revoke the JWT and it will still be valid until it expires.

• The password reset flow consist of 2 broad steps: (i) Allow the user to login via the password reset link; (ii) Update the user's password.
• The reset_password_for_email() only sends a password reset link to the user's email. To update the user's password, see update_user().
• When the user clicks the reset link in the email they are redirected back to your application. You can configure the URL that the user is redirected to with the redirectTo parameter. See redirect URLs and wildcards to add additional redirect URLs to your project.
• After the user has been redirected successfully, prompt them for a new password and call update_user():

1
2
3
response = supabase.auth.update_user(    {"password": new_password})

• The verify_otp 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: email, recovery, invite or email_change (signup and magiclink types are deprecated).
• The verification type used should be determined based on the corresponding auth method called before verify_otp to sign up / sign-in a user.
• The TokenHash is contained in the email templates and can be used to sign in. You may wish to use the hash with Magic Links for the PKCE flow for Server Side Auth. See this guide for more details.

• This method retrieves the current local session (i.e in memory).
• The session contains a signed JWT and unencoded session data.
• Since the unencoded session data is retrieved from the local storage medium, do not rely on it as a source of trusted data on the server. It could be tampered with by the sender. If you need verified, trustworthy user data, call get_user instead.
• If the session has an expired access token, this method will use the refresh token to get a new session.

Returns a new session, regardless of expiry status. Takes in an optional refresh token. If not passed in, then refresh_session() will attempt to retrieve it from get_session(). If the current session's refresh token is invalid, an error will be thrown.

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

• This method fetches the user object from the database instead of local session.
• This method is useful for checking if the user is authorized because it validates the user's access token JWT on the server.

• In order to use the update_user() 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.

Gets all the identities linked to a user.

• The user needs to be signed in to call get_user_identities().

• The Enable Manual Linking option must be enabled from your project's authentication settings.
• The user needs to be signed in to call link_identity().
• If the candidate identity is already linked to the existing user or another user, link_identity() will fail.
• If link_identity is run on the server, you should handle the redirect.

• The Enable Manual Linking option must be enabled from your project's authentication settings.
• The user needs to be signed in to call unlink_identity().
• The user must have at least 2 identities in order to unlink an identity.
• The identity to be unlinked must belong to the user.

• This method is used together with updateUser() when a user's password needs to be updated.
• If you require your user to reauthenticate before updating their password, you need to enable the Secure password change option in your project's email provider settings.
• A user is only require to reauthenticate before updating their password if Secure password change is enabled and the user hasn't recently signed in. A user is deemed recently signed in if the session was created in the last 24 hours.
• This method will send a nonce to the user's email. If the user doesn't have a confirmed email address, the method will send the nonce to the user's confirmed phone number instead.

• Resends a signup confirmation, email change or phone change email to the user.
• Passwordless sign-ins can be resent by calling the sign_in_with_otp() method again.
• Password recovery emails can be resent by calling the reset_password_for_email() method again.
• This method will only resend an email or phone OTP to the user if there was an initial signup, email change or phone change request being made.
• You can specify a redirect url when you resend an email link using the email_redirect_to option.

Sets the session data from the current session. If the current session is expired, setSession will take care of refreshing it to obtain a new session. If the refresh token or access token in the current session is invalid, an error will be thrown.

• This method sets the session using an access_token and refresh_token.
• If successful, a SIGNED_IN event is emitted.

Log in an existing user by exchanging an Auth Code issued during the PKCE flow.

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

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.

• Currently, totp is the only supported factor_type. 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.challenge_and_verify().

• An enrolled factor is required before creating a challenge.
• To verify a challenge, see mfa.verify().

• To verify a challenge, please create a challenge first.

• An enrolled factor is required before invoking challengeAndVerify().
• Executes mfa.challenge() and mfa.verify() in a single step.

• 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 next_level field will return aal2, else, it will return aal1.

• Any method under the supabase.auth.admin namespace requires a service_role key.
• These methods are considered admin methods and should be called on a trusted server. Never expose your service_role key in the browser.

• Fetches the user object from the database based on the user's id.
• The get_user_by_id() method requires the user's id which maps to the auth.users.id column.

• Defaults to return 50 users per page.

• To confirm the user's email address or phone number, set email_confirm or phone_confirm to true. Both arguments default to false.
• create_user() will not send a confirmation email to the user. You can use invite_user_by_email() if you want to send them an email invite instead.
• If you are sure that the created user's email or phone number is legitimate and verified, you can set the email_confirm or phone_confirm param to true.

Delete a user. Requires a service_role key.

• The delete_user() method requires the user's ID, which maps to the auth.users.id column.

Sends an invite link to an email address.

• Sends an invite link to the user's email address.
• The invite_user_by_email() method is typically used by administrators to invite users to join the application.
• Note that PKCE is not supported when using invite_user_by_email. This is because the browser initiating the invite is often different from the browser accepting the invite which makes it difficult to provide the security guarantees required of the PKCE flow.

• The following types can be passed into generate_link(): signup, magiclink, invite, recovery, email_change_current, email_change_new, phone_change.
• generate_link() only generates the email link for email_change_email if the Secure email change is enabled in your project's email auth provider settings.
• generate_link() handles the creation of the user for signup, invite and magiclink.

Deletes a factor on a user. This will log the user out of all active sessions if the deleted factor was verified.

Invoke a Supabase Function.

• Requires an Authorization header.
• When you pass in a body to your function, we automatically attach the Content-Type header for Blob, ArrayBuffer, File, FormData and String. If it doesn't match any of these types we assume the payload is json, serialise 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.

Realtime in Python only works with the asynchronous client. You can initialize a new Supabase client using the acreate_client() method.

• Some Realtime methods are asynchronous and must be awaited. Ensure these methods are called within an async function.
• In the following Realtime examples, certain methods are awaited. These should be enclosed within an async function.
• When an asynchronous method needs to be used within a synchronous context, such as the callback for .subscribe(), utilize asyncio.create_task() to schedule the coroutine. This is why the acreate_client example includes an import of asyncio.

• 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.

• 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.

• 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.

Broadcast a message to all connected clients to a channel.

Creates a new Storage bucket

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

Retrieves the details of an existing Storage bucket.

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

Retrieves the details of all Storage buckets within an existing project.

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