@protobase/cli 0.67.0 → 0.67.2

package/dist/cli/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.67.0";
+var version = "0.67.2";
 //#endregion
 export { version };

package/dist/config/build-project.js

@@ -1,4 +1,5 @@
 import { projectFiles, projectFunctions, projectJobs, projectNotifications, projectOptions, projectResources, projectWebhooks } from "./project-parts.js";
+import { userTablesOn } from "./user-tables-config.js";
 import { buildAppAuth, buildAuthenticator, checkCallsOptions, checkStatusOptions } from "@protobase/server/internal";
 //#region src/config/build-project.ts
 /**
@@ -76,6 +77,7 @@ const buildProject = async (config, database) => {
 		...config.mobile && { mobile: config.mobile },
 		...config.secret && { secret: config.secret },
 		...identity && { app: identity },
+		...userTablesOn(config) && { userTables: true },
 		options
 	};
 };

package/dist/config/source-config.js

@@ -1,4 +1,5 @@
 import { mergeConfig } from "./merge-config.js";
+import { checkUserTables } from "./user-tables-config.js";
 import { importProjectFiles } from "../project/import-project-file.js";
 import { withDefaults } from "./config-defaults.js";
 import { sourceFiles } from "./project-files.js";
@@ -27,11 +28,11 @@ const loadSourceConfig = async (dir, { command, extensions = [], importModules =
 	}
 	const file = configFileOf(dir);
 	const own = file ? await readConfigFile(file, configEnv, importModules) : {};
-	return withDefaults(mergeConfig(...extended, {
+	return checkUserTables(withDefaults(mergeConfig(...extended, {
 		config: own,
 		files: sourceFiles(dir, importModules),
 		label: file ? path.basename(file) : "config/index.ts"
-	}), command, process.env);
+	}), command, process.env));
 };
 //#endregion
 export { loadSourceConfig };

package/dist/config/user-tables-config.js

@@ -0,0 +1,15 @@
+//#region src/config/user-tables-config.ts
+/** Whether the app keeps tables its users add: the one reading of `userTables`, after `checkUserTables`. */
+const userTablesOn = (config) => config.userTables === true;
+/**
+* Refuses a `userTables` that is no boolean, and user tables together with organizations, whose definitions and records
+* are not kept per organization. Organizations are on for any truthy `auth.organizations`, as sign-in reads it.
+*/
+const checkUserTables = (config) => {
+	const value = config.userTables;
+	if (value !== void 0 && typeof value !== "boolean") throw new Error(`userTables is ${JSON.stringify(value)}; it takes true or false`);
+	if (userTablesOn(config) && config.auth && config.auth.organizations) throw new Error("userTables and auth.organizations are both on; tables users add are not kept per organization yet, so turn one of them off");
+	return config;
+};
+//#endregion
+export { checkUserTables, userTablesOn };

package/dist/dev/entry.js

@@ -1,13 +1,13 @@
 import { buildProject } from "../config/build-project.js";
 import { projectIcons } from "../build/app-icons.js";
 import { projectErrorReporter } from "../project/error-reporter.js";
-import { projectAdmin } from "../project/project-admin.js";
+import { servedAdmin } from "../project/served-admin.js";
 import { devJobs } from "./dev-jobs.js";
 import { devRealtimePrune } from "./dev-prune.js";
 import { devDatabase, loadDevConfig } from "./project.js";
 import { withDevServiceWorker } from "./service-worker-route.js";
 import { setMissing, supabaseEnv } from "./supabase-env.js";
-import { apiKeySettings, assistantSettings, authSchemaDrift, authStoreTables, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkWebhooksSchema, configExports, hasUsers, relayed, sqlSends } from "@protobase/server";
+import { apiKeySettings, assistantSettings, authSchemaDrift, authStoreTables, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkUserTablesSchema, checkWebhooksSchema, configExports, hasUsers, relayed, sqlSends } from "@protobase/server";
 import { upgradeWebSocket } from "@hono/node-server";
 import { Hono } from "hono";
 //#region src/dev/entry.ts
@@ -42,6 +42,7 @@ if (relayed(project.realtime)) await checkRealtimeRelay(db);
 if (sqlSends(project.realtime)) await checkChannelSends(db);
 if (project.notifications) await checkNotificationsSchema(db, project.notifications, project.auth);
 if (project.status) await checkStatusSchema(db, project.status, project.auth);
+if (project.userTables) await checkUserTablesSchema(db);
 setMissing(process.env, supabaseEnv({
 	url: process.env.PROTOBASE_DEV_URL,
 	databaseUrl: process.env.PROTOBASE_DATABASE_URL,
@@ -54,7 +55,7 @@ const ui = {
 	fieldTypes: {},
 	icons: projectIcons(projectDir)
 };
-const { admin, jobs } = projectAdmin(project, db, ui, reporter, upgradeWebSocket);
+const { admin, jobs } = await servedAdmin(project, db, ui, reporter, upgradeWebSocket);
 if (process.env.PROTOBASE_DEV_JOBS !== "false") await devJobs(db, jobs, admin.decryptField, project.mailer);
 devRealtimePrune(admin);
 var entry_default = withDevServiceWorker(new Hono(), Boolean(project.notifications)).route("/", admin);

package/dist/doctor/run.js

@@ -1,3 +1,4 @@
+import { userTablesOn } from "../config/user-tables-config.js";
 import { loadSourceConfig } from "../config/source-config.js";
 import { connect } from "../db/connect.js";
 import { introspect } from "../db/introspect.js";
@@ -9,6 +10,7 @@ import { indexIssues } from "./index-issues.js";
 import { readShapes } from "./read-shapes.js";
 import { relationIssues } from "./relation-issues.js";
 import { sortIssues } from "./sort-issues.js";
+import { userTableModels } from "./user-table-models.js";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { tableIndexes } from "@protobase/query";
@@ -18,26 +20,36 @@ const runDoctor = async (options, out) => {
 	if (!existsSync(path.join(options.configDir, "index.ts"))) throw new Error(`No config in ${options.configDir}: write it with \`protobase scaffold\`, or pass --config <dir>`);
 	const config = await loadDataConfig(options.configDir, options.projectDir);
 	if (config.models.length === 0) throw new Error(`No resources exported from ${options.configDir}/index.ts`);
-	const builtIn = builtInModels(await loadSourceConfig(options.projectDir, { command: "tool" }), config.models);
-	const models = [...builtIn.models, ...config.models];
+	const source = await loadSourceConfig(options.projectDir, { command: "tool" });
+	const builtIn = builtInModels(source, config.models);
 	const sql = connect(options.url);
 	const tables = await introspect(sql, { views: true }).finally(() => sql.end());
 	const db = readOnlyDb(options.url);
+	const userTables = userTablesOn(source) ? await userTableModels(db, [...builtIn.models, ...config.models]) : {
+		models: [],
+		issues: []
+	};
+	const models = [
+		...builtIn.models,
+		...config.models,
+		...userTables.models
+	];
 	const shapes = readShapes({
 		models,
 		views: [...builtIn.views, ...config.views],
 		pages: config.pages
 	});
 	const indexes = await Promise.all(models.map(async (model) => indexIssues(model, await tableIndexes(db, model), shapes))).then((found) => found.map((issues, i) => i < builtIn.models.length ? builtInIndexIssues(issues) : issues)).finally(() => db.destroy());
-	const issues = models.flatMap((model, i) => [
+	const issues = [...userTables.issues, ...models.flatMap((model, i) => [
 		...checkResource(model, tables),
 		...relationIssues(model, models),
 		...sortIssues(model, shapes),
 		...indexes[i]
-	]);
+	])];
 	for (const issue of issues) out(format(issue));
 	const errors = issues.filter((i) => i.severity === "error").length;
-	out(`Checked ${builtIn.models.length > 0 ? `${config.models.length} resources and ${builtIn.models.length} built-in ones` : `${models.length} resources`}: ${errors} errors, ${issues.length - errors} warnings.\n`);
+	const counted = userTables.models.length > 0 ? `${config.models.length} resources, ${userTables.models.length} user tables` : `${config.models.length} resources`;
+	out(`Checked ${builtIn.models.length > 0 ? `${counted} and ${builtIn.models.length} built-in ones` : counted}: ${errors} errors, ${issues.length - errors} warnings.\n`);
 	return {
 		errors,
 		warnings: issues.length - errors

package/dist/doctor/user-table-models.js

@@ -0,0 +1,26 @@
+import { userTableResources } from "@protobase/server/config-exports";
+//#region src/doctor/user-table-models.ts
+/**
+* The models of the tables users add, which doctor checks like the config's, and an error for each definition that
+* does not fit the database or whose name a resource in code has, as the server leaves those out.
+*/
+const userTableModels = async (db, codeModels) => {
+	const tables = await userTableResources(db);
+	const taken = new Set(codeModels.map((model) => model.name));
+	const built = tables.resources.map((source) => source.toModel());
+	const issues = [...tables.problems.map((message) => ({
+		severity: "error",
+		resource: "user tables",
+		message
+	})), ...built.filter((model) => taken.has(model.name)).map((model) => ({
+		severity: "warning",
+		resource: model.name,
+		message: "a resource in code has the name of this user table, which is not served"
+	}))];
+	return {
+		models: built.filter((model) => !taken.has(model.name)),
+		issues
+	};
+};
+//#endregion
+export { userTableModels };

package/dist/migration/load-project.js

@@ -1,5 +1,6 @@
 import { loadNearestEnvFile } from "../dev/env.js";
 import { projectJobs, projectNotifications, projectResources, projectWebhooks } from "../config/project-parts.js";
+import { userTablesOn } from "../config/user-tables-config.js";
 import { projectAuth } from "../config/build-project.js";
 import { loadSourceConfig } from "../config/source-config.js";
 import { openAppDatabase } from "../project/pg-db.js";
@@ -44,6 +45,7 @@ const migrationProject = async (config, url) => {
 		...notifications && { notifications },
 		...config.status && { status: checkStatusOptions(config.status) },
 		jobs,
+		userTables: userTablesOn(config),
 		readOnlyQueries: assistantSettings(config.assistant, process.env)?.kind === "built-in",
 		authTables: auth ? authStoreTables(auth) : {
 			tables: [],

package/dist/migration/parts.js

@@ -1,5 +1,5 @@
 import { authMigrationTitle } from "../auth/migration-file.js";
-import { authSchemaMigration, callsMigration, changesMigration, channelSendsMigration, commentsMigration, computedMigration, isCaptured, jobsSchemaMigration, notificationsMigration, queryRunnerMigration, realtimeRelayMigration, relayed, sqlSends, statusMigration, webhooksMigration } from "@protobase/server";
+import { authSchemaMigration, callsMigration, changesMigration, channelSendsMigration, commentsMigration, computedMigration, isCaptured, jobsSchemaMigration, notificationsMigration, queryRunnerMigration, realtimeRelayMigration, relayed, sqlSends, statusMigration, userTablesMigration, webhooksMigration } from "@protobase/server";
 //#region src/migration/parts.ts
 /** Every feature the project's config enables, in the order their files are written. */
 const migrationParts = (project) => {
@@ -61,6 +61,11 @@ const migrationParts = (project) => {
 			title: "The relay of Realtime broadcasts and presence between the processes serving the app",
 			sql: () => realtimeRelayMigration(project.db)
 		}] : [],
+		...project.userTables ? [{
+			name: "user_tables",
+			title: "The schemas of the tables users add and of their definitions, and pg_trgm",
+			sql: () => userTablesMigration(project.db)
+		}] : [],
 		...sqlSends(project.realtime) ? [{
 			name: "channel_sends",
 			title: "SQL's broadcasts to the record channels, channels.send()",

package/dist/project/project-admin.js

@@ -6,14 +6,20 @@ import { configExports, createAdmin } from "@protobase/server";
 * types and which icons are the project's own (`protobase dev` passes the project's icons alone). `jobs` are the
 * project's own and the delivery of its events and history. With a `reporter`, every error the API turns into a 500,
 * and every stopped query, goes to the error tracker too, besides the project's `onUnhandledError` or the console. With
-* the host's `upgradeWebSocket`, it serves `/api/sb/realtime/v1` too.
+* the host's `upgradeWebSocket`, it serves `/api/sb/realtime/v1` too. With `userTables`, the tables users add serve
+* beside the config's resources (see `readUserTables`). `report` is what the admin does with an unhandled error.
 */
-const projectAdmin = (project, db, ui, reporter, upgradeWebSocket) => {
+const projectAdmin = (project, db, ui, reporter, upgradeWebSocket, userTables) => {
 	const { resources, views, pages, userMenu, bottomBars, subscriptions } = configExports(project.config);
 	const unhandled = project.options?.onUnhandledError ?? ((error) => console.error(error));
+	const report = (error, request) => {
+		reporter?.report(error, request);
+		unhandled(error, request);
+	};
 	const admin = createAdmin({
 		resources,
 		views,
+		...userTables && { userTables },
 		pages,
 		...userMenu && { userMenu },
 		bottomBars,
@@ -42,15 +48,13 @@ const projectAdmin = (project, db, ui, reporter, upgradeWebSocket) => {
 		...upgradeWebSocket && { upgradeWebSocket },
 		options: {
 			...project.options,
-			onUnhandledError: (error, request) => {
-				reporter?.report(error, request);
-				unhandled(error, request);
-			}
+			onUnhandledError: report
 		}
 	});
 	return {
 		admin,
-		jobs: [...project.jobs, ...admin.jobs]
+		jobs: [...project.jobs, ...admin.jobs],
+		report
 	};
 };
 //#endregion

package/dist/project/project-user-tables.js

@@ -0,0 +1,10 @@
+import { userTableResources } from "@protobase/server";
+//#region src/project/project-user-tables.ts
+/** The tables users add, read from their definitions; each one that does not fit the database is printed as a warning and left out, so the rest of the app serves. */
+const readUserTables = async (db) => {
+	const tables = await userTableResources(db);
+	for (const problem of tables.problems) console.warn(problem);
+	return tables;
+};
+//#endregion
+export { readUserTables };

package/dist/project/served-admin.js

@@ -0,0 +1,29 @@
+import { projectAdmin } from "./project-admin.js";
+import { readUserTables } from "./project-user-tables.js";
+import { readDefinitionsVersion, reloadingAdmin } from "@protobase/server";
+//#region src/project/served-admin.ts
+/**
+* The admin a serving process answers with (`projectAdmin`). With `userTables`, it is rebuilt when the tables users add
+* change (`reloadingAdmin`); the version is read before the tables, so a change between the two reads rebuilds again.
+*/
+const servedAdmin = async (project, db, ui, reporter, upgradeWebSocket) => {
+	if (!project.userTables) return projectAdmin(project, db, ui, reporter, upgradeWebSocket);
+	const version = await readDefinitionsVersion(db);
+	const tables = await readUserTables(db);
+	const built = projectAdmin(project, db, ui, reporter, upgradeWebSocket, tables);
+	const admin = reloadingAdmin({
+		first: built.admin,
+		version,
+		readVersion: () => readDefinitionsVersion(db),
+		readTables: () => readUserTables(db),
+		build: (changed) => projectAdmin(project, db, ui, reporter, upgradeWebSocket, changed).admin,
+		report: built.report,
+		...project.options?.statementTimeoutMs !== void 0 && { statementTimeoutMs: project.options.statementTimeoutMs }
+	});
+	return {
+		...built,
+		admin
+	};
+};
+//#endregion
+export { servedAdmin };

package/dist/scaffold/plan.js

@@ -45,7 +45,7 @@ const planScaffold = async (input) => {
 	const byTable = new Map(existing.map((resource) => [resource.table, resource]));
 	const wanted = (table) => matchesTarget(input.target, table) && !isExcluded(input.excludes, table);
 	const tables = input.tables.filter((table) => table.kind === "table");
-	const protobase = protobaseSchemas(tables, input.target);
+	const protobase = protobaseSchemas(tables, input.target, new Set(byTable.keys()));
 	const skipped = protobase.map((found) => ({
 		...found,
 		tables: found.tables.filter(wanted)

package/dist/scaffold/protobase-tables.d.ts

@@ -2,7 +2,7 @@ import { DbTable } from "../db/model.js";
 //#region src/scaffold/protobase-tables.d.ts
 export type ProtobaseSchema = {
   schema: string;
-  what: 'auth store' | 'job queue' | 'record of migrations';
+  what: 'auth store' | 'job queue' | 'record of migrations' | 'table definitions' | 'user tables';
   tables: DbTable[];
 };
 //#endregion

package/dist/scaffold/protobase-tables.js

@@ -1,4 +1,6 @@
+import { tableKey } from "../db/model.js";
 import { migrationsTableName, storeTableNames } from "@protobase/server/auth-store";
+import { definitionsSchema, userTablesSchema } from "@protobase/server/config-exports";
 //#region src/scaffold/protobase-tables.ts
 const storeCore = [
 	"session",
@@ -21,14 +23,28 @@ const authStore = (schema, tables) => {
 };
 const jobQueue = (schema, tables) => schema === "jobs" && ["job", "version"].every((name) => tables.some((table) => table.name === name)) ? tables : [];
 const migrationRecord = (schema, tables) => schema === "migrations" && tables.some((table) => table.name === "applied") ? tables : [];
-const protobaseSchemas = (tables, target) => [...bySchema(tables)].flatMap(([schema, own]) => {
+const tableDefinitions = (schema, tables) => schema === definitionsSchema && ["tables", "fields"].every((name) => tables.some((table) => table.name === name)) ? tables : [];
+const userTables = (schema, tables, claimed) => schema === userTablesSchema ? tables.filter((table) => !claimed.has(tableKey(table))) : [];
+const protobaseSchemas = (tables, target, claimed = /* @__PURE__ */ new Set()) => [...bySchema(tables)].flatMap(([schema, own]) => {
 	const store = authStore(schema, own);
 	if (store.length > 0) return [{
 		schema,
 		what: "auth store",
 		tables: store
 	}];
+	const added = userTables(schema, own, claimed);
+	if (added.length > 0) return [{
+		schema,
+		what: "user tables",
+		tables: added
+	}];
 	if (target.schema === schema) return [];
+	const definitions = tableDefinitions(schema, own);
+	if (definitions.length > 0) return [{
+		schema,
+		what: "table definitions",
+		tables: definitions
+	}];
 	const queue = jobQueue(schema, own);
 	if (queue.length > 0) return [{
 		schema,

package/dist/serve/lifecycle.js

@@ -1,7 +1,7 @@
 import { protobaseVersion } from "../version/version.js";
 import { buildProject } from "../config/build-project.js";
 import { openAppDatabase } from "../project/pg-db.js";
-import { projectAdmin } from "../project/project-admin.js";
+import { servedAdmin } from "../project/served-admin.js";
 import { apiWebSocketServer } from "../project/api-websocket-server.js";
 import { withClientAddress } from "./client-address.js";
 import { createServeApp } from "./app.js";
@@ -9,7 +9,7 @@ import { startCleanupTimer } from "./cleanup-timer.js";
 import { closeSockets } from "./close-sockets.js";
 import { servedRelease } from "./mobile-release.js";
 import pg from "pg";
-import { assistantSettings, authStoreTables, backgroundSettled, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkWebhooksSchema, configExports, createFileCleanup, relayed, sqlSends, startJobs } from "@protobase/server";
+import { assistantSettings, authStoreTables, backgroundSettled, checkAi, checkAuthSchema, checkCalls, checkChanges, checkChannelSends, checkComments, checkComputed, checkJobsSchema, checkNotificationsSchema, checkQueryRunner, checkRealtimeRelay, checkResourcesOutsideAuthStore, checkStatusSchema, checkUserTablesSchema, checkWebhooksSchema, configExports, createFileCleanup, relayed, sqlSends, startJobs } from "@protobase/server";
 import { createAdaptorServer, upgradeWebSocket } from "@hono/node-server";
 //#region src/serve/lifecycle.ts
 const listen = (server, port) => new Promise((resolve, reject) => {
@@ -48,7 +48,8 @@ const startServe = async ({ config, env, openDb = (url) => openAppDatabase(pg, u
 		if (env.startupChecks && sqlSends(project.realtime)) await checkChannelSends(db);
 		if (env.startupChecks && project.notifications) await checkNotificationsSchema(db, project.notifications, project.auth);
 		if (env.startupChecks && project.status) await checkStatusSchema(db, project.status, project.auth);
-		const { admin, jobs: definitions } = projectAdmin(project, db, ui, reporter, upgradeWebSocket);
+		if (env.startupChecks && project.userTables) await checkUserTablesSchema(db);
+		const { admin, jobs: definitions } = await servedAdmin(project, db, ui, reporter, upgradeWebSocket);
 		if (env.startupChecks && definitions.length > 0) await checkJobsSchema(db);
 		const jobs = definitions.length > 0 ? await startJobs({
 			db,

package/dist/serve/load-bundle.js

@@ -1,4 +1,5 @@
 import { mergeConfig } from "../config/merge-config.js";
+import { checkUserTables } from "../config/user-tables-config.js";
 import { withDefaults } from "../config/config-defaults.js";
 import { calledConfig } from "../config/called-config.js";
 import { bundleBasePath } from "../bundle/manifest.js";
@@ -36,7 +37,7 @@ const bundledConfig = async (bundle, command, root) => {
 		files: projectFiles(files, bundle.packages),
 		label
 	});
-	const config = withDefaults(mergeConfig(...sources), command, process.env);
+	const config = checkUserTables(withDefaults(mergeConfig(...sources), command, process.env));
 	const basePath = config.apiPath;
 	if (basePath !== void 0 && basePath !== "/api/v1") throw new Error(`apiPath is ${JSON.stringify(basePath)}; a bundle's UI and manifest expect the API at ${bundleBasePath}, so remove it (see https://docs.protobase.net/reference/cli/#the-manifest)`);
 	return config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/cli",
-  "version": "0.67.0",
+  "version": "0.67.2",
   "description": "The protobase command: scaffold, doctor, dev, build and serve a Protobase project.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,12 +43,12 @@
   "dependencies": {
     "@better-auth/core": "^1.7.12",
     "@hono/node-server": "^2.1.3",
-    "@protobase/config": "0.67.0",
-    "@protobase/layout": "0.67.0",
-    "@protobase/query": "0.67.0",
-    "@protobase/schema": "0.67.0",
-    "@protobase/server": "0.67.0",
-    "@protobase/ui": "0.67.0",
+    "@protobase/config": "0.67.2",
+    "@protobase/layout": "0.67.2",
+    "@protobase/query": "0.67.2",
+    "@protobase/schema": "0.67.2",
+    "@protobase/server": "0.67.2",
+    "@protobase/ui": "0.67.2",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/vite-plugin": "^11.10.0",

package/skills/protobase/SKILL.md

@@ -101,6 +101,7 @@ Reference:
 - When using components and action handlers of your own in layouts → read [Custom components](references/reference/custom-components.md)
 - When building or loading plugins → read [Plugins](references/reference/plugins.md)
 - When using resources another Protobase API serves → read [Remote resources](references/reference/remote-resources.md)
+- When an app keeps tables its users add in its own database (`userTables`) → read [User tables](references/reference/user-tables.md)
 - When setting the app's tokens, colors and fonts → read [Theme](references/reference/theme.md)
 - When setting the app's name, icon, home-screen icons or install colours → read [App identity](references/reference/app-identity.md)
 - When showing the app's screens in Dutch → read [Languages](references/reference/languages.md)

package/skills/protobase/references/features/user-tables.md

@@ -0,0 +1,7 @@
+<!-- Generated by scripts/protobase-skill.ts from docs/website/src/content/docs/features/user-tables.md: run `bun run docs:skill`, do not edit. -->
+
+# Tables users add
+
+Tables an app's users add from the admin UI, by hand or from a file, and how a developer takes them over as code.
+
+- [Tables defined in the database](../reference/user-tables.md#tables-defined-in-the-database) (in development): An app can keep tables its users add in its own database, beside the resources in its code. Each one is served like any other resource, at its own address with its list, record page, search and API. Every server process serves a new table within a second of it being added.

package/skills/protobase/references/features.md

@@ -16,6 +16,7 @@ A feature without a mark is stable. The others say so after their name:
 
 - [Start a project](features/start-a-project.md): Start a new app, or an admin over an existing Postgres database, and keep the config in step with it.
 - [Data model](features/data-model.md): Describe the tables of an existing Postgres database as resources, with their fields, keys and rules.
+- [Tables users add](features/user-tables.md): Tables an app's users add from the admin UI, by hand or from a file, and how a developer takes them over as code.
 - [Access](features/access.md): Decide who may read and change which records and fields.
 - [Lists](features/lists.md): The list page of each resource, with its columns, filters, charts, search, exports and imports.
 - [List displays](features/list-displays.md): Show a list as cards, a map, a board, a calendar or a timeline, and reorder records by hand.

package/skills/protobase/references/reference/config/api.md

@@ -173,6 +173,17 @@ export default defineConfig(({ env }) => ({
 }))
 ```
 
+## userTables
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+`true` keeps the tables the app's users add in its own database, in the `table_definitions` and `user_tables` schemas that [`protobase migration`](../cli.md#migration) writes, and serves each one like a resource in code. It cannot be on together with organizations. See [User tables](../user-tables.md).
+
+```ts
+export default defineConfig({ userTables: true })
+```
+
 ## Code of the API
 
 Two files of the project's own change what the API does, each its default export, with no key in the config:

package/skills/protobase/references/reference/config.md

@@ -28,7 +28,7 @@ Each key is described with its type and default in the option pages:
 | --- | --- |
 | [App options](config/app.md) | `name`, `url`, `secret`, `previousSecrets`, `locale`, `timezone`, `themeColor`, `backgroundColor`, `mobile` |
 | [Sign-in options](config/sign-in.md) | `auth`, `authenticate`, `signingKeyDays`, `signingKeyGraceDays` |
-| [API options](config/api.md) | `apiPath`, `apiKeys`, `cors`, `defaultAccess`, `rowPermissions`, `statementTimeoutMs`, `scanGuard`, `errorReporting`, `writeHooks`, `mcpEndpoint`, `remoteResources`, `runtimeUpdates`, `realtime`, `calls` |
+| [API options](config/api.md) | `apiPath`, `apiKeys`, `cors`, `defaultAccess`, `rowPermissions`, `statementTimeoutMs`, `scanGuard`, `errorReporting`, `writeHooks`, `mcpEndpoint`, `remoteResources`, `runtimeUpdates`, `realtime`, `calls`, `userTables` |
 | [Admin app options](config/admin-app.md) | `assistant`, `maps`, `plugins` |
 | [Jobs and events options](config/jobs-and-events.md) | `jobs`, `events`, `history`, `webhooks`, `notifications`, `status` |
 | [Files options](config/files.md) | `files` |

package/skills/protobase/references/reference/user-tables.md

@@ -0,0 +1,83 @@
+<!-- Generated by scripts/protobase-skill.ts from docs/website/src/content/docs/reference/user-tables.md: run `bun run docs:skill`, do not edit. -->
+
+# User tables
+
+The switch that keeps tables users add in the app's own database, the two schemas they live in, the migration that adds them, and how each one is served.
+
+An app's resources usually come from its code: a resource in `config/` over a table a migration made. With user tables on, the app also keeps tables its users add in its own database, and serves each one beside the resources in code.
+
+## Tables defined in the database
+
+:::caution[In development]
+The server serves the tables defined in the database, but no screen or API adds one yet.
+:::
+
+An app can keep tables its users add in its own database, beside the resources in its code. Each one is served like any other resource, at its own address with its list, record page, search and API. Every server process serves a new table within a second of it being added.
+
+<gap>Tables users add cannot be used in an app with organizations because keeping their definitions and records per organization is not implemented.</gap>
+
+<gap>Users cannot add a table yet because the screens and the API that create one are not implemented.</gap>
+
+### The switch
+
+User tables are off by default. Turn them on in `protobase.config.ts`:
+
+```ts
+export default defineConfig({ userTables: true })
+```
+
+`userTables` takes only `true` or `false`. Together with organizations (`auth.organizations`), `dev`, `build` and `serve` stop with an error that names both settings.
+
+### The schemas and the migration
+
+The tables users add and their definitions live in two schemas of the app's database, so a table's name can never reach a definition:
+
+| Schema | What it holds |
+| --- | --- |
+| `table_definitions` | `tables`, one row per table users add, with its singular and plural label, its title field and a version, and `fields`, each table's fields in order with their label, type and whether they are required |
+| `user_tables` | the tables themselves, each with an `id bigint generated always as identity` primary key and a column per field |
+
+With `userTables: true`, [`protobase migration`](cli.md#migration) writes a migration that adds both schemas, the two definition tables and the `pg_trgm` extension when it is missing, and grants the app's database role CREATE on `user_tables` alone, and writes nothing once the database has them. Apply it with the project's other migrations; the server never creates them itself. At start, `dev` and `serve` stop while one is missing; `PROTOBASE_STARTUP_CHECKS=false` skips that check in `serve`, as it skips the others.
+
+A table's name and each field's name are lowercase letters, digits and `_`, starting with a letter, at most 63 bytes. A field is one of these types:
+
+| Type | Column |
+| --- | --- |
+| `text` | `text` |
+| `long_text` | `text`, edited in a box that grows with it |
+| `integer` | `integer` |
+| `decimal` | `numeric`, with the definition's precision and scale |
+| `boolean` | `boolean` |
+| `date` | `date` |
+| `timestamp` | `timestamptz` |
+| `json` | `jsonb` |
+
+### How each one is served
+
+When the server starts, and whenever the definitions change, it builds a resource from each definition and serves it at `/<table>` and `/<table>/<key>`, with its list, record page, sidebar entry and REST API, and in `/meta`, as the resources in code are. The labels of the definition are the names the admin app shows.
+
+- **Admins only.** Each table starts readable and writable by admins alone, and is left out of role wildcards such as `*.read`, like [resources that need named grants](access.md#resources-that-need-named-grants). Anyone else does not see it.
+- **Filters, sorts and search follow the indexes.** A field can be filtered or sorted by only where an index of its table serves it, and the table is searched on its title field only where a `pg_trgm` index serves that field, as the [scan guard](config/api.md#scanguard) requires.
+- **A definition that does not fit is left out.** A definition with a name or type outside the rules above, or whose table or columns do not match it, is not served, and the server prints why at start. The rest of the app serves.
+- **Code wins.** A resource in code with the name of a user table, or a resource Protobase adds, is served instead of the definition, which is then ignored with a warning. This is how a table users added is taken over as code.
+
+[`protobase doctor`](cli.md#doctor) checks each definition against the database as it checks the resources in code, and reports each one it leaves out as an error. [`protobase scaffold`](cli.md#scaffold) leaves out the definitions and the tables in `user_tables` that no resource in code claims, and writes and updates the config of one that a resource claims.
+
+### How a change reaches every process
+
+A definition added, changed or removed is served by every process of `serve` and `dev` within a second, with no restart or deploy. Each process rebuilds its API from the resources in code and the definitions as they are now, and the admin app reads `/meta` again once `X-Meta-Version` changes, as after any change of the app.
+
+- **When a process looks.** `/meta` reads the version of the definitions before it answers. Any other request reads it at most once a second, and once more when its answer would be not found or invalid, as for a resource or field the process does not know yet; it is then answered by the API built anew. The process that makes a change rebuilds at once. A process that receives no request reads nothing, so a database that scales to zero stays asleep.
+- **What a look costs.** The version is one read of `table_definitions.tables`, under a millisecond. Each change of a definition or its fields must raise the definition's `version`; adding and removing a definition change the version on their own.
+- **What a rebuild costs.** A rebuild reads the definitions and the indexes of each table, then builds the API, once per process: requests that need it meanwhile wait for that one rebuild. Requests already running finish on the API they started with, and an open WebSocket keeps the API it opened with. <gap>A channel socket opened before a rebuild cannot hear a broadcast sent through a socket opened after it, in the same process and without a realtime relay, until it reconnects, because moving open sockets to the rebuilt API is not implemented.</gap> <gap>A request whose body is not JSON, such as a file upload, that names a table added under a second ago cannot be answered by the rebuilt API because replaying a streamed body is not implemented; it is answered not found, and works on the next try.</gap>
+
+Measured with six fields per table on one machine running Postgres and the processes:
+
+| Tables users add | Rebuild, one process | Rebuild, each of four processes at once |
+| --- | --- | --- |
+| 10 | under 0.1 s | under 0.1 s |
+| 50 | about 0.1 s | about 0.4 s |
+| 200 | about 0.7 s | about 1.4 s |
+| 500 | about 2.2 s | about 4.5 s |
+
+- **A rebuild that fails.** When the API does not build with the new definitions, the process reports why through `onUnhandledError`, naming what it refused, and keeps serving the API it had, with the resources in code. A definition that does not fit the database is left out with a warning, as at start.