The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs: update SDK reference docs and guides from recent SDK changes (#44629)
Guilherme Souza61578be9b305
diff --git a/apps/docs/content/guides/api/automatic-retries-in-supabase-js.mdx b/apps/docs/content/guides/api/automatic-retries-in-supabase-js.mdxindex 094f4b25a40..cc9e2692bb1 100644--- a/apps/docs/content/guides/api/automatic-retries-in-supabase-js.mdx+++ b/apps/docs/content/guides/api/automatic-retries-in-supabase-js.mdx@@ -1,7 +1,7 @@---id: automatic-retries-in-supabase-jstitle: 'How to do automatic retries with `supabase-js`'-subtitle: 'Learn how to add automatic retries to your Supabase API requests using `fetch-retry`.'+subtitle: 'Learn how to configure automatic retries for your Supabase API requests.'---<Admonition type="danger" title="Important">@@ -10,9 +10,31 @@ You should only enable retries if your requests fail with network errors (e.g. 5</Admonition>-The `fetch-retry` package allows you to add retry logic to `fetch` requests, making it a useful tool for enhancing the resilience of API calls in your Supabase applications. Here's a step-by-step guide on how to integrate `fetch-retry` with the `supabase-js` library.+## Built-in retries for PostgREST queries-## 1. Install dependencies+Starting with `supabase-js` v2.102.0, PostgREST queries (`.from()`, `.rpc()`) include built-in automatic retries for transient errors. Retries are **enabled by default** and use exponential backoff with jitter.++Retryable errors include HTTP status codes 408 (Request Timeout), 409 (Conflict), 503 (Service Unavailable), and 504 (Gateway Timeout), as well as network failures. Only idempotent HTTP methods (GET, HEAD, OPTIONS) and POST requests (used by PostgREST) are retried.++### Disable built-in retries++If you prefer to handle retries yourself, you can disable the built-in retry behavior:++```javascript+import { createClient } from '@supabase/supabase-js'++const supabase = createClient('https://your-supabase-url.supabase.co', 'your-anon-key', {+ db: {+ retry: false,+ },+})+```++## Custom retries with `fetch-retry`++For more control over retry behavior, or to add retries to non-PostgREST requests (auth, storage, functions), you can use the `fetch-retry` package. This approach wraps the native `fetch` function and applies to all requests made by the client.++### 1. Install dependenciesTo get started, ensure you have both `supabase-js` and `fetch-retry` installed in your project:@@ -20,7 +42,7 @@ To get started, ensure you have both `supabase-js` and `fetch-retry` installed inpm install @supabase/supabase-js fetch-retry```-## 2. Wrap the fetch function+### 2. Wrap the fetch functionThe `fetch-retry` package works by wrapping the native `fetch` function. You can create a custom fetch instance with retry logic and pass it to the `supabase-js` client.@@ -43,7 +65,7 @@ const supabase = createClient()```-## 3. Configure retry options+### 3. Configure retry optionsYou can configure `fetch-retry` options to control retry behavior, such as the number of retries, retry delay, and which errors should trigger a retry.@@ -59,7 +81,7 @@ const fetchWithRetry = fetchRetry(fetch, {In this example, the `retryDelay` function implements an exponential backoff strategy, and retries are triggered only for specific HTTP status codes.-## 4. Using the Supabase client+### 4. Using the Supabase clientWith `fetch-retry` integrated, you can use the Supabase client as usual. The retry logic will automatically apply to all network requests made by `supabase-js`.@@ -77,7 +99,7 @@ async function fetchData() {fetchData()```-## 5. Fine-Tuning retries for specific requests+### 5. Fine-tuning retries for specific requestsIf you need different retry logic for certain requests, you can use the `retryOn` with a custom function to inspect the URL or response and decide whether to retry the request.@@ -119,4 +141,4 @@ By using `retryOn` with a custom function, you can define specific conditions fo## Conclusion-Integrating `fetch-retry` with `supabase-js` is a straightforward way to add robustness to your Supabase API requests. By handling transient errors and implementing retry strategies, you can improve the reliability of your application while maintaining a seamless user experience.+For most use cases, the built-in PostgREST retry mechanism is sufficient. Use `fetch-retry` when you need retries on non-PostgREST requests or need fine-grained control over retry behavior.diff --git a/apps/docs/content/guides/auth/passwords.mdx b/apps/docs/content/guides/auth/passwords.mdxindex 8675ed00a4e..286d074c91a 100644--- a/apps/docs/content/guides/auth/passwords.mdx+++ b/apps/docs/content/guides/auth/passwords.mdx@@ -1028,6 +1028,41 @@ final UserResponse res = await supabase.auth.updateUser(</$Show></Tabs>+#### Verifying the current password++If your app requires users to confirm their current password before setting a new one, you can pass `currentPassword` (available in `supabase-js` v2.102.0+ and `supabase-kt` 3.5.0+):++<Tabs+ scrollable+ size="small"+ type="underlined"+ defaultActiveId="js"+ queryGroup="language"+>+<TabPanel id="js" label="JavaScript">++```js+await supabase.auth.updateUser({+ password: 'new_password',+ currentPassword: 'old_password',+})+```++</TabPanel>+<$Show if="sdk:kotlin">+<TabPanel id="kotlin" label="Kotlin">++```kotlin+supabase.auth.updateUser {+ password = "new_password"+ currentPassword = "old_password"+}+```++</TabPanel>+</$Show>+</Tabs>+### Email sendingThe signup confirmation and password reset flows require an SMTP server to send emails.diff --git a/apps/docs/spec/supabase_dart_v2.yml b/apps/docs/spec/supabase_dart_v2.ymlindex e773d77b1ae..ded7a29ea76 100644--- a/apps/docs/spec/supabase_dart_v2.yml+++ b/apps/docs/spec/supabase_dart_v2.yml@@ -82,6 +82,10 @@ functions:isOptional: truetype: intdescription: The number of times to retry a failed upload request. Defaults to `0`.+ - name: useNewHostname+ isOptional: true+ type: bool+ description: Whether to rewrite legacy storage URLs to use the dedicated storage host (`<ref>.storage.supabase.co`). Set to `true` only if your project has the dedicated storage host enabled. Defaults to `false`.examples:- id: flutter-initializename: For Flutter@@ -790,6 +794,18 @@ functions:kIsWeb ? LaunchMode.platformDefault : LaunchMode.externalApplication, // Launch the auth screen in a new webview on mobile.);```+ - id: sign-in-with-custom-provider+ name: Sign in with a custom OIDC provider+ description: |+ `OAuthProvider` is now a class instead of an enum, allowing you to use custom OIDC providers by passing a custom provider string.+ isSpotlight: false+ code: |+ ```dart+ await supabase.auth.signInWithOAuth(+ OAuthProvider('custom:my-oidc-provider'),+ redirectTo: kIsWeb ? null : 'my.scheme://my-host',+ );+ ```- id: sign-in-using-a-third-party-provider-with-redirectname: With `redirectTo`description: |@@ -1579,6 +1595,10 @@ functions:isOptional: falsetype: Stringdescription: Refresh token to use to get a new session.+ - name: accessToken+ isOptional: true+ type: String+ description: Optional access token to set along with the refresh token.examples:- id: refresh-the-sessionname: Refresh the session@@ -1591,6 +1611,17 @@ functions:final session = res.session;```+ - id: set-session-with-access-token+ name: Set session with access token+ description: You can optionally provide an access token along with the refresh token.+ isSpotlight: false+ code: |+ ```dart+ final AuthResponse response = await supabase.auth.setSession(+ refreshToken,+ accessToken: accessToken,+ );+ ```response: |```jsonAuthResponse(diff --git a/apps/docs/spec/supabase_js_v2.yml b/apps/docs/spec/supabase_js_v2.ymlindex 7ea66fd0fff..6b2d34c52d8 100644--- a/apps/docs/spec/supabase_js_v2.yml+++ b/apps/docs/spec/supabase_js_v2.yml@@ -169,6 +169,22 @@ functions:$ref: '@supabase/auth-js.GoTrueAdminMFAApi.listFactors'- id: mfa-delete-factor$ref: '@supabase/auth-js.GoTrueAdminMFAApi.deleteFactor'+ - id: admin-custom-providers-api+ title: Custom OIDC/OAuth Provider Admin API+ notes: |+ - These methods allow you to manage custom OIDC/OAuth providers programmatically.+ - Requires `service_role` key.+ - Custom providers use the `custom:` prefix when signing in (e.g., `custom:my-oidc-provider`).+ - id: admin-custom-providers-create+ $ref: '@supabase/auth-js.GoTrueAdminCustomProvidersApi.createProvider'+ - id: admin-custom-providers-list+ $ref: '@supabase/auth-js.GoTrueAdminCustomProvidersApi.listProviders'+ - id: admin-custom-providers-get+ $ref: '@supabase/auth-js.GoTrueAdminCustomProvidersApi.getProvider'+ - id: admin-custom-providers-update+ $ref: '@supabase/auth-js.GoTrueAdminCustomProvidersApi.updateProvider'+ - id: admin-custom-providers-delete+ $ref: '@supabase/auth-js.GoTrueAdminCustomProvidersApi.deleteProvider'- id: select$ref: '@supabase/postgrest-js.PostgrestQueryBuilder.select'- id: insertdiff --git a/apps/docs/spec/supabase_kt_v3.yml b/apps/docs/spec/supabase_kt_v3.ymlindex 21ae35af3ca..da063dded1d 100644--- a/apps/docs/spec/supabase_kt_v3.yml+++ b/apps/docs/spec/supabase_kt_v3.yml@@ -218,6 +218,10 @@ functions:`customUrl` - Custom url for the PostgREST API. Can be safely ignored when using Supabase. Default: `null``jwtToken` - Plugin specific JWT Token. Can be ignored when using the Auth plugin. Default: `null`++ `urlLengthLimit` - The maximum URL length for requests. When exceeded, the request is automatically sent as POST with query parameters in the body. Default: `null` (unlimited)++ `timeout` - The timeout for PostgREST requests. Default: `30.seconds`- id: configure-storagename: Configure Storage modulecode: |@@ -3569,6 +3573,10 @@ functions:isOptional: truetype: JsonObjectdescription: The new user data.+ - name: currentPassword+ isOptional: true+ type: String?+ description: The current password. Required when reauthentication is needed to change the password.examples:- id: update-the-email-for-an-authenticated-username: Update the email for an authenticated user@@ -4621,6 +4629,27 @@ functions:```description: |The return type of the invoking methods is an `HttpResponse`. You can access the response body via `response.body<T>()`, where `T` can be any serializable type.+ - id: invoke-with-streaming+ name: Invoke with streaming (SSE)+ description: |+ You can invoke edge functions that return Server-Sent Events (SSE) and consume them as a Kotlin Flow.+ isSpotlight: true+ code: |+ ```kotlin+ val function = supabase.functions.buildEdgeFunction("streaming-function")++ // Collect SSE events as a Flow+ function.collectAsFlow(+ body = buildJsonObject {+ put("prompt", "Hello!")+ }+ ).collect { event ->+ println("Event: ${event.event}")+ println("Data: ${event.data}")+ // Decode typed data+ val response = event.decodeAs<MyResponse>()+ }+ ```- id: reuse-functionname: Reuse function by saving it to a variableisSpotlight: truediff --git a/apps/docs/spec/supabase_swift_v2.yml b/apps/docs/spec/supabase_swift_v2.ymlindex 21c302bda5e..9efeef86d6f 100644--- a/apps/docs/spec/supabase_swift_v2.yml+++ b/apps/docs/spec/supabase_swift_v2.yml@@ -53,6 +53,25 @@ functions:))```+ - id: initialize-client-with-retries+ name: Initialize Client with automatic retries+ description: |+ PostgREST requests automatically retry on transient errors (HTTP 408, 409, 503, 504 and network failures) with exponential backoff. Retries are enabled by default and can be disabled per client.+ code: |+ ```swift+ import Supabase++ let supabase = SupabaseClient(+ supabaseURL: URL(string: "https://xyzcompany.supabase.co")!,+ supabaseKey: "publishable-or-anon-key",+ options: SupabaseClientOptions(+ db: .init(+ // Disable automatic retries for this client+ retryEnabled: false+ )+ )+ )+ ```- id: initialize-client-with-loggingname: Initialize Client with Loggingcode: |@@ -4393,6 +4412,7 @@ functions:- 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.- Use AsyncStream or callbacks for listening to changes.+ - Presence and Postgres change callbacks must be registered **before** calling `subscribe()`. Attempting to add them after the channel is subscribing or subscribed will trigger a warning and the callback will be rejected.examples:- id: listen-to-broadcastname: Listen to broadcast messagesdiff --git a/supa-mdx-lint/Rule003Spelling.toml b/supa-mdx-lint/Rule003Spelling.tomlindex 17499bb886a..e84afb9a48c 100644--- a/supa-mdx-lint/Rule003Spelling.toml+++ b/supa-mdx-lint/Rule003Spelling.toml@@ -318,6 +318,7 @@ allow_list = ["Redis","RedwoodJS","Refine",+ "[Rr]etryable","Roboflow","Rollup","SaaS",