Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

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

Charis600a0ffcec44
diff --git a/.claude/skills/safe-sql-execution/SKILL.md b/.claude/skills/safe-sql-execution/SKILL.md
new file mode 100644
index 00000000000..6cf59379d04
--- /dev/null
+++ b/.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>
+ </>
+ )
+}
+```