@pgpm/services 0.17.0 → 0.18.0

package/__tests__/__snapshots__/services.test.ts.snap

@@ -7,9 +7,7 @@ exports[`services functionality should handle complete meta workflow with servic
   "label": null,
   "name": "my-meta-db",
   "owner_id": "[ID]",
-  "private_schema_name": null,
   "schema_hash": null,
-  "schema_name": null,
 }
 `;
 

package/deploy/schemas/services_private/triggers/enforce_api_schema_table_name_uniqueness.sql

@@ -0,0 +1,47 @@
+-- Deploy schemas/services_private/triggers/enforce_api_schema_table_name_uniqueness to pg
+
+-- requires: schemas/services_private/schema
+-- requires: schemas/services_public/tables/api_schemas/table
+-- requires: metaschema-schema:schemas/metaschema_public/tables/table/table
+-- requires: metaschema-schema:schemas/metaschema_public/tables/table/indexes/databases_table_unique_name_idx
+
+BEGIN;
+
+-- When linking a schema to an API, check that none of its tables conflict
+-- (by plural-hash) with tables already exposed through that API's other schemas.
+CREATE FUNCTION services_private.tg_enforce_api_schema_table_name_uniqueness()
+RETURNS TRIGGER AS $$
+DECLARE
+  conflicting_new_table text;
+  conflicting_existing_table text;
+BEGIN
+  -- Find any table name collision between the newly linked schema
+  -- and any schema already linked to the same API
+  SELECT new_t.name, existing_t.name
+  INTO conflicting_new_table, conflicting_existing_table
+  FROM metaschema_public.table AS new_t
+  JOIN services_public.api_schemas AS existing_link
+    ON existing_link.api_id = NEW.api_id
+    AND existing_link.schema_id IS DISTINCT FROM NEW.schema_id
+  JOIN metaschema_public.table AS existing_t
+    ON existing_t.schema_id = existing_link.schema_id
+    AND metaschema_private.table_name_hash(existing_t.name) = metaschema_private.table_name_hash(new_t.name)
+  WHERE new_t.schema_id = NEW.schema_id
+  LIMIT 1;
+
+  IF conflicting_new_table IS NOT NULL THEN
+    RAISE EXCEPTION 'Cannot link schema to API: table "%" conflicts with existing table "%" already exposed in this API. Table names must be unique (by plural form) across all schemas within the same API.',
+      conflicting_new_table, conflicting_existing_table;
+  END IF;
+
+  RETURN NEW;
+END;
+$$
+LANGUAGE plpgsql VOLATILE;
+
+CREATE TRIGGER _000001_enforce_api_schema_table_name_uniqueness
+BEFORE INSERT ON services_public.api_schemas
+FOR EACH ROW
+EXECUTE FUNCTION services_private.tg_enforce_api_schema_table_name_uniqueness();
+
+COMMIT;

package/deploy/schemas/services_private/triggers/enforce_api_table_name_uniqueness.sql

@@ -0,0 +1,60 @@
+-- Deploy schemas/services_private/triggers/enforce_api_table_name_uniqueness to pg
+
+-- requires: schemas/services_private/schema
+-- requires: schemas/services_public/tables/api_schemas/table
+-- requires: metaschema-schema:schemas/metaschema_public/tables/table/table
+-- requires: metaschema-schema:schemas/metaschema_public/tables/table/indexes/databases_table_unique_name_idx
+
+BEGIN;
+
+-- Enforce that table names are unique (by plural-hash) across all schemas within each API.
+-- This allows different APIs to have tables with the same name, but prevents
+-- collisions within a single API where multiple schemas are exposed together.
+CREATE FUNCTION services_private.tg_enforce_api_table_name_uniqueness()
+RETURNS TRIGGER AS $$
+DECLARE
+  new_name_hash bytea;
+  conflicting_api_name text;
+  conflicting_table_name text;
+BEGIN
+  -- Compute the plural-hash of the new table name
+  new_name_hash := metaschema_private.table_name_hash(NEW.name);
+
+  -- Check if any API that includes this table's schema also includes
+  -- another schema containing a table with the same name hash
+  SELECT a.name, t.name
+  INTO conflicting_api_name, conflicting_table_name
+  FROM services_public.api_schemas AS my_api
+  JOIN services_public.api_schemas AS other_api
+    ON other_api.api_id = my_api.api_id
+    AND other_api.schema_id IS DISTINCT FROM NEW.schema_id
+  JOIN metaschema_public.table AS t
+    ON t.schema_id = other_api.schema_id
+    AND metaschema_private.table_name_hash(t.name) = new_name_hash
+  JOIN services_public.apis AS a
+    ON a.id = my_api.api_id
+  WHERE my_api.schema_id = NEW.schema_id
+  LIMIT 1;
+
+  IF conflicting_api_name IS NOT NULL THEN
+    RAISE EXCEPTION 'Table name "%" conflicts with existing table "%" in API "%". Table names must be unique (by plural form) across all schemas within the same API.',
+      NEW.name, conflicting_table_name, conflicting_api_name;
+  END IF;
+
+  RETURN NEW;
+END;
+$$
+LANGUAGE plpgsql VOLATILE;
+
+CREATE TRIGGER _000003_enforce_api_table_name_uniqueness
+BEFORE INSERT ON metaschema_public.table
+FOR EACH ROW
+EXECUTE FUNCTION services_private.tg_enforce_api_table_name_uniqueness();
+
+CREATE TRIGGER _000003_enforce_api_table_name_uniqueness_update
+BEFORE UPDATE ON metaschema_public.table
+FOR EACH ROW
+WHEN (NEW.name IS DISTINCT FROM OLD.name OR NEW.schema_id IS DISTINCT FROM OLD.schema_id)
+EXECUTE FUNCTION services_private.tg_enforce_api_table_name_uniqueness();
+
+COMMIT;

package/deploy/schemas/services_public/tables/api_modules/table.sql

@@ -19,6 +19,13 @@ CREATE TABLE services_public.api_modules (
 
 );
 
+COMMENT ON TABLE services_public.api_modules IS 'Server-side module configuration for an API endpoint; stores module name and JSON settings used by the application server';
+COMMENT ON COLUMN services_public.api_modules.id IS 'Unique identifier for this API module record';
+COMMENT ON COLUMN services_public.api_modules.database_id IS 'Reference to the metaschema database';
+COMMENT ON COLUMN services_public.api_modules.api_id IS 'API this module configuration belongs to';
+COMMENT ON COLUMN services_public.api_modules.name IS 'Module name (e.g. auth, uploads, webhooks)';
+COMMENT ON COLUMN services_public.api_modules.data IS 'JSON configuration data for this module';
+
 ALTER TABLE services_public.api_modules ADD CONSTRAINT api_modules_api_id_fkey FOREIGN KEY ( api_id ) REFERENCES services_public.apis ( id );
 COMMENT ON CONSTRAINT api_modules_api_id_fkey ON services_public.api_modules IS E'@omit manyToMany';
 CREATE INDEX api_modules_api_id_idx ON services_public.api_modules ( api_id );

package/deploy/schemas/services_public/tables/api_schemas/table.sql

@@ -18,6 +18,12 @@ CREATE TABLE services_public.api_schemas (
   unique(api_id, schema_id)
 );
 
+COMMENT ON TABLE services_public.api_schemas IS 'Join table linking APIs to the database schemas they expose; controls which schemas are accessible through each API';
+COMMENT ON COLUMN services_public.api_schemas.id IS 'Unique identifier for this API-schema mapping';
+COMMENT ON COLUMN services_public.api_schemas.database_id IS 'Reference to the metaschema database';
+COMMENT ON COLUMN services_public.api_schemas.schema_id IS 'Metaschema schema being exposed through the API';
+COMMENT ON COLUMN services_public.api_schemas.api_id IS 'API that exposes this schema';
+
 -- COMMENT ON CONSTRAINT schema_fkey ON services_public.api_schemas IS E'@omit manyToMany';
 -- COMMENT ON CONSTRAINT api_fkey ON services_public.api_schemas IS E'@omit manyToMany';
 COMMENT ON CONSTRAINT db_fkey ON services_public.api_schemas IS E'@omit manyToMany';

package/deploy/schemas/services_public/tables/apis/table.sql

@@ -20,6 +20,15 @@ CREATE TABLE services_public.apis (
     UNIQUE(database_id, name)
 );
 
+COMMENT ON TABLE services_public.apis IS 'API endpoint configurations: each record defines a PostGraphile/PostgREST API with its database role and public access settings';
+COMMENT ON COLUMN services_public.apis.id IS 'Unique identifier for this API';
+COMMENT ON COLUMN services_public.apis.database_id IS 'Reference to the metaschema database this API serves';
+COMMENT ON COLUMN services_public.apis.name IS 'Unique name for this API within its database';
+COMMENT ON COLUMN services_public.apis.dbname IS 'PostgreSQL database name to connect to';
+COMMENT ON COLUMN services_public.apis.role_name IS 'PostgreSQL role used for authenticated requests';
+COMMENT ON COLUMN services_public.apis.anon_role IS 'PostgreSQL role used for anonymous/unauthenticated requests';
+COMMENT ON COLUMN services_public.apis.is_public IS 'Whether this API is publicly accessible without authentication';
+
 COMMENT ON CONSTRAINT db_fkey ON services_public.apis IS E'@omit manyToMany';
 CREATE INDEX apis_database_id_idx ON services_public.apis ( database_id );
 

package/deploy/schemas/services_public/tables/apps/table.sql

@@ -23,6 +23,17 @@ CREATE TABLE services_public.apps (
     UNIQUE ( site_id )
 );
 
+COMMENT ON TABLE services_public.apps IS 'Mobile and native app configuration linked to a site, including store links and identifiers';
+COMMENT ON COLUMN services_public.apps.id IS 'Unique identifier for this app';
+COMMENT ON COLUMN services_public.apps.database_id IS 'Reference to the metaschema database this app belongs to';
+COMMENT ON COLUMN services_public.apps.site_id IS 'Site this app is associated with (one app per site)';
+COMMENT ON COLUMN services_public.apps.name IS 'Display name of the app';
+COMMENT ON COLUMN services_public.apps.app_image IS 'App icon or promotional image';
+COMMENT ON COLUMN services_public.apps.app_store_link IS 'URL to the Apple App Store listing';
+COMMENT ON COLUMN services_public.apps.app_store_id IS 'Apple App Store application identifier';
+COMMENT ON COLUMN services_public.apps.app_id_prefix IS 'Apple App ID prefix (Team ID) for universal links and associated domains';
+COMMENT ON COLUMN services_public.apps.play_store_link IS 'URL to the Google Play Store listing';
+
 ALTER TABLE services_public.apps ADD CONSTRAINT apps_site_id_fkey FOREIGN KEY ( site_id ) REFERENCES services_public.sites ( id );
 COMMENT ON CONSTRAINT apps_site_id_fkey ON services_public.apps IS E'@omit manyToMany';
 CREATE INDEX apps_site_id_idx ON services_public.apps ( site_id );

package/deploy/schemas/services_public/tables/domains/table.sql

@@ -29,6 +29,14 @@ CREATE TABLE services_public.domains (
     UNIQUE ( subdomain, domain )
 );
 
+COMMENT ON TABLE services_public.domains IS 'DNS domain and subdomain routing: maps hostnames to either an API endpoint or a site';
+COMMENT ON COLUMN services_public.domains.id IS 'Unique identifier for this domain record';
+COMMENT ON COLUMN services_public.domains.database_id IS 'Reference to the metaschema database this domain belongs to';
+COMMENT ON COLUMN services_public.domains.api_id IS 'API endpoint this domain routes to (mutually exclusive with site_id)';
+COMMENT ON COLUMN services_public.domains.site_id IS 'Site this domain routes to (mutually exclusive with api_id)';
+COMMENT ON COLUMN services_public.domains.subdomain IS 'Subdomain portion of the hostname';
+COMMENT ON COLUMN services_public.domains.domain IS 'Root domain of the hostname';
+
 COMMENT ON CONSTRAINT db_fkey ON services_public.domains IS E'@omit manyToMany';
 CREATE INDEX domains_database_id_idx ON services_public.domains ( database_id );
 

package/deploy/schemas/services_public/tables/site_metadata/table.sql

@@ -23,6 +23,14 @@ CREATE TABLE services_public.site_metadata (
 );
 
 
+COMMENT ON TABLE services_public.site_metadata IS 'SEO and social sharing metadata for a site: page title, description, and Open Graph image';
+COMMENT ON COLUMN services_public.site_metadata.id IS 'Unique identifier for this metadata record';
+COMMENT ON COLUMN services_public.site_metadata.database_id IS 'Reference to the metaschema database';
+COMMENT ON COLUMN services_public.site_metadata.site_id IS 'Site this metadata belongs to';
+COMMENT ON COLUMN services_public.site_metadata.title IS 'Page title for SEO (max 120 characters)';
+COMMENT ON COLUMN services_public.site_metadata.description IS 'Meta description for SEO and social sharing (max 120 characters)';
+COMMENT ON COLUMN services_public.site_metadata.og_image IS 'Open Graph image for social media previews';
+
 ALTER TABLE services_public.site_metadata ADD CONSTRAINT site_metadata_site_id_fkey FOREIGN KEY ( site_id ) REFERENCES services_public.sites ( id );
 COMMENT ON CONSTRAINT site_metadata_site_id_fkey ON services_public.site_metadata IS E'@omit manyToMany';
 CREATE INDEX site_metadata_site_id_idx ON services_public.site_metadata ( site_id );

package/deploy/schemas/services_public/tables/site_modules/table.sql

@@ -17,6 +17,13 @@ CREATE TABLE services_public.site_modules (
     CONSTRAINT db_fkey FOREIGN KEY (database_id) REFERENCES metaschema_public.database (id) ON DELETE CASCADE
 );
 
+COMMENT ON TABLE services_public.site_modules IS 'Site-level module configuration; stores module name and JSON settings used by the frontend or server for each site';
+COMMENT ON COLUMN services_public.site_modules.id IS 'Unique identifier for this site module record';
+COMMENT ON COLUMN services_public.site_modules.database_id IS 'Reference to the metaschema database';
+COMMENT ON COLUMN services_public.site_modules.site_id IS 'Site this module configuration belongs to';
+COMMENT ON COLUMN services_public.site_modules.name IS 'Module name (e.g. user_auth_module, analytics)';
+COMMENT ON COLUMN services_public.site_modules.data IS 'JSON configuration data for this module';
+
 ALTER TABLE services_public.site_modules ADD CONSTRAINT site_modules_site_id_fkey FOREIGN KEY ( site_id ) REFERENCES services_public.sites ( id );
 COMMENT ON CONSTRAINT site_modules_site_id_fkey ON services_public.site_modules IS E'@omit manyToMany';
 CREATE INDEX site_modules_site_id_idx ON services_public.site_modules ( site_id );

package/deploy/schemas/services_public/tables/site_themes/table.sql

@@ -17,6 +17,12 @@ CREATE TABLE services_public.site_themes (
     CONSTRAINT db_fkey FOREIGN KEY (database_id) REFERENCES metaschema_public.database (id) ON DELETE CASCADE
 );
 
+COMMENT ON TABLE services_public.site_themes IS 'Theme configuration for a site; stores design tokens, colors, and typography as JSONB';
+COMMENT ON COLUMN services_public.site_themes.id IS 'Unique identifier for this theme record';
+COMMENT ON COLUMN services_public.site_themes.database_id IS 'Reference to the metaschema database';
+COMMENT ON COLUMN services_public.site_themes.site_id IS 'Site this theme belongs to';
+COMMENT ON COLUMN services_public.site_themes.theme IS 'JSONB object containing theme tokens (colors, typography, spacing, etc.)';
+
 ALTER TABLE services_public.site_themes ADD CONSTRAINT site_themes_site_id_fkey FOREIGN KEY ( site_id ) REFERENCES services_public.sites ( id );
 COMMENT ON CONSTRAINT site_themes_site_id_fkey ON services_public.site_themes IS E'@omit manyToMany';
 CREATE INDEX site_themes_site_id_idx ON services_public.site_themes ( site_id );

package/deploy/schemas/services_public/tables/sites/table.sql

@@ -24,6 +24,17 @@ CREATE TABLE services_public.sites (
   CONSTRAINT max_descr CHECK ( character_length(description) <= 120 )
 );
 
+COMMENT ON TABLE services_public.sites IS 'Top-level site configuration: branding assets, title, and description for a deployed application';
+COMMENT ON COLUMN services_public.sites.id IS 'Unique identifier for this site';
+COMMENT ON COLUMN services_public.sites.database_id IS 'Reference to the metaschema database this site belongs to';
+COMMENT ON COLUMN services_public.sites.title IS 'Display title for the site (max 120 characters)';
+COMMENT ON COLUMN services_public.sites.description IS 'Short description of the site (max 120 characters)';
+COMMENT ON COLUMN services_public.sites.og_image IS 'Open Graph image used for social media link previews';
+COMMENT ON COLUMN services_public.sites.favicon IS 'Browser favicon attachment';
+COMMENT ON COLUMN services_public.sites.apple_touch_icon IS 'Apple touch icon for iOS home screen bookmarks';
+COMMENT ON COLUMN services_public.sites.logo IS 'Primary logo image for the site';
+COMMENT ON COLUMN services_public.sites.dbname IS 'PostgreSQL database name this site connects to';
+
 COMMENT ON CONSTRAINT db_fkey ON services_public.sites IS E'@omit manyToMany';
 CREATE INDEX sites_database_id_idx ON services_public.sites ( database_id );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgpm/services",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Services schemas for module registration and service configuration",
   "author": "Dan Lynch <pyramation@gmail.com>",
   "contributors": [
@@ -21,11 +21,11 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@pgpm/metaschema-schema": "0.17.0",
-    "@pgpm/verify": "0.17.0"
+    "@pgpm/metaschema-schema": "0.18.0",
+    "@pgpm/verify": "0.18.0"
   },
   "devDependencies": {
-    "pgpm": "^1.3.0"
+    "pgpm": "^4.2.3"
   },
   "repository": {
     "type": "git",
@@ -35,5 +35,5 @@
   "bugs": {
     "url": "https://github.com/constructive-io/constructive-db/issues"
   },
-  "gitHead": "8eb8b9e3a6784fb45a3a9e86838f8417f061925c"
+  "gitHead": "8144027c7fab4956bcdebd736d04c0d4f57344bc"
 }

package/pgpm.plan

@@ -13,3 +13,5 @@ schemas/services_public/tables/domains/table [schemas/services_public/schema sch
 schemas/services_public/tables/site_metadata/table [schemas/services_public/schema schemas/services_public/tables/sites/table metaschema-schema:schemas/metaschema_public/tables/database/table] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/services_public/tables/site_metadata/table
 schemas/services_public/tables/site_modules/table [schemas/services_public/schema schemas/services_public/tables/sites/table metaschema-schema:schemas/metaschema_public/tables/database/table] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/services_public/tables/site_modules/table
 schemas/services_public/tables/site_themes/table [schemas/services_public/schema schemas/services_public/tables/sites/table metaschema-schema:schemas/metaschema_public/tables/database/table] 2017-08-11T08:11:51Z skitch <skitch@5b0c196eeb62> # add schemas/services_public/tables/site_themes/table
+schemas/services_private/triggers/enforce_api_table_name_uniqueness [schemas/services_private/schema schemas/services_public/tables/api_schemas/table metaschema-schema:schemas/metaschema_public/tables/table/table metaschema-schema:schemas/metaschema_public/tables/table/indexes/databases_table_unique_name_idx] 2026-02-27T00:00:00Z devin <devin@cognition.ai> # add API-level table name uniqueness trigger
+schemas/services_private/triggers/enforce_api_schema_table_name_uniqueness [schemas/services_private/schema schemas/services_public/tables/api_schemas/table metaschema-schema:schemas/metaschema_public/tables/table/table metaschema-schema:schemas/metaschema_public/tables/table/indexes/databases_table_unique_name_idx] 2026-02-27T00:00:00Z devin <devin@cognition.ai> # add API-schema link table name uniqueness trigger

package/revert/schemas/services_private/triggers/enforce_api_schema_table_name_uniqueness.sql

@@ -0,0 +1,8 @@
+-- Revert schemas/services_private/triggers/enforce_api_schema_table_name_uniqueness
+
+BEGIN;
+
+DROP TRIGGER IF EXISTS _000001_enforce_api_schema_table_name_uniqueness ON services_public.api_schemas;
+DROP FUNCTION IF EXISTS services_private.tg_enforce_api_schema_table_name_uniqueness();
+
+COMMIT;

package/revert/schemas/services_private/triggers/enforce_api_table_name_uniqueness.sql

@@ -0,0 +1,9 @@
+-- Revert schemas/services_private/triggers/enforce_api_table_name_uniqueness
+
+BEGIN;
+
+DROP TRIGGER IF EXISTS _000003_enforce_api_table_name_uniqueness_update ON metaschema_public.table;
+DROP TRIGGER IF EXISTS _000003_enforce_api_table_name_uniqueness ON metaschema_public.table;
+DROP FUNCTION IF EXISTS services_private.tg_enforce_api_table_name_uniqueness();
+
+COMMIT;

package/verify/schemas/services_private/triggers/enforce_api_schema_table_name_uniqueness.sql

@@ -0,0 +1,10 @@
+-- Verify schemas/services_private/triggers/enforce_api_schema_table_name_uniqueness
+
+BEGIN;
+
+SELECT has_function_privilege(
+  'services_private.tg_enforce_api_schema_table_name_uniqueness()',
+  'execute'
+);
+
+ROLLBACK;

package/verify/schemas/services_private/triggers/enforce_api_table_name_uniqueness.sql

@@ -0,0 +1,10 @@
+-- Verify schemas/services_private/triggers/enforce_api_table_name_uniqueness
+
+BEGIN;
+
+SELECT has_function_privilege(
+  'services_private.tg_enforce_api_table_name_uniqueness()',
+  'execute'
+);
+
+ROLLBACK;