JavaScript Client Library

Create a new client for use in the browser.

You can initialize a new Supabase client using the createClient() 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.

Perform a SELECT query on the table or view.

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

Perform an INSERT into the table or view.

By default, inserted rows are not returned. To return it, chain the call with .select().

Perform an UPDATE on the table or view.

By default, updated rows are not returned. To return it, chain the call with .select() after filters.

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

Perform an UPSERT on the table or view. Depending on the column(s) passed to onConflict, .upsert() allows you to perform the equivalent of .insert() if a row with the corresponding onConflict columns doesn't exist, or if it does exist, perform an alternative action depending on ignoreDuplicates.

By default, upserted rows are not returned. To return it, chain the call with .select().

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

Perform a DELETE on the table or view.

By default, deleted rows are not returned. To return it, chain the call with .select() after filters.

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

Perform a function call.

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;

To call Postgres functions on Read Replicas, use the get: true option.

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.

To check if the value of column is NULL, you should use .is() instead.

Match only rows where column is not equal to value.

Match only rows where column is greater 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.

For non-boolean columns, this is only relevant for checking if the value of column is NULL by setting value to null.

For boolean columns, you can also set value to true or false and it will behave the same way as .eq().

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 either contained in range or 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.

Unlike most filters, opearator and value are used as-is and need to follow PostgREST syntax. You also need to make sure they are properly sanitized.

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

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

Match only rows which satisfy at least one of the filters.

Unlike most filters, filters is used as-is and needs to follow PostgREST syntax. You also need to make sure it's properly sanitized.

It's currently not possible to do an .or() filter across multiple tables.

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()`

Match only rows which satisfy the filter. This is an escape hatch - you should use the specific filter methods wherever possible.

Unlike most filters, opearator and value are used as-is and need to follow PostgREST syntax. You also need to make sure they are properly sanitized.

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

Perform a SELECT on the query result.

By default, .insert(), .update(), .upsert(), and .delete() do not return modified rows. By calling this method, modified rows are returned in data.

Order the query result by column.

You can call this method multiple times to order by multiple columns.

You can order referenced tables, but it only affects the ordering of the parent table if you use !inner in the query.

Limit the query result by count.

Limit the query result by starting at an offset from and ending at the offset to. 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 from and to values are 0-based and inclusive: range(1, 3) will include the second, third and fourth rows of the query.

Set the AbortSignal for the fetch request.

You can use this to set a timeout for the request.

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

Query result must be one row (e.g. using .limit(1)), otherwise this returns an error.

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

Query result must be zero or one row (e.g. using .limit(1)), otherwise this returns an error.

Return data as a string in CSV format.

Override the type of the returned data.

• Deprecated: use overrideTypes method instead

Override the type of the returned data field in the response.

Return data as the EXPLAIN plan for the query.

You need to enable the db_plan_enabled setting before using this method.

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 persistSession to true and attempts to store the session in local storage. When using the supabase client in an environment that doesn't support local storage, you might notice the following warning message being logged:

  No storage option exists to persist the session, which may result in unexpected behavior when using auth. If you want to set persistSession to true, please provide a storage option or you may set persistSession to false to disable this warning.

  This warning message can be safely ignored if you're not using auth on the server-side. If you are using auth and you want to set persistSession to true, you will need to provide a custom storage implementation that follows this interface.

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

Creates a new user.

Be aware that if a user account exists in the system you may get back an error message that attempts to hide this information from the user. This method has support for PKCE via email signups. The PKCE flow cannot be used when autoconfirm is enabled.

• 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:
  • 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 getUser().

Receive a notification every time an auth event happens.

• Subscribes to important events occurring on the user's session.
• Use on the frontend/client. It is less useful on the server.
• Events are emitted across tabs to keep your application's UI up-to-date. Some events can fire very frequently, based on the number of tabs open. Use a quick and efficient callback function, and defer or debounce as many operations as you can to be performed outside of the callback.
• Important: A callback can be an async function and it runs synchronously during the processing of the changes causing the event. You can easily create a dead-lock by using await on a call to another method of the Supabase library.
  • Avoid using async functions as callbacks.
  • Limit the number of await calls in async callbacks.
  • Do not use other Supabase functions in the callback function. If you must, dispatch the functions once the callback has finished executing. Use this as a quick way to achieve this:

    1
    2
    3
    4
    5
    6
    supabase.auth.onAuthStateChange((event, session) => {  setTimeout(async () => {    // await on other Supabase function here    // this runs right after the callback has finished  }, 0)})

• Emitted events:
  • INITIAL_SESSION
    • Emitted right after the Supabase client is constructed and the initial session from storage is loaded.
  • SIGNED_IN
    • Emitted each time a user session is confirmed or re-established, including on user sign in and when refocusing a tab.
    • Avoid making assumptions as to when this event is fired, this may occur even when the user is already signed in. Instead, check the user object attached to the event to see if a new user has signed in and update your application's UI.
    • This event can fire very frequently depending on the number of tabs open in your application.
  • SIGNED_OUT
    • Emitted when the user signs out. This can be after:
      • A call to supabase.auth.signOut().
      • After the user's session has expired for any reason:
        • User has signed out on another device.
        • The session has reached its timebox limit or inactivity timeout.
        • User has signed in on another device with single session per user enabled.
        • Check the User Sessions docs for more information.
    • Use this to clean up any local storage your application has associated with the user.
  • TOKEN_REFRESHED
    • Emitted each time a new access and refresh token are fetched for the signed in user.
    • It's best practice and highly recommended to extract the access token (JWT) and store it in memory for further use in your application.
      • Avoid frequent calls to supabase.auth.getSession() for the same purpose.
    • There is a background process that keeps track of when the session should be refreshed so you will always receive valid tokens by listening to this event.
    • The frequency of this event is related to the JWT expiry limit configured on your project.
  • USER_UPDATED
    • Emitted each time the supabase.auth.updateUser() method finishes successfully. Listen to it to update your application's UI based on new profile information.
  • PASSWORD_RECOVERY
    • Emitted instead of the SIGNED_IN event when the user lands on a page that includes a password recovery link in the URL.
    • Use it to show a UI to the user where they can reset their password.

Creates a new anonymous 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.

Be aware that you may get back an error message that will not distinguish between the cases where the account does not exist or that the email/phone and password combination is wrong or that the account can only be accessed via social login.

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

• Use an ID token to sign in.
• Especially useful when implementing sign in using native platform dialogs in mobile or desktop apps using Sign in with Apple or Sign in with Google on iOS and Android.
• You can also use Google's One Tap and Automatic sign-in via this API.

Log in a user using magiclink or a one-time password (OTP).

If the {{ .ConfirmationURL }} variable is specified in the email template, a magiclink will be sent. If the {{ .Token }} variable is specified in the email template, an OTP will be sent. If you're using phone sign-ins, only an OTP will be sent. You won't be able to send a magiclink for phone sign-ins.

Be aware that you may get back an error message that will not distinguish between the cases where the account does not exist or, that the account can only be accessed via social login.

Do note that you will need to configure a Whatsapp sender on Twilio if you are using phone sign in with the 'whatsapp' channel. The whatsapp channel is not supported on other providers at this time. This method supports PKCE when an email is passed.

• 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, signInWithOtp() will signup the user instead. To restrict this behavior, you can set shouldCreateUser 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 }}.
• See our Twilio Phone Auth Guide for details about configuring WhatsApp sign in.

Log in an existing user via a third-party provider. This method supports the PKCE flow.

• This method is used for signing in using Social Login (OAuth) providers.
• It works by redirecting your application to the provider's authorization screen, before bringing back the user to your app.

Attempts a single-sign on using an enterprise Identity Provider. A successful SSO attempt will redirect the current page to the identity provider authorization page. The redirect URL is implementation and SSO protocol specific.

You can use it by providing a SSO domain. Typically you can extract this domain by asking users for their email address. If this domain is registered on the Auth instance the redirect will use that organization's currently active SSO Identity Provider for the login.

If you have built an organization-specific login page, you can use the organization's SSO Identity Provider UUID directly instead.

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