From 2133134daaa2460851a8e66f9f345bb1bc3ab558 Mon Sep 17 00:00:00 2001 From: Guilherme Souza Date: Fri, 8 May 2026 15:12:30 -0300 Subject: [PATCH] docs: update SDK reference docs from recent SDK changes (#45716) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Updates reference docs based on recent **stable** releases across supabase-js, supabase-flutter, and supabase-py. Only changes that landed in a stable tag are documented. ## Changes analyzed | SDK | Repo | Stable tag range | Notes | |-----|------|-----------------|-------| | js | supabase/supabase-js | `v2.105.0` → `v2.105.3` | Bug fixes and type improvements; no doc-worthy API changes | | dart | supabase/supabase-flutter | → `supabase_flutter-v2.13.0` | `anonKey` deprecated → `publishableKey` | | py | supabase/supabase-py | `v2.29.0` → `v2.30.0` | New: `.select()` chaining on write builders | | swift | supabase/supabase-swift | `v2.46.0` | Dependency bumps only | | kt | supabase-community/supabase-kt | `3.6.0` | Test coverage improvements only | | csharp | supabase-community/supabase-csharp | `v1.1.2` | No changes | > **Note**: The JS `storage.from().exists()` breaking behavior change and `PostgrestError instanceof` fix were intentionally excluded — they are only in the `v3.0.0-next` pre-release branch, not in any stable `v2.x` tag. ## Documentation updates ### `apps/docs/spec/supabase_dart_v2.yml` - Rename `anonKey` parameter → `publishableKey` in `Supabase.initialize()` to match the deprecation in [supabase-flutter#1360](https://github.com/supabase/supabase-flutter/pull/1360) (landed in `supabase_flutter-v2.13.0`) - Update Flutter example to use `publishableKey:` named argument - Note that `anonKey` is still accepted but deprecated ### `apps/docs/spec/supabase_py_v2.yml` - Add `.select()` chaining examples to `insert()`, `update()`, `upsert()`, and `delete()` write builders, newly supported in [supabase-py v2.30.0](https://github.com/supabase/supabase-py/pull/1383) - Add notes to each write method mentioning select chaining capability --- 🤖 Generated with [Claude Code](https://claude.com/claude-code) ## Summary by CodeRabbit ## Release Notes * **Documentation** * Dart SDK: Updated client initialization to use `publishableKey` parameter; deprecated `anonKey` remains supported for backward compatibility. * Python SDK: Added examples demonstrating how to chain `.select()` with write operations (`insert()`, `update()`, `upsert()`, `delete()`) to retrieve specific columns from modified rows. --------- Co-authored-by: Claude Sonnet 4.6 --- apps/docs/spec/supabase_dart_v2.yml | 8 +- apps/docs/spec/supabase_py_v2.yml | 142 ++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+), 4 deletions(-) diff --git a/apps/docs/spec/supabase_dart_v2.yml b/apps/docs/spec/supabase_dart_v2.yml index 2c646dac149..2f17b096cad 100644 --- a/apps/docs/spec/supabase_dart_v2.yml +++ b/apps/docs/spec/supabase_dart_v2.yml @@ -26,10 +26,10 @@ functions: isOptional: false type: string description: The unique Supabase URL which is supplied when you create a new project in your project dashboard. - - name: anonKey + - name: publishableKey isOptional: false type: string - description: The unique Supabase Key which is supplied when you create a new project in your project dashboard. + description: The publishable (anon) key supplied when you create a new project in your project dashboard. Use this for client-side apps. The deprecated `anonKey` parameter is still accepted but `publishableKey` takes precedence when both are supplied. - name: headers isOptional: true type: Map @@ -94,7 +94,7 @@ functions: Future main() async { await Supabase.initialize( url: 'https://xyzcompany.supabase.co', - anonKey: 'publishable-or-anon-key', + publishableKey: 'your-publishable-key', ); runApp(MyApp()); @@ -109,7 +109,7 @@ functions: ```dart final supabase = SupabaseClient( 'https://xyzcompany.supabase.co', - 'publishable-or-anon-key', + 'your-secret-key', // use your secret key for server-side usage ); ``` diff --git a/apps/docs/spec/supabase_py_v2.yml b/apps/docs/spec/supabase_py_v2.yml index f3f22a14401..a6905395a50 100644 --- a/apps/docs/spec/supabase_py_v2.yml +++ b/apps/docs/spec/supabase_py_v2.yml @@ -3706,6 +3706,8 @@ functions: - id: insert title: 'Create data: insert()' + notes: | + - Chain `.select()` after `insert()` to return specific columns from the inserted row(s). params: - name: json isOptional: false @@ -3796,10 +3798,41 @@ functions: A bulk create operation is handled in a single transaction. If any of the inserts fail, none of the rows are inserted. hideCodeBlock: true + - id: insert-with-select + name: Insert and return selected columns + code: | + ```python + response = ( + supabase.table("planets") + .insert({"id": 1, "name": "Pluto"}) + .select("id, name") + .execute() + ) + ``` + data: + sql: | + ```sql + create table + planets (id int8 primary key, name text); + ``` + response: | + ```json + { + "data": [ + { + "id": 1, + "name": "Pluto" + } + ], + "count": null + } + ``` + hideCodeBlock: true - id: update title: 'Modify data: update()' notes: | - `update()` should always be combined with [Filters](/docs/reference/python/using-filters) to target the item(s) you wish to update. + - Chain `.select()` after `update()` to return specific columns from the updated row(s). params: - name: json isOptional: false @@ -3891,10 +3924,47 @@ functions: description: | Postgres offers some [operators](/docs/guides/database/json#query-the-jsonb-data) for working with JSON data. Currently, it is only possible to update the entire JSON document. hideCodeBlock: true + - id: update-with-select + name: Update and return selected columns + code: | + ```python + response = ( + supabase.table("instruments") + .update({"name": "piano"}) + .eq("id", 1) + .select("id, name") + .execute() + ) + ``` + data: + sql: | + ```sql + create table + instruments (id int8 primary key, name text); + + insert into + instruments (id, name) + values + (1, 'harpsichord'); + ``` + response: | + ```json + { + "data": [ + { + "id": 1, + "name": "piano" + } + ], + "count": null + } + ``` + hideCodeBlock: true - id: upsert title: 'Upsert data: upsert()' notes: | - Primary keys must be included in the `values` dict to use upsert. + - Chain `.select()` after `upsert()` to return specific columns from the upserted row(s). params: - name: json isOptional: false @@ -4041,6 +4111,41 @@ functions: In the following query, `upsert()` implicitly uses the `id`(primary key) column to determine conflicts. If there is no existing row with the same `id`, `upsert()` inserts a new row, which will fail in this case as there is already a row with `handle` `"saoirse"`. Using the `on_conflict` option, you can instruct `upsert()` to use another column with a unique constraint to determine conflicts. hideCodeBlock: true + - id: upsert-with-select + name: Upsert and return selected columns + code: | + ```python + response = ( + supabase.table("instruments") + .upsert({"id": 1, "name": "piano"}) + .select("id, name") + .execute() + ) + ``` + data: + sql: | + ```sql + create table + instruments (id int8 primary key, name text); + + insert into + instruments (id, name) + values + (1, 'harpsichord'); + ``` + response: | + ```json + { + "data": [ + { + "id": 1, + "name": "piano" + } + ], + "count": null + } + ``` + hideCodeBlock: true - id: delete title: 'Delete data: delete()' @@ -4052,6 +4157,7 @@ functions: 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. + - Chain `.select()` after `delete()` to return specific columns from the deleted row(s). params: - name: count isOptional: true @@ -4142,6 +4248,42 @@ functions: ``` hideCodeBlock: false isSpotlight: false + - id: delete-with-select + name: Delete and return selected columns + code: | + ```python + response = ( + supabase.table("countries") + .delete() + .eq("id", 1) + .select("id, name") + .execute() + ) + ``` + data: + sql: | + ```sql + create table + countries (id int8 primary key, name text); + + insert into + countries (id, name) + values + (1, 'Mordor'); + ``` + response: | + ```json + { + "data": [ + { + "id": 1, + "name": "Mordor" + } + ], + "count": null + } + ``` + hideCodeBlock: true - id: rpc title: 'Postgres functions: rpc()'