From bdfd69e9554a1f9fb76d0aee3b57d5eec5ac3dbe Mon Sep 17 00:00:00 2001
From: Katerina Skroumpelou <mandarini@users.noreply.github.com>
Date: Thu, 3 Sep 2026 19:19:22 +0300
Subject: [PATCH] docs(api): note db.schema generic requirement for TS (#49967)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a note to the "Using Custom Schemas" guide:
`createClient<Database>(...)` needs the schema passed as the second
generic (`createClient<Database, 'myschema'>(...)`) to type-check
`db.schema` against anything but `public`.
`supabase.schema('myschema').from(...)` is the per-call alternative that
needs no second generic.

Related to supabase/supabase-js#969 — the existing JS example has no
type parameters so it never surfaces this, and TypeScript users
extending it with `<Database>` hit a confusing compile error with no
pointer to the fix.

supabase-js companion: supabase/supabase-js#2662

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Added guidance to the custom schemas guide explaining TypeScript
typing behavior when using non-public schemas.
* Clarified how to specify a schema explicitly and when schema types are
inferred automatically.
* Noted that custom schemas must be included in the generated `Database`
type.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 apps/docs/content/guides/api/using-custom-schemas.mdx | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/apps/docs/content/guides/api/using-custom-schemas.mdx b/apps/docs/content/guides/api/using-custom-schemas.mdx
index 9b431d22385d4..dc788a700250d 100644
--- a/apps/docs/content/guides/api/using-custom-schemas.mdx
+++ b/apps/docs/content/guides/api/using-custom-schemas.mdx
@@ -56,6 +56,12 @@ const { data: todos, error } = await supabase.from('todos').select('*')
 const { data: todos, error } = await supabase.schema('myschema').from('todos').select('*')
 ```
 
+<Admonition type="note">
+
+With generated `Database` types that include `public`, `createClient<Database>(...)` type-checks `db.schema` against `public` only, unless the schema name is also passed as the second generic: `createClient<Database, 'myschema'>(...)`. `supabase.schema('myschema').from(...)` infers its schema per call and needs no second generic. In both cases `myschema` has to be present in the generated `Database` type.
+
+</Admonition>
+
 </TabPanel>
 <$Show if="sdk:dart">
 <TabPanel id="dart" label="Dart">