Skip to content

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

feat: introduce safeSql function to pg-meta (#44467)

Charisc372e77c8b36
diff --git a/packages/pg-meta/src/index.ts b/packages/pg-meta/src/index.ts
index 0e498b0e93a..a9b038d4bb8 100644
--- a/packages/pg-meta/src/index.ts
+++ b/packages/pg-meta/src/index.ts
@@ -33,6 +33,9 @@ export * from './sql/studio/sql-editor'
export * from './sql/studio/role-impersonation'
export * from './sql/studio/integrations'
+export { ident, literal, keyword, safeSql, joinSqlFragments } from './pg-format'
+export type { SafeSqlFragment } from './pg-format'
+
export default {
roles,
columns,
diff --git a/packages/pg-meta/src/pg-format/index.ts b/packages/pg-meta/src/pg-format/index.ts
index a2f99321676..e6f92ea6a23 100644
--- a/packages/pg-meta/src/pg-format/index.ts
+++ b/packages/pg-meta/src/pg-format/index.ts
@@ -10,6 +10,38 @@ export interface PgFormatConfig {
pattern: PgFormatConfigPattern
}
+/**
+ * A branded string type representing a SQL fragment that is safe to compose
+ * into queries.
+ * Values of this type are either:
+ * - Static strings in source code (no interpolation)
+ * - Outputs of `ident()`, `literal()`, or `keyword()` (properly escaped or
+ * validated)
+ * - Compositions via `safeSql` template tag (enforces SafeSqlFragment-only
+ * interpolations)
+ * - Compositions via `joinFragments` (enforces SafeSqlFragment inputs)
+ *
+ * Never cast arbitrary strings to this type — use ident/literal/keyword/safeSql
+ * instead.
+ */
+export type SafeSqlFragment = string & { readonly __safeSqlFragmentBrand: never }
+
+export type SqlFragmentSeparator =
+ | ','
+ | ', '
+ | ';\n'
+ | ' and '
+ | ' AND '
+ | ' or '
+ | ' OR '
+ | ' union all '
+ | ' union '
+ | ' UNION ALL '
+ | ' UNION '
+ | '\n'
+ | '\n\n'
+ | ' '
+
const FMT_PATTERN_CONFIG: PgFormatConfigPattern = {
ident: 'I',
literal: 'L',
@@ -42,15 +74,15 @@ function arrayToList(useSpace: boolean, array: unknown[], formatter: (value: unk
// Ported from PostgreSQL 9.2.4 source code in src/interfaces/libpq/fe-exec.c
// eslint-disable-next-line radar/cognitive-complexity
-export function ident(value?: unknown): string {
+export function ident(value?: unknown): SafeSqlFragment {
if (value === undefined || value === null) {
throw new Error('SQL identifier cannot be null or undefined')
} else if (value === false) {
- return '"f"'
+ return '"f"' as SafeSqlFragment
} else if (value === true) {
- return '"t"'
+ return '"t"' as SafeSqlFragment
} else if (value instanceof Date) {
- return `"${formatDate(value.toISOString())}"`
+ return `"${formatDate(value.toISOString())}"` as SafeSqlFragment
} else if (Array.isArray(value)) {
const temporary: string[] = []
for (const element of value) {
@@ -62,7 +94,7 @@ export function ident(value?: unknown): string {
temporary.push(ident(element))
}
}
- return temporary.toString()
+ return temporary.toString() as SafeSqlFragment
} else if (value === Object(value)) {
throw new Error('SQL identifier cannot be an object')
}
@@ -71,7 +103,7 @@ export function ident(value?: unknown): string {
// do not quote a valid, unquoted identifier
if (/^[_a-z][\d$_a-z]*$/.test(tident) === true && isReserved(tident) === false) {
- return tident
+ return tident as SafeSqlFragment
}
let quoted = '"'
@@ -82,42 +114,42 @@ export function ident(value?: unknown): string {
quoted += '"'
- return quoted
+ return quoted as SafeSqlFragment
}
// Ported from PostgreSQL 9.2.4 source code in src/interfaces/libpq/fe-exec.c
// eslint-disable-next-line radar/cognitive-complexity
-export function literal(value?: unknown): string {
+export function literal(value?: unknown): SafeSqlFragment {
let tliteral = ''
let explicitCast: string | undefined
if (value === undefined || value === null) {
- return 'NULL'
+ return 'NULL' as SafeSqlFragment
}
if (typeof value === 'bigint') {
- return BigInt(value).toString()
+ return BigInt(value).toString() as SafeSqlFragment
}
if (value === Number.POSITIVE_INFINITY) {
- return "'Infinity'"
+ return "'Infinity'" as SafeSqlFragment
}
if (value === Number.NEGATIVE_INFINITY) {
- return "'-Infinity'"
+ return "'-Infinity'" as SafeSqlFragment
}
if (Number.isNaN(value)) {
- return "'NaN'"
+ return "'NaN'" as SafeSqlFragment
}
if (typeof value === 'number') {
// Test must be AFTER other special case number tests
- return Number(value).toString()
+ return Number(value).toString() as SafeSqlFragment
}
if (value === false) {
- return "'f'"
+ return "'f'" as SafeSqlFragment
}
if (value === true) {
- return "'t'"
+ return "'t'" as SafeSqlFragment
}
if (value instanceof Date) {
- return `'${formatDate(value.toISOString())}'`
+ return `'${formatDate(value.toISOString())}'` as SafeSqlFragment
}
if (Array.isArray(value)) {
const temporary: string[] = []
@@ -128,7 +160,7 @@ export function literal(value?: unknown): string {
temporary.push(literal(element))
}
}
- return temporary.toString()
+ return temporary.toString() as SafeSqlFragment
}
if (value === Object(value)) {
explicitCast = 'jsonb'
@@ -161,7 +193,21 @@ export function literal(value?: unknown): string {
quoted += `::${explicitCast}`
}
- return quoted
+ return quoted as SafeSqlFragment
+}
+
+/**
+ * Marks SQL keywords (e.g., 'BEFORE', 'instead of') as safe for interpolation.
+ * Only letters, numbers, underscores, and spaces are allowed, to prevent
+ * injection.
+ */
+export function keyword(value: string): SafeSqlFragment {
+ if (!/^[A-Za-z][A-Za-z0-9_ ]*$/.test(value)) {
+ throw new Error(
+ `Not a valid keyword: "${value}". Only letters, numbers, underscores, and spaces are permitted.`
+ )
+ }
+ return value as SafeSqlFragment
}
// eslint-disable-next-line radar/cognitive-complexity
@@ -266,3 +312,29 @@ export function withArray(fmt: string, parameters: unknown[]): string {
export function format(fmt: string, ...arguments_: unknown[]): string {
return withArray(fmt, arguments_)
}
+
+/**
+ * Tagged template literal for composing SQL fragments safely.
+ * Only accepts SafeSqlFragment interpolations — plain strings are rejected at
+ * compile time.
+ */
+export function safeSql(
+ strings: TemplateStringsArray,
+ ...interpolated: Array<SafeSqlFragment>
+): SafeSqlFragment {
+ return strings.reduce(
+ (result, string, i) => result + string + (interpolated[i] ?? ''),
+ ''
+ ) as SafeSqlFragment
+}
+
+/**
+ * Joins an array of already-safe SQL fragments with a fixed structural
+ * separator.
+ */
+export function joinSqlFragments(
+ fragments: Array<SafeSqlFragment>,
+ separator: SqlFragmentSeparator
+): SafeSqlFragment {
+ return fragments.join(separator) as SafeSqlFragment
+}
diff --git a/packages/pg-meta/test/pg-format.test.ts b/packages/pg-meta/test/pg-format.test.ts
index 13628fc112f..48d5e9d0e8c 100644
--- a/packages/pg-meta/test/pg-format.test.ts
+++ b/packages/pg-meta/test/pg-format.test.ts
@@ -1,6 +1,6 @@
-import { describe, expect, test } from 'vitest'
+import { describe, expect, expectTypeOf, test } from 'vitest'
-import { ident, literal } from '../src/pg-format'
+import { ident, keyword, literal, safeSql } from '../src/pg-format'
describe('pg-format', () => {
describe('ident', () => {
@@ -139,4 +139,165 @@ describe('pg-format', () => {
expect(literal('C:\\Users\\test')).toBe("E'C:\\\\Users\\\\test'")
})
})
+
+ describe('keyword', () => {
+ test('accepts single uppercase words', () => {
+ expect(keyword('BEFORE')).toBe('BEFORE')
+ expect(keyword('AFTER')).toBe('AFTER')
+ expect(keyword('ROW')).toBe('ROW')
+ })
+
+ test('accepts lowercase and mixed case', () => {
+ expect(keyword('instead of')).toBe('instead of')
+ expect(keyword('Each Row')).toBe('Each Row')
+ })
+
+ test('accepts words with underscores and digits', () => {
+ expect(keyword('EACH_ROW')).toBe('EACH_ROW')
+ expect(keyword('col2')).toBe('col2')
+ })
+
+ test('rejects empty string', () => {
+ expect(() => keyword('')).toThrow('Not a valid keyword')
+ })
+
+ test('rejects strings starting with a digit', () => {
+ expect(() => keyword('1BEFORE')).toThrow('Not a valid keyword')
+ })
+
+ test('rejects strings with semicolons', () => {
+ expect(() => keyword('BEFORE;')).toThrow('Not a valid keyword')
+ })
+
+ test('rejects strings with dashes', () => {
+ expect(() => keyword('BE-FORE')).toThrow('Not a valid keyword')
+ })
+
+ test('rejects strings with single quotes', () => {
+ expect(() => keyword("BE'FORE")).toThrow('Not a valid keyword')
+ })
+
+ test('rejects strings with parentheses', () => {
+ expect(() => keyword('fn()')).toThrow('Not a valid keyword')
+ })
+ })
+
+ describe('safeSql', () => {
+ test('returns a plain string when there are no interpolations', () => {
+ const result = safeSql`SELECT 1`
+ expect(result).toBe('SELECT 1')
+ })
+
+ test('interpolates ident values', () => {
+ const table = ident('my_table')
+ const result = safeSql`SELECT * FROM ${table}`
+ expect(result).toBe('SELECT * FROM my_table')
+ })
+
+ test('interpolates literal values', () => {
+ const value = literal('hello')
+ const result = safeSql`SELECT ${value}`
+ expect(result).toBe("SELECT 'hello'")
+ })
+
+ test('interpolates multiple values', () => {
+ const table = ident('users')
+ const col = ident('email')
+ const val = literal('[email protected]')
+ const result = safeSql`SELECT ${col} FROM ${table} WHERE ${col} = ${val}`
+ expect(result).toBe(`SELECT email FROM users WHERE email = '[email protected]'`)
+ })
+
+ test('handles ident with special characters', () => {
+ const table = ident('my "table"')
+ const result = safeSql`SELECT * FROM ${table}`
+ expect(result).toBe('SELECT * FROM "my ""table"""')
+ })
+
+ test('literal: escapes classic quote bypass', () => {
+ const val = literal("' OR '1'='1")
+ const result = safeSql`SELECT * FROM users WHERE password = ${val}`
+ expect(result).toBe("SELECT * FROM users WHERE password = ''' OR ''1''=''1'")
+ })
+
+ test('literal: escapes UNION SELECT attack', () => {
+ const val = literal("x' UNION SELECT username, password FROM admins --")
+ const result = safeSql`SELECT name FROM products WHERE id = ${val}`
+ expect(result).toBe(
+ "SELECT name FROM products WHERE id = 'x'' UNION SELECT username, password FROM admins --'"
+ )
+ })
+
+ test('literal: escapes stacked query injection', () => {
+ const val = literal("1'; DROP TABLE users; --")
+ const result = safeSql`SELECT * FROM users WHERE id = ${val}`
+ expect(result).toBe("SELECT * FROM users WHERE id = '1''; DROP TABLE users; --'")
+ })
+
+ test('literal: escapes comment-based injection', () => {
+ const val = literal("admin'--")
+ const result = safeSql`SELECT * FROM users WHERE username = ${val}`
+ expect(result).toBe("SELECT * FROM users WHERE username = 'admin''--'")
+ })
+
+ test('ident: escapes SQL keyword injection in table name', () => {
+ const table = ident('users WHERE 1=1 --')
+ const result = safeSql`SELECT * FROM ${table}`
+ expect(result).toBe('SELECT * FROM "users WHERE 1=1 --"')
+ })
+
+ test('ident: escapes stacked query injection in column name', () => {
+ const col = ident('id; DROP TABLE users')
+ const result = safeSql`SELECT ${col} FROM users`
+ expect(result).toBe('SELECT "id; DROP TABLE users" FROM users')
+ })
+
+ test('handles literal with null', () => {
+ const val = literal(null)
+ const result = safeSql`SELECT ${val}`
+ expect(result).toBe('SELECT NULL')
+ })
+
+ test('handles literal with numbers', () => {
+ const val = literal(42)
+ const result = safeSql`SELECT ${val}`
+ expect(result).toBe('SELECT 42')
+ })
+
+ test('can be nested', () => {
+ const col = ident('id')
+ const inner = safeSql`SELECT ${col} FROM ${ident('items')}`
+ const outer = safeSql`WITH cte AS (${inner}) SELECT * FROM cte`
+ expect(outer).toBe('WITH cte AS (SELECT id FROM items) SELECT * FROM cte')
+ })
+ })
+
+ describe('safeSql type safety', () => {
+ test('rejects a plain string interpolation', () => {
+ const unsafeValue = 'malicious'
+ // @ts-expect-error plain string is not a SafeSqlFragment
+ safeSql`SELECT * FROM ${unsafeValue}`
+ })
+
+ test('rejects a number interpolation', () => {
+ // @ts-expect-error number is not a SafeSqlFragment
+ safeSql`SELECT * FROM users LIMIT ${10}`
+ })
+
+ test('rejects an object interpolation', () => {
+ const obj = { table: 'users' }
+ // @ts-expect-error object is not a SafeSqlFragment
+ safeSql`SELECT * FROM ${obj}`
+ })
+
+ test('accepts SafeSqlFragment from ident', () => {
+ const result = safeSql`SELECT * FROM ${ident('users')}`
+ expectTypeOf(result).toBeString
+ })
+
+ test('accepts SafeSqlFragment from literal', () => {
+ const result = safeSql`SELECT ${literal('value')}`
+ expectTypeOf(result).toBeString
+ })
+ })
})