The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
feat: notebook content schema (#48813)
Charis0b97e37ccfff
diff --git a/apps/studio/components/interfaces/SQLEditor/querySource.test.ts b/apps/studio/components/interfaces/SQLEditor/querySource.test.tsindex d0e4659d0da..6c68f56e2db 100644--- a/apps/studio/components/interfaces/SQLEditor/querySource.test.ts+++ b/apps/studio/components/interfaces/SQLEditor/querySource.test.ts@@ -6,7 +6,6 @@ import {DEFAULT_LOG_DATE_RANGE,getSnippetSource,isLogsSource,- isoDateTimeString,logDateRangesEqual,logDateRangeToDatePickerValue,resolveLogRunRange,@@ -21,6 +20,7 @@ import {import { generateHelpersFromInput } from '@/components/interfaces/Settings/Logs/Logs.datePickerHelpers'import type { DatePickerValue } from '@/components/interfaces/Settings/Logs/Logs.DatePickers'import type { DatetimeHelper } from '@/components/interfaces/Settings/Logs/Logs.types'+import { isoDateTimeString } from '@/lib/iso-datetime'/** Build the `DatePickerValue` the Logs picker submits when a helper is selected. */const valueFromHelper = (helper: DatetimeHelper): DatePickerValue => ({@@ -92,22 +92,6 @@ describe('querySource.ts:resolveSnippetSource', () => {})})-describe('querySource.ts:isoDateTimeString', () => {- it('accepts a valid ISO datetime', () => {- const raw = '2025-01-01T12:00:00.000Z'- expect(isoDateTimeString(raw)).toBe(raw)- })-- it('rejects an empty string', () => {- expect(isoDateTimeString('')).toBeNull()- })-- it('rejects junk', () => {- expect(isoDateTimeString('not-a-date')).toBeNull()- expect(isoDateTimeString('2025-13-45T99:99:99Z')).toBeNull()- })-})-describe('querySource.ts:datePickerValueToLogDateRange', () => {it('parses every static preset into a relative range', () => {const cases: Array<[string, { amount: number; unit: 'minute' | 'hour' | 'day' }]> = [diff --git a/apps/studio/components/interfaces/SQLEditor/querySource.ts b/apps/studio/components/interfaces/SQLEditor/querySource.tsindex 32e84bd78a3..4a1174f8375 100644--- a/apps/studio/components/interfaces/SQLEditor/querySource.ts+++ b/apps/studio/components/interfaces/SQLEditor/querySource.ts@@ -5,6 +5,7 @@ import { generateDynamicHelper } from '@/components/interfaces/Settings/Logs/Logimport type { DatePickerValue } from '@/components/interfaces/Settings/Logs/Logs.DatePickers'import type { ResolvedLogDateRange } from '@/components/interfaces/Settings/Logs/logsDateRange'import type { Snippet } from '@/data/content/sql-folders-query'+import { isoDateTimeString, type IsoDateTimeString } from '@/lib/iso-datetime'/*** Domain view of where a snippet's query runs. Derived from the content TYPE:@@ -60,22 +61,6 @@ export function resolveSnippetSource(return snippet !== undefined ? getSnippetSource(snippet) : parseSqlSnippetSource(sourceParam)}-/**- * An ISO-8601 datetime proven valid at construction via a dayjs parse. Absolute- * log ranges carry these instead of raw strings so an unvalidated datetime can- * never reach execution.- */-export type IsoDateTimeString = string & { readonly __isoDateTimeBrand: unique symbol }--/**- * Validate a raw string as an ISO datetime, returning the branded value or null.- * The sole construction site for `IsoDateTimeString` outside `now`.- */-export function isoDateTimeString(raw: string): IsoDateTimeString | null {- if (!raw) return null- return dayjs(raw).isValid() ? (raw as IsoDateTimeString) : null-}-/** `now` as a branded ISO datetime — `toISOString()` is always valid ISO-8601. */function nowIsoDateTime(): IsoDateTimeString {return dayjs().toISOString() as IsoDateTimeStringdiff --git a/apps/studio/data/content/content-query.ts b/apps/studio/data/content/content-query.tsindex e65c862acbd..65ad09dc4ba 100644--- a/apps/studio/data/content/content-query.ts+++ b/apps/studio/data/content/content-query.ts@@ -6,7 +6,12 @@ import { contentKeys } from './keys'import { get, handleError } from '@/data/fetchers'import type { Dashboards, LogSqlSnippets, SqlSnippets, UseCustomQueryOptions } from '@/types'-export type ContentBase = components['schemas']['GetUserContentResponse']['data'][number]+// TODO — Charis 2026-08-06+// Temporary widening until we have API support for notebooks+export type ContentBase = Omit<+ components['schemas']['GetUserContentResponse']['data'][number],+ 'type'+> & { type: components['schemas']['GetUserContentResponse']['data'][number]['type'] | 'notebook' }export type Content = Omit<ContentBase, 'content' | 'type'> &(diff --git a/apps/studio/data/content/notebooks/notebook-schema.test.ts b/apps/studio/data/content/notebooks/notebook-schema.test.tsnew file mode 100644index 00000000000..8f81fff51cf--- /dev/null+++ b/apps/studio/data/content/notebooks/notebook-schema.test.ts@@ -0,0 +1,161 @@+import { untrustedSql } from '@supabase/pg-meta'+import { describe, expect, it } from 'vitest'++import { agentNotebookSchema, notebookDomainSchema, notebookSchema } from './notebook-schema'+import { untrustedLogSql } from '@/data/logs/safe-analytics-sql'++const FULL_NOTEBOOK = {+ schema_version: 1 as const,+ cells: [+ {+ _tag: 'markdown_cell' as const,+ id: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',+ text: '# Signup funnel',+ },+ {+ _tag: 'database_cell' as const,+ id: 'b1ffcd88-8d1a-4de7-aa5c-5aa8ac270b22',+ sql: 'select * from auth.users limit 100',+ row_limit: 100,+ },+ {+ _tag: 'log_cell' as const,+ id: 'c2001199-1e2b-4ef8-bb6d-6bb9bd380a33',+ sql: "select timestamp, event_message from edge_logs where source = 'edge_logs' limit 10",+ time_range: {+ _tag: 'relative_time_range' as const,+ unit: 'hour' as const,+ amount: 1,+ },+ },+ ],+}++describe('notebookSchema', () => {+ it('accepts a full three-cell notebook', () => {+ expect(notebookSchema.safeParse(FULL_NOTEBOOK).success).toBe(true)+ })++ it('rejects an unknown cell _tag', () => {+ const result = notebookSchema.safeParse({+ schema_version: 1,+ cells: [{ _tag: 'chart_cell', id: '1', text: 'hi' }],+ })++ expect(result.success).toBe(false)+ })++ it('rejects a database_cell missing row_limit', () => {+ const result = notebookSchema.safeParse({+ schema_version: 1,+ cells: [{ _tag: 'database_cell', id: '1', sql: 'select 1' }],+ })++ expect(result.success).toBe(false)+ })++ it('rejects a non-ISO absolute_time_range bound', () => {+ const result = notebookSchema.safeParse({+ schema_version: 1,+ cells: [+ {+ _tag: 'log_cell',+ id: '1',+ sql: 'select 1',+ time_range: {+ _tag: 'absolute_time_range',+ start: 'not-a-real-date',+ end: '2024-01-02T00:00:00.000Z',+ },+ },+ ],+ })++ expect(result.success).toBe(false)+ })++ it('accepts an absolute_time_range with ISO8601 bounds', () => {+ const result = notebookSchema.safeParse({+ schema_version: 1,+ cells: [+ {+ _tag: 'log_cell',+ id: '1',+ sql: 'select 1',+ time_range: {+ _tag: 'absolute_time_range',+ start: '2024-01-01T00:00:00.000Z',+ end: '2024-01-02T00:00:00.000Z',+ },+ },+ ],+ })++ expect(result.success).toBe(true)+ })++ it('rejects an invalid relative_time_range unit', () => {+ const result = notebookSchema.safeParse({+ schema_version: 1,+ cells: [+ {+ _tag: 'log_cell',+ id: '1',+ sql: 'select 1',+ time_range: { _tag: 'relative_time_range', unit: 'fortnight', amount: 1 },+ },+ ],+ })++ expect(result.success).toBe(false)+ })+})++describe('agentNotebookSchema', () => {+ it('accepts cells without ids', () => {+ const result = agentNotebookSchema.safeParse({+ schema_version: 1,+ cells: [+ { _tag: 'markdown_cell', text: 'hello' },+ { _tag: 'database_cell', sql: 'select 1', row_limit: 100 },+ ],+ })++ expect(result.success).toBe(true)+ })++ it('rejects cells that carry an agent-supplied id', () => {+ const result = agentNotebookSchema.safeParse({+ schema_version: 1,+ cells: [{ _tag: 'markdown_cell', id: 'should-not-be-here', text: 'hello' }],+ })++ expect(result.success).toBe(false)+ })+})++describe('notebookDomainSchema', () => {+ it('brands database_cell and log_cell sql as unchecked_sql, leaving markdown_cell untouched', () => {+ const result = notebookDomainSchema.safeParse(FULL_NOTEBOOK)++ expect(result.success).toBe(true)+ if (!result.success) return++ const [markdownCell, databaseCell, logCell] = result.data.cells+ expect(markdownCell).toEqual(FULL_NOTEBOOK.cells[0])+ expect(databaseCell).toEqual({+ _tag: 'database_cell',+ id: FULL_NOTEBOOK.cells[1].id,+ row_limit: 100,+ unchecked_sql: untrustedSql('select * from auth.users limit 100'),+ })+ expect(databaseCell).not.toHaveProperty('sql')+ expect(logCell).toMatchObject({+ _tag: 'log_cell',+ unchecked_sql: untrustedLogSql(+ "select timestamp, event_message from edge_logs where source = 'edge_logs' limit 10"+ ),+ })+ expect(logCell).not.toHaveProperty('sql')+ })+})diff --git a/apps/studio/data/content/notebooks/notebook-schema.ts b/apps/studio/data/content/notebooks/notebook-schema.tsnew file mode 100644index 00000000000..e5ca0c796da--- /dev/null+++ b/apps/studio/data/content/notebooks/notebook-schema.ts@@ -0,0 +1,121 @@+import { untrustedSql } from '@supabase/pg-meta'+import * as z from 'zod'++import { untrustedLogSql } from '@/data/logs/safe-analytics-sql'+import { isoDateTimeString } from '@/lib/iso-datetime'++const isoDateTimeSchema = z.string().transform((raw, ctx) => {+ const parsed = isoDateTimeString(raw)+ if (parsed === null) {+ ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'must be a valid ISO-8601 datetime' })+ return z.NEVER+ }+ return parsed+})++const chartConfigSchema = z.object({+ x_column: z.string(),+ y_column: z.string(),+ cumulative: z.boolean(),+})++const absoluteTimeRangeSchema = z.object({+ _tag: z.literal('absolute_time_range'),+ start: isoDateTimeSchema,+ end: isoDateTimeSchema,+})++const relativeTimeRangeSchema = z.object({+ _tag: z.literal('relative_time_range'),+ unit: z.enum(['minute', 'hour', 'day', 'week', 'month', 'year']),+ amount: z.number(),+})++const timeRangeSchema = z.discriminatedUnion('_tag', [+ absoluteTimeRangeSchema,+ relativeTimeRangeSchema,+])++const markdownCellSchema = z.object({+ _tag: z.literal('markdown_cell'),+ id: z.string(),+ text: z.string(),+})++const databaseCellSchema = z.object({+ _tag: z.literal('database_cell'),+ id: z.string(),+ sql: z.string(),+ row_limit: z.number(),+ chart: chartConfigSchema.optional(),+})++const logCellSchema = z.object({+ _tag: z.literal('log_cell'),+ id: z.string(),+ sql: z.string(),+ time_range: timeRangeSchema,+ chart: chartConfigSchema.optional(),+})++const cellSchema = z.discriminatedUnion('_tag', [+ markdownCellSchema,+ databaseCellSchema,+ logCellSchema,+])++// The wire shape: every notebook fetched from the API has this shape, with backend-+// generated cell `id`s and plaintext `sql`.+export const notebookSchema = z.object({+ schema_version: z.literal(1),+ cells: z.array(cellSchema),+})++export type NotebookWire = z.infer<typeof notebookSchema>+export type CellWire = z.infer<typeof cellSchema>++// Agents have restrictions on writing IDs to preserve guarantees about ID+// uniqueness.+export const agentCellSchema = z.discriminatedUnion('_tag', [+ markdownCellSchema.omit({ id: true }).strict(),+ databaseCellSchema.omit({ id: true }).strict(),+ logCellSchema.omit({ id: true }).strict(),+])++export const agentNotebookSchema = z.object({+ schema_version: z.literal(1),+ cells: z.array(agentCellSchema),+})++export type AgentNotebook = z.infer<typeof agentNotebookSchema>+export type AgentCell = z.infer<typeof agentCellSchema>++// The domain shape: parses the same wire cell (`cellSchema`) and transforms `sql` into a+// branded `unchecked_sql`.+const cellDomainSchema = cellSchema.transform((cell) => {+ switch (cell._tag) {+ case 'markdown_cell':+ return cell+ case 'database_cell': {+ const { sql, ...rest } = cell+ return { ...rest, unchecked_sql: untrustedSql(sql) }+ }+ case 'log_cell': {+ const { sql, ...rest } = cell+ return { ...rest, unchecked_sql: untrustedLogSql(sql) }+ }+ }+})++export const notebookDomainSchema = z.object({+ schema_version: z.literal(1),+ cells: z.array(cellDomainSchema),+})++export type NotebookContent = z.infer<typeof notebookDomainSchema>+export type Cell = z.infer<typeof cellDomainSchema>+export type MarkdownCell = Extract<Cell, { _tag: 'markdown_cell' }>+export type DatabaseCell = Extract<Cell, { _tag: 'database_cell' }>+export type LogCell = Extract<Cell, { _tag: 'log_cell' }>+export type TimeRange = z.infer<typeof timeRangeSchema>+export type ChartConfig = z.infer<typeof chartConfigSchema>diff --git a/apps/studio/lib/iso-datetime.test.ts b/apps/studio/lib/iso-datetime.test.tsnew file mode 100644index 00000000000..332782ad9f0--- /dev/null+++ b/apps/studio/lib/iso-datetime.test.ts@@ -0,0 +1,19 @@+import { describe, expect, it } from 'vitest'++import { isoDateTimeString } from './iso-datetime'++describe('isoDateTimeString', () => {+ it('accepts a valid ISO datetime', () => {+ const raw = '2025-01-01T12:00:00.000Z'+ expect(isoDateTimeString(raw)).toBe(raw)+ })++ it('rejects an empty string', () => {+ expect(isoDateTimeString('')).toBeNull()+ })++ it('rejects junk', () => {+ expect(isoDateTimeString('not-a-date')).toBeNull()+ expect(isoDateTimeString('2025-13-45T99:99:99Z')).toBeNull()+ })+})diff --git a/apps/studio/lib/iso-datetime.ts b/apps/studio/lib/iso-datetime.tsnew file mode 100644index 00000000000..9153213804d--- /dev/null+++ b/apps/studio/lib/iso-datetime.ts@@ -0,0 +1,19 @@+import dayjs from 'dayjs'++/**+ * An ISO-8601 datetime proven valid at construction via a dayjs parse. Callers that need to+ * carry a datetime through the type system without re-validating it (e.g. absolute log+ * ranges, notebook time ranges) use this instead of a raw string, so an unvalidated value+ * can never reach execution.+ */+export type IsoDateTimeString = string & { readonly __isoDateTimeBrand: unique symbol }++/**+ * Validate a raw string as an ISO datetime, returning the branded value or null. The sole+ * construction site for `IsoDateTimeString` besides a direct `toISOString()` call (which is+ * always valid ISO-8601 by construction).+ */+export function isoDateTimeString(raw: string): IsoDateTimeString | null {+ if (!raw) return null+ return dayjs(raw).isValid() ? (raw as IsoDateTimeString) : null+}diff --git a/apps/studio/types/userContent.ts b/apps/studio/types/userContent.tsindex 0910808bb82..e1206a77739 100644--- a/apps/studio/types/userContent.ts+++ b/apps/studio/types/userContent.ts@@ -1,8 +1,19 @@import type { UntrustedSqlFragment } from '@supabase/pg-meta'import { ChartConfig } from '@/components/interfaces/SQLEditor/UtilityPanel/ChartConfig'+import type * as NotebookSchema from '@/data/content/notebooks/notebook-schema'import type { UntrustedLogSqlFragment } from '@/data/logs/safe-analytics-sql'+export namespace Notebooks {+ export type Content = NotebookSchema.NotebookContent+ export type Cell = NotebookSchema.Cell+ export type MarkdownCell = NotebookSchema.MarkdownCell+ export type DatabaseCell = NotebookSchema.DatabaseCell+ export type LogCell = NotebookSchema.LogCell+ export type TimeRange = NotebookSchema.TimeRange+ export type ChartConfig = NotebookSchema.ChartConfig+}+export interface UserContent<T = Dashboards.Content | SqlSnippets.Content | LogSqlSnippets.Content,> {