Skip to content

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

feat: add safe SQL execution for analytics queries (BigQuery/ClickHouse) (#46287)

Charisd117e70f6c5f
diff --git a/apps/studio/data/logs/execute-analytics-sql.ts b/apps/studio/data/logs/execute-analytics-sql.ts
new file mode 100644
index 00000000000..5e3e7a77de7
--- /dev/null
+++ b/apps/studio/data/logs/execute-analytics-sql.ts
@@ -0,0 +1,50 @@
+/**
+ * Wire-boundary for analytics SQL execution.
+ *
+ * This is the analytics-path analog of pg-meta's `executeSql`. It accepts only
+ * `SafeLogSqlFragment` — plain strings are rejected at compile time — so any
+ * value flowing from URL parameters, UI inputs, or LLM output must pass through
+ * a sanitization helper in safe-analytics-sql.ts before reaching the wire.
+ *
+ * See .claude/skills/safe-sql-execution/SKILL.md for the full security model.
+ */
+import type { SafeLogSqlFragment } from './safe-analytics-sql'
+import { handleError, post } from '@/data/fetchers'
+
+/**
+ * Analytics endpoints that accept a POST body with `{ sql, iso_timestamp_start, iso_timestamp_end }`.
+ * Extend this union as additional endpoints are migrated to the safe-analytics-sql pattern.
+ */
+export type AnalyticsSqlEndpoint =
+ | '/platform/projects/{ref}/analytics/endpoints/logs.all'
+ | '/platform/projects/{ref}/analytics/endpoints/logs.all.otel'
+
+export interface ExecuteAnalyticsSqlVariables {
+ projectRef: string
+ endpoint: AnalyticsSqlEndpoint
+ /** Must carry the `SafeLogSqlFragment` brand — plain strings are rejected at compile time. */
+ sql: SafeLogSqlFragment
+ iso_timestamp_start: string
+ iso_timestamp_end: string
+ signal?: AbortSignal
+ headers?: HeadersInit
+}
+
+export async function executeAnalyticsSql({
+ projectRef,
+ endpoint,
+ sql,
+ iso_timestamp_start,
+ iso_timestamp_end,
+ signal,
+ headers: headersInit,
+}: ExecuteAnalyticsSqlVariables) {
+ const { data, error } = await post(endpoint, {
+ params: { path: { ref: projectRef } },
+ body: { sql, iso_timestamp_start, iso_timestamp_end },
+ signal,
+ headers: headersInit !== undefined ? new Headers(headersInit) : undefined,
+ })
+ if (error) handleError(error)
+ return data
+}
diff --git a/apps/studio/data/logs/safe-analytics-sql.test.ts b/apps/studio/data/logs/safe-analytics-sql.test.ts
new file mode 100644
index 00000000000..358027004ca
--- /dev/null
+++ b/apps/studio/data/logs/safe-analytics-sql.test.ts
@@ -0,0 +1,170 @@
+import { describe, expect, it } from 'vitest'
+
+import { executeAnalyticsSql } from './execute-analytics-sql'
+import {
+ analyticsLiteral,
+ bqDottedIdent,
+ bqIdent,
+ clickhouseDottedIdent,
+ clickhouseIdent,
+ keyword,
+ safeSql,
+} from './safe-analytics-sql'
+
+describe('keyword', () => {
+ it('returns the matching SafeLogSqlFragment from the allow-list', () => {
+ expect(keyword('AND', [safeSql`AND`, safeSql`OR`])).toBe('AND')
+ expect(keyword('=', [safeSql`=`, safeSql`!=`, safeSql`LIKE`])).toBe('=')
+ })
+
+ it('throws when value is not in the allow-list', () => {
+ expect(() => keyword('DROP', [safeSql`AND`, safeSql`OR`])).toThrow(
+ '"DROP" is not in the allowed list'
+ )
+ })
+
+ it('is case-insensitive and returns the allow-listed fragment', () => {
+ // 'and' (lowercase) matches 'AND' in the allow-list; the returned value
+ // is the allow-listed fragment 'AND', not the raw input 'and'.
+ expect(keyword('and', [safeSql`AND`, safeSql`OR`])).toBe('AND')
+ expect(keyword('OR', [safeSql`and`, safeSql`or`])).toBe('or')
+ })
+
+ it('throws for an empty allow-list', () => {
+ expect(() => keyword('AND', [])).toThrow()
+ })
+})
+
+describe('bqDottedIdent', () => {
+ it('wraps a single-segment identifier in backticks', () => {
+ expect(bqDottedIdent('status')).toBe('`status`')
+ })
+
+ it('wraps the entire two-part dotted path in a single pair of backticks', () => {
+ expect(bqDottedIdent('request.method')).toBe('`request.method`')
+ })
+
+ it('wraps the entire three-part dotted path in a single pair of backticks', () => {
+ expect(bqDottedIdent('a.b.c')).toBe('`a.b.c`')
+ })
+
+ it('throws for an empty string', () => {
+ expect(() => bqDottedIdent('')).toThrow('invalid BigQuery dotted identifier')
+ })
+
+ it('throws when a segment contains disallowed characters', () => {
+ expect(() => bqDottedIdent('request.method; DROP TABLE')).toThrow(
+ 'invalid BigQuery dotted identifier'
+ )
+ })
+
+ it('throws for an empty segment (double dot)', () => {
+ expect(() => bqDottedIdent('a..b')).toThrow('invalid BigQuery dotted identifier')
+ })
+
+ it('produces the same result as bqIdent for a single segment', () => {
+ expect(bqDottedIdent('col')).toBe(bqIdent('col'))
+ })
+})
+
+describe('clickhouseDottedIdent', () => {
+ it('quotes a single-segment identifier with double-quotes', () => {
+ expect(clickhouseDottedIdent('status')).toBe('"status"')
+ })
+
+ it('quotes each segment of a two-part dotted identifier', () => {
+ expect(clickhouseDottedIdent('request.method')).toBe('"request"."method"')
+ })
+
+ it('quotes each segment of a three-part dotted identifier', () => {
+ expect(clickhouseDottedIdent('a.b.c')).toBe('"a"."b"."c"')
+ })
+
+ it('throws for an empty string', () => {
+ expect(() => clickhouseDottedIdent('')).toThrow('invalid ClickHouse dotted identifier')
+ })
+
+ it('throws when a segment contains disallowed characters', () => {
+ expect(() => clickhouseDottedIdent('col OR 1=1')).toThrow(
+ 'invalid ClickHouse dotted identifier'
+ )
+ })
+
+ it('produces the same result as clickhouseIdent for a single segment', () => {
+ expect(clickhouseDottedIdent('col')).toBe(clickhouseIdent('col'))
+ })
+})
+
+describe('executeAnalyticsSql — compile-time boundary', () => {
+ it('accepts a SafeLogSqlFragment', () => {
+ const sql = safeSql`SELECT 1`
+ // SafeLogSqlFragment is accepted — no type error expected here.
+ const fn = () =>
+ executeAnalyticsSql({
+ projectRef: 'test-ref',
+ endpoint: '/platform/projects/{ref}/analytics/endpoints/logs.all',
+ sql,
+ iso_timestamp_start: '2024-01-01T00:00:00Z',
+ iso_timestamp_end: '2024-01-02T00:00:00Z',
+ })
+ expect(fn).toBeDefined()
+ })
+
+ it('rejects a plain string at the type level', () => {
+ const plainSql: string = 'SELECT 1'
+ // Never invoked — compile-time check only. The function is defined so
+ // TypeScript type-checks the body, but no network request is made.
+ const _check = () =>
+ executeAnalyticsSql({
+ projectRef: 'test-ref',
+ endpoint: '/platform/projects/{ref}/analytics/endpoints/logs.all',
+ // @ts-expect-error — plain string must not be assignable to SafeLogSqlFragment
+ sql: plainSql,
+ iso_timestamp_start: '2024-01-01T00:00:00Z',
+ iso_timestamp_end: '2024-01-02T00:00:00Z',
+ })
+ expect(_check).toBeDefined()
+ })
+
+ it('rejects rawSql output cast back to string at the type level', () => {
+ const fragment = safeSql`SELECT 1`
+ const asString: string = fragment as string
+ // Never invoked — compile-time check only.
+ const _check = () =>
+ executeAnalyticsSql({
+ projectRef: 'test-ref',
+ endpoint: '/platform/projects/{ref}/analytics/endpoints/logs.all',
+ // @ts-expect-error — widened-to-string value must not be assignable to SafeLogSqlFragment
+ sql: asString,
+ iso_timestamp_start: '2024-01-01T00:00:00Z',
+ iso_timestamp_end: '2024-01-02T00:00:00Z',
+ })
+ expect(_check).toBeDefined()
+ })
+})
+
+describe('safeSql template tag — existing helpers still compose', () => {
+ it('analyticsLiteral output is composable via safeSql', () => {
+ const val = analyticsLiteral('hello')
+ const query = safeSql`SELECT ${val}`
+ expect(query).toBe("SELECT 'hello'")
+ })
+
+ it('bqDottedIdent output is composable via safeSql', () => {
+ const col = bqDottedIdent('request.method')
+ const query = safeSql`SELECT ${col} FROM logs`
+ expect(query).toBe('SELECT `request.method` FROM logs')
+ })
+
+ it('clickhouseDottedIdent output is composable via safeSql', () => {
+ const col = clickhouseDottedIdent('request.method')
+ const query = safeSql`SELECT ${col} FROM logs`
+ expect(query).toBe('SELECT "request"."method" FROM logs')
+ })
+
+ it('keyword output is composable via safeSql', () => {
+ const op = keyword('AND', [safeSql`AND`, safeSql`OR`])
+ const query = safeSql`WHERE a = 1 ${op} b = 2`
+ expect(query).toBe('WHERE a = 1 AND b = 2')
+ })
+})
diff --git a/apps/studio/data/logs/safe-analytics-sql.ts b/apps/studio/data/logs/safe-analytics-sql.ts
index 91c522d325d..a26c1cd47d3 100644
--- a/apps/studio/data/logs/safe-analytics-sql.ts
+++ b/apps/studio/data/logs/safe-analytics-sql.ts
@@ -1,3 +1,15 @@
+// SECURITY MODEL — Proven authorship for analytics SQL
+//
+// Analytics queries (BigQuery for legacy cloud, ClickHouse for self-hosted OTEL)
+// carry the same injection risk as Postgres queries: filter keys, values, and
+// other fragments that originate from URL parameters, UI inputs, or LLM output
+// can be spliced into SQL that is executed on behalf of the project. The pattern
+// here mirrors the pg-meta safe-SQL model described in
+// .claude/skills/safe-sql-execution/SKILL.md: every value that flows from an
+// external source must pass through a sanitization helper before being
+// interpolated, and the wire boundary (`executeAnalyticsSql`) refuses plain
+// strings at compile time.
+//
// pg-meta's `literal()` and `ident()` are Postgres-specific: `literal()` emits
// `E'…'` for backslash-bearing strings and `::jsonb` casts for objects;
// `ident()` quotes identifiers with double-quotes, which BigQuery rejects
@@ -124,3 +136,53 @@ export function clickhouseIdent(value: string): SafeLogSqlFragment {
}
return rawSql('"' + value + '"')
}
+
+/**
+ * Validates `value` against an allow-list of pre-branded fragments and returns
+ * the matching fragment. Use for SQL operators or keywords where the permitted
+ * set is known at compile time (e.g. `keyword(op, [safeSql`AND`, safeSql`OR`])`).
+ * Matching is case-insensitive (SQL keywords are case-insensitive by convention);
+ * the returned value is always the allow-listed fragment, never the raw input.
+ * Throws if `value` does not match any fragment in `allowed`.
+ */
+export function keyword(value: string, allowed: readonly SafeLogSqlFragment[]): SafeLogSqlFragment {
+ const lower = value.toLowerCase()
+ const match = allowed.find((frag) => frag.toLowerCase() === lower)
+ if (match === undefined) {
+ throw new Error(
+ `keyword: "${value}" is not in the allowed list [${allowed.map((s) => `"${s}"`).join(', ')}]`
+ )
+ }
+ return match
+}
+
+/**
+ * Quotes a dotted BigQuery identifier by wrapping the entire path in backticks,
+ * validating each segment individually.
+ * Accepts `a`, `a.b`, or `a.b.c`; each segment must match `[A-Za-z_][A-Za-z0-9_]*`.
+ * Example: `bqDottedIdent('request.method')` → `` `request.method` ``
+ *
+ * BigQuery requires the entire dotted path to be enclosed in a single pair of
+ * backticks; individually quoting each segment (`` `request`.`method` ``) is a
+ * syntax error in BigQuery's dialect.
+ */
+export function bqDottedIdent(value: string): SafeLogSqlFragment {
+ const segments = value.split('.')
+ if (segments.length === 0 || segments.some((s) => !SAFE_IDENT_RE.test(s))) {
+ throw new Error(`bqDottedIdent: invalid BigQuery dotted identifier "${value}"`)
+ }
+ return rawSql('`' + segments.join('.') + '`')
+}
+
+/**
+ * Quotes a dotted ClickHouse identifier using double-quotes, validating each segment.
+ * Accepts `a`, `a.b`, or `a.b.c`; each segment must match `[A-Za-z_][A-Za-z0-9_]*`.
+ * Example: `clickhouseDottedIdent('request.method')` → `"request"."method"`
+ */
+export function clickhouseDottedIdent(value: string): SafeLogSqlFragment {
+ const segments = value.split('.')
+ if (segments.length === 0 || segments.some((s) => !SAFE_IDENT_RE.test(s))) {
+ throw new Error(`clickhouseDottedIdent: invalid ClickHouse dotted identifier "${value}"`)
+ }
+ return rawSql(segments.map((s) => '"' + s + '"').join('.'))
+}