From feecf1f1216a850b69b443f6efbcb41ccd59a361 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20Caba=C3=A7o?= <filipe@supabase.io>
Date: Tue, 16 Dec 2025 09:08:27 +0000
Subject: [PATCH] docs: add warning regarding db-pre-request usage (#41354)

---
 .../_partials/db_pre_request_warning.mdx      | 31 +++++++++++++++++++
 .../content/guides/api/securing-your-api.mdx  |  6 ++++
 .../guides/database/debugging-performance.mdx |  2 ++
 3 files changed, 39 insertions(+)
 create mode 100644 apps/docs/content/_partials/db_pre_request_warning.mdx

diff --git a/apps/docs/content/_partials/db_pre_request_warning.mdx b/apps/docs/content/_partials/db_pre_request_warning.mdx
new file mode 100644
index 00000000000..0b61bc21917
--- /dev/null
+++ b/apps/docs/content/_partials/db_pre_request_warning.mdx
@@ -0,0 +1,31 @@
+<Admonition type="caution">
+
+The `pgrst.db_pre_request` configuration only works with the **Data API** (PostgREST). It does not work with Realtime, Storage, or other Supabase products.
+
+If you're using `db_pre_request` to call a function (like `set_information()`) that sets up context or performs checks on every request, and you need similar behavior for other Supabase products, you must call the function directly in your Row Level Security (RLS) policies instead.
+
+**Example:**
+
+If you have a `db_pre_request` function that calls `set_information()` that returns `true` to set up context or perform checks, and you have an RLS policy like:
+
+```sql
+create policy "Individuals can view their own todos."
+on todos for select
+using ( (select auth.uid()) = user_id );
+```
+
+To achieve the same behavior with other Supabase products, you need to call the function directly in your RLS policy:
+
+```sql
+create policy "Individuals can view their own todos."
+on todos for select
+using ( set_information() AND (select auth.uid()) = user_id );
+```
+
+This ensures the function is called when evaluating RLS policies for all products, not just Data API requests.
+
+**Performance consideration:**
+
+Be aware that calling functions directly in RLS policies can impact database performance, as the function is evaluated for each row when the policy is checked. Consider optimizing your function or using caching strategies if performance becomes an issue.
+
+</Admonition>
diff --git a/apps/docs/content/guides/api/securing-your-api.mdx b/apps/docs/content/guides/api/securing-your-api.mdx
index c106c2bbded..32274596639 100644
--- a/apps/docs/content/guides/api/securing-your-api.mdx
+++ b/apps/docs/content/guides/api/securing-your-api.mdx
@@ -97,6 +97,8 @@ This configures the `public.check_request` function to run on every Data API req
 notify pgrst, 'reload config';
 ```
 
+<$Partial path="db_pre_request_warning.mdx" />
+
 Inside the function you can perform any additional checks on the request headers or JWT and raise an exception to prevent the request from completing. For example, this exception raises a HTTP 402 Payment Required response with a `hint` and additional `X-Powered-By` header:
 
 ```sql
@@ -249,6 +251,8 @@ alter role authenticator
 notify pgrst, 'reload config';
 ```
 
+<$Partial path="db_pre_request_warning.mdx" />
+
 To clear old entries in the `private.rate_limits` table, set up a [pg_cron](/docs/guides/database/extensions/pg_cron) job to clean them up.
 
 </TabPanel>
@@ -329,6 +333,8 @@ alter role authenticator
 notify pgrst, 'reload config';
 ```
 
+<$Partial path="db_pre_request_warning.mdx" />
+
 </TabPanel>
 
 </Tabs>
diff --git a/apps/docs/content/guides/database/debugging-performance.mdx b/apps/docs/content/guides/database/debugging-performance.mdx
index 2a7a64dbc52..a2f349d7547 100644
--- a/apps/docs/content/guides/database/debugging-performance.mdx
+++ b/apps/docs/content/guides/database/debugging-performance.mdx
@@ -88,6 +88,8 @@ alter role authenticator set pgrst.db_pre_request to 'filter_plan_requests';
 notify pgrst, 'reload config';
 ```
 
+<$Partial path="db_pre_request_warning.mdx" />
+
 Replace `'123.123.123.123'` with your actual IP address.
 
 ## Disabling explain