JavaScript Client Library

Create a new client for use in the browser.

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

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

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 included in the values array.

• For more information, see Postgres full text search.

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

1
.not('id', 'in', '(5,6,7)')  // Use `()` for `in` filter
2
.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
.or('id.in.(5,6,7), arraycol.cs.{"a","b"}')  // Use `()` for `in` filter, `{}` for array values and `cs` for `contains()`.
2
.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
.filter('id', 'in', '(5,6,7)')  // Use `()` for `in` filter
2
.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.

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.

• 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. Safe to use without an async function as callback.

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