docs(claude): add safe-sql-execution skill (supabase#46171)

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Docs (new Claude Code skill).

## What is the current behavior?

There is no shared, written-down reference for the SQL safety model in
Studio. The rules around `SafeSqlFragment`/`UntrustedSqlFragment`,
sanitization utilities, and how to promote snippet content live only in
code and contributor knowledge, which makes it easy for AI-assisted
changes to bypass the type-based guarantees.

## What is the new behavior?

Adds a `safe-sql-execution` skill under `.claude/skills/` that documents
the proven-authorship security model: the three classes of SQL
fragments, provenance tracking with branded types, sanitization
utilities (`ident`/`literal`/`keyword`), the `acceptUntrustedSql` rule
(event handlers only), and the special case that snippet content
(`unchecked_sql`) must never be considered safe. Includes good/bad
examples for the common patterns.

## Additional context

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

* **Documentation**
* Added a comprehensive guide on secure SQL execution in Supabase
Studio: explains provenance-based SQL safety, distinct categories of SQL
fragments, how unsafe snippets must be explicitly promoted before
execution, available sanitization helpers for user input, strict
execution constraints to prevent accidental runs, and numerous examples
demonstrating safe vs. unsafe usage and safe preview/runner patterns.

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/supabase/supabase/pull/46171?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: charislam

.claude/skills/safe-sql-execution/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: safe-sql-execution
+description: Safely execute SQL queries against a user database without risking SQL injection or other security vulnerabilities.
+---
+
+# Safe SQL execution
+
+Supabase Studio executes SQL statements directly against the user's database.
+Because this is the authenticated user's own database, our security model is
+different from most frontend applications: a user should be able to execute any
+SQL statement, as long as it is proven that they themselves authored it. What
+we SHOULD NOT ALLOW is execution of SQL statements that can be influenced by an
+attacker, such as through URL parameters.
+
+## Security model
+
+The security model for SQL execution in Supabase Studio is based on the
+principle of "proven authorship". This means that a user should only be able to
+execute SQL statements that they have explicitly authored, and not statements
+that can be influenced by external input.
+
+There are three classes of SQL fragments:
+
+1.  Hardcoded within the application code. These are safe to execute because
+    they cannot be influenced by an attacker. They can be marked with the
+    `safeSql` utility with `pg-meta`:
+
+    ```ts
+    import { safeSql } from '@supabase/pg-meta'
+
+    const sql = safeSql`
+      SELECT *
+      FROM users
+      WHERE id = 1
+    `
+    ```
+
+    `safeSql` automatically creates a string of the branded type
+    `SafeSqlFragment`. (See Provenance Tracking below.)
+
+2.  Third-party influenceable. These are SQL fragments that can be influenced
+    by an attacker, such as through URL parameters or LLM output. These should
+    be marked with the `untrustedSql` utility with `pg-meta`:
+
+    ```ts
+    import { untrustedSql } from '@supabase/pg-meta'
+
+    const unsafeQuery = searchParams.get('query')
+    const querySql = untrustedSql(unsafeQuery)
+    ```
+
+    `untrustedSql` creates a string of the branded type `UntrustedSqlFragment`.
+    (See Provenance Tracking below.)
+
+3.  User-authored. These are SQL fragments that are authored by the user
+    themselves within the UI, for example in a text input field. Because the
+    user is the author, these should be considered safe to execute.
+
+    However, there is a caveat, where third-party and user-authored code can
+    mix, contaminating the user-authored code (for example, if an input is
+    prefilled from an unsanitized URL parameter). Provenance tracking helps us
+    track these cases.
+
+    For example, a safe input component could be implemented as follows by requiring that its placeholder and controlled value are of type `SafeSqlFragment`. In this case we can use its onChange to promote the user input to `SafeSqlFragment` type, because we know that the user is the author of the input. An implementation of this is in
+    @apps/studio/components/ui/SafeSqlInput.tsx:
+
+    ```ts
+    import { rawSql, type SafeSqlFragment } from '@supabase/pg-meta'
+    import type { ChangeEvent, ComponentProps } from 'react'
+    import { Input } from 'ui-patterns/DataInputs/Input'
+
+    type InputProps = ComponentProps<typeof Input>
+
+    export type SafeSqlInputProps = Omit<
+      InputProps, 'placeholder' | 'value' | 'onChange'
+    > & {
+      placeholder?: SafeSqlFragment
+      value: SafeSqlFragment
+      onChange?:
+        (event: ChangeEvent<HTMLInputElement>, value: SafeSqlFragment) => void
+    }
+
+    export const SafeSqlInput = ({ onChange, ...props }: SafeSqlInputProps) => (
+      <Input
+        {...props}
+        onChange={(event) => onChange?.(event, rawSql(event.target.value))}
+      />
+    )
+    ```
+
+    This is pretty much the ONLY VALID USE CASE of the rawSql export from
+    pg-meta, and it should be used with caution.
+
+## Provenance tracking
+
+Branded types are used to track the provenance of SQL fragments. The types,
+exported from `pg-meta`, are:
+
+- `SafeSqlFragment`: represents SQL fragments that are safe to execute, because
+  they are either hardcoded in the application or authored by the user
+  themselves.
+- `UntrustedSqlFragment`: represents SQL fragments that can be influenced by an
+  attacker, such as through URL parameters or LLM output.
+
+These are valid ways to generate a `SafeSqlFragment`:
+
+- Using the `safeSql` utility from `pg-meta` to create hardcoded SQL fragments.
+- Using the sanitization utilities from `pg-meta` to sanitize untrusted input
+  and promote it to a `SafeSqlFragment`:
+  - `ident`
+  - `literal`
+  - `keyword`
+- Using the safe SQL manipulation utilities:
+  - `joinSqlFragments`
+  - `trimSafeSqlFragment`
+
+`UntrustedSqlFragments` can be generated from raw strings using
+`untrustedSql()`.
+
+There is also a union type, `DisplayableSqlFragment`, which represents SQL fragments that can be safely displayed in the UI, but not necessarily executed. This includes both `SafeSqlFragment` and `UntrustedSqlFragment`.
+
+## Security of SQL round-tripped from the user's database
+
+SQL derived directly from catalog tables (e.g., function definitions, RLS
+expressions, etc.) is considered safe, and it is promoted AT THE POINT OF
+BEING QUERIED from the database. In most cases, this is in an
+apps/studio/data/\*_/_.ts file, in the utility function that makes the API or
+database fetch.
+
+A critical exception to the safety of SQL round-tripped from the database is
+user snippets. These must NEVER BE CONSIDERED SAFE because they are both (a)
+externally influenceable and (b) auto-saved. The snippet type uses the
+`unchecked_sql` property, which is an `UntrustedSqlFragment`, to enforce this.
+
+## Promoting SQL fragments to `SafeSqlFragment` type
+
+Given an insecure string or `UntrustedSqlFragment`, how do we promote it safely
+to a `SafeSqlFragment`?
+
+### Sanitization utilities
+
+This is the preferred method when the input is sanitizable, e.g., it is a
+relation name, a column name, will be compared as a literal, etc.
+
+The pg-meta library provides the following sanitization utilities that can be
+used to safely promote untrusted input to `SafeSqlFragment`:
+
+- `ident`: for sanitizing identifiers such as table names or column names.
+- `literal`: for sanitizing literal values that will be used in SQL statements.
+- `keyword`: for sanitizing SQL keywords.
+
+### `acceptUntrustedSql`
+
+Some untrusted SQL fragments cannot be sanitized with the above utilities. For
+example, the `USING` expression in the RLS policy editor is an arbitrary SQL
+expression.
+
+In these cases, we can promote the SQL fragment _upon explicit user action_.
+User action indicates that the user has seen the SQL and is OK with running it.
+For example, an explicit user action could be clicking a "Run" button.
+
+The promotion happens with the `acceptUntrustedSql` utility from `pg-meta`,  
+which takes an `UntrustedSqlFragment` and returns a `SafeSqlFragment`.
+
+This utility MUST ONLY BE USED IN event handlers. It should NEVER be used in
+a useQuery, direct in the render body of a component, in a useEffect, or
+anywhere it could auto-run without explicit user action.
+
+This is safe:
+
+```ts
+import { acceptUntrustedSql } from '@supabase/pg-meta'
+
+function SafeComponent() {
+  const { mutate: execute } = useExecuteSqlMutation()
+
+  const handleRun = () => {
+    // ✅ GOOD: Safe because it is in an event handler which requires a user
+    // click
+    execute({ sql: acceptUntrustedSql(/* sql */) })
+  }
+
+  return (
+    <button onClick={handleRun}>Run</button>
+  )
+}
+```
+
+This is unsafe:
+
+```ts
+import { acceptUntrustedSql } from '@supabase/pg-meta'
+
+function UnsafeComponent() {
+  const { data } = useQuery({
+    queryKey: ['execute-sql', sql],
+    queryFn: () => {
+      // 🛑 BAD: Unsafe because it is in a query which could auto-run without
+      // explicit user action
+      return execute({ sql: acceptUntrustedSql(/* sql */) })
+    },
+  })
+}
+```
+
+## Type guarantees
+
+SQL run against the user's Postgres database runs through the `executeSql`
+function, which only takes arguments of type `SafeSqlFragment` for the SQL
+parameter. Raw strings or `UntrustedSqlFragment`s will error at compile time.
+
+## Examples
+
+### Hard-coded SQL
+
+```ts
+// ✅ GOOD: Automatically safe with `safeSql` utility
+const selectStatement = safeSql`select 1`
+```
+
+### SQL with sanitizable interpolations
+
+```ts
+// ✅ GOOD: `pg-meta` utilities sanitize the input
+const tableName = ident(userInputTableName)
+const searchString = literal(userInputSearchString)
+const sqlStatement = safeSql`
+  SELECT *
+  FROM ${tableName}
+  WHERE search_column = ${searchString}
+`
+```
+
+```ts
+// 🛑 BAD: Passing raw strings will type error
+const tableName = 'my_table'
+const sqlStatement = safeSql`
+  SELECT *
+  FROM ${tableName}
+`
+```
+
+### Non-sanitizable SQL from a user input
+
+```ts
+// ✅ GOOD: SafeSqlInput only allows a value that is a SafeSqlFragment
+import { SafeSqlInput } from '@apps/studio/components/ui/SafeSqlInput'
+
+function MyComponent() {
+  const [sql, setSql] = useState<SafeSqlFragment>(safeSql``)
+
+  return (
+    <SafeSqlInput
+      placeholder={safeSql`Enter your SQL query here...`}
+      value={sql}
+      onChange={(event, value) => setSql(value)}
+    />
+  )
+}
+```
+
+```ts
+// 🛑 BAD: This input mixes SafeSqlFragments and unsafe strings
+
+function MyBadComponent() {
+  const [sql, setSql] = useState<SafeSqlFragment>(safeSql``)
+
+  return (
+    <Input
+    // 🛑 BAD: This is unsafe because the placeholder is a raw string
+      placeholder="Enter your SQL query here..."
+      value={sql}
+      onChange={(event) => setSql(event.target.value)}
+    />
+  )
+}
+```
+
+### Round-tripping SQL from the database (NOT snippet content)
+
+```ts
+// ✅ GOOD: SQL from the database is promoted to SafeSqlFragment at the point 
+// of fetching
+
+// data/function-definitions.ts
+function markFunctionDefinitionSafe(
+  functionDefinition: FunctionDefinition
+): SafeFunctionDefinition {
+  return {
+    ...functionDefinition,
+    definition: functionDefinition.definition as SafeSqlFragment,
+  }
+}
+
+// data/function-definitions.ts
+function getFunctionDefinitions() {
+  return GET(`/function-definitions`).then((functionDefinitions) =>
+    functionDefinitions.map(markFunctionDefinitionSafe)
+  )
+}
+```
+
+```ts
+// 🛑 BAD: Strings are promoted to SafeSqlFragment in a utility function, where
+// it is impossible to easily determine the safety of the input
+
+// utils.ts
+function markFunctionDefinitionSafe(
+  functionDefinition: FunctionDefinition
+): SafeFunctionDefinition {
+  return {
+    ...functionDefinition,
+    definition: functionDefinition.definition as SafeSqlFragment,
+  }
+}
+
+// Component.ts
+function MyComponent() {
+  const { data: functionDefinitions } = useFunctionDefinitions()
+  const safeFunctionDefinitions = functionDefinitions.map(markFunctionDefinitionSafe)
+}
+```
+
+### Snippet content is ALWAYS UNSAFE
+
+Snippets are auto-persisted to the database and can be created or modified 
+through externally influenceable channels (e.g., prefilled from URL params). 
+The `unchecked_sql` property is typed as `UntrustedSqlFragment` to enforce this 
+— it must only be promoted to `SafeSqlFragment` via `acceptUntrustedSql` in an 
+event handler that requires explicit user action.
+
+```ts
+// 🛑 BAD: Snippet content is executed automatically via useQuery, with no
+// explicit user action confirming that the user has reviewed the SQL.
+import { acceptUntrustedSql } from '@supabase/pg-meta'
+
+function UnsafeSnippetPreview({ snippet }: { snippet: Snippet }) {
+  const { data } = useExecuteSqlQuery({
+    sql: acceptUntrustedSql(snippet.content.unchecked_sql),
+  })
+
+  return <Results data={data} />
+}
+```
+
+```ts
+// 🛑 BAD: Casting bypasses the type system entirely. The snippet's
+// `unchecked_sql` is `UntrustedSqlFragment` for a reason — never cast it.
+function UnsafeSnippetRunner({ snippet }: { snippet: Snippet }) {
+  const { mutate: execute } = useExecuteSqlMutation()
+
+  useEffect(() => {
+    execute({ sql: snippet.content.unchecked_sql as SafeSqlFragment })
+  }, [snippet])
+}
+```
+
+```ts
+// ✅ GOOD: Snippet content is only promoted to SafeSqlFragment inside an event
+// handler, after the user clicks Run. The user has seen the SQL in the editor
+// and explicitly chosen to execute it.
+import { acceptUntrustedSql } from '@supabase/pg-meta'
+
+function SnippetRunner({ snippet }: { snippet: Snippet }) {
+  const { mutate: execute } = useExecuteSqlMutation()
+
+  const handleRun = () => {
+    execute({ sql: acceptUntrustedSql(snippet.content.unchecked_sql) })
+  }
+
+  return (
+    <>
+      <SnippetEditor snippet={snippet} />
+      <button onClick={handleRun}>Run</button>
+    </>
+  )
+}
+```