@nsshunt/stsdatamanagement 1.18.195 → 1.18.198

package/db-scripts/builddb.sql

@@ -443,6 +443,7 @@ ALTER TABLE public.stsresource
 
 -- DROP INDEX public.stsresource_resname_vnum;
 
+-- Enforce resource version uniqueness.
 CREATE UNIQUE INDEX stsresource_resname_vnum
     ON public.stsresource USING btree
     (resname COLLATE pg_catalog."default" ASC NULLS LAST, vnum ASC NULLS LAST)
@@ -452,12 +453,14 @@ CREATE UNIQUE INDEX stsresource_resname_vnum
 
 -- DROP INDEX public.stsresource_resname_validto;
 
+-- General current-version lookup.
+-- Includes current deleted records.
 CREATE INDEX stsresource_resname_validto
     ON public.stsresource USING btree
     (resname COLLATE pg_catalog."default" ASC NULLS LAST, validto DESC NULLS LAST)
     TABLESPACE pg_default;
 
-
+/*
 -- DROP INDEX public.stsresource_given;
 
 CREATE INDEX stsresource_given
@@ -471,6 +474,15 @@ CREATE INDEX stsresource_family
     ON public.stsresource USING btree
     (family COLLATE pg_catalog."default" ASC)
 	WHERE family IS NOT NULL;
+*/
+
+-- DROP INDEX public.idx_stsresource_resname_current;
+
+-- Normal application reads and cursor-based pagination.
+CREATE INDEX idx_stsresource_resname_current
+ON public.stsresource (resname, oid)
+WHERE validto IS NULL
+  AND dbaction != 3;
 
 -- FUNCTION: public.create_stsresource(character varying, character varying, character varying)
 
@@ -564,7 +576,7 @@ ALTER FUNCTION public.create_stsresource(character varying, character varying, c
 CREATE OR REPLACE FUNCTION public.update_stsresource(
 	_dbactionuser character varying,
 	_resname character varying,
-	_resvnum integer,
+	_resvnum bigint,
 	_resdesc character varying)
     RETURNS SETOF stsresource 
     LANGUAGE 'plpgsql'
@@ -616,13 +628,10 @@ BEGIN
 END;
 $BODY$;
 
-ALTER FUNCTION public.update_stsresource(character varying, character varying, integer, character varying)
+ALTER FUNCTION public.update_stsresource(character varying, character varying, bigint, character varying)
     OWNER TO postgres;
 
 
--- FUNCTION: public.update_stsresource(character varying, character varying, integer, character varying)
-
--- DROP FUNCTION public.update_stsresource(character varying, character varying, integer, character varying);
 
 CREATE OR REPLACE FUNCTION public.update_stsresource_latest(
 	_dbactionuser character varying,
@@ -640,7 +649,7 @@ declare
 	_now timestamp without time zone := now();
 	resoid bigint;
 	newresoid stsresource.oid%TYPE;
-	_resvnum integer;
+	_resvnum bigint;
 	_resdesc_jsonb JSONB;
 	_given character varying(64) COLLATE pg_catalog."default";
 	_family character varying(64) COLLATE pg_catalog."default";
@@ -691,14 +700,11 @@ ALTER FUNCTION public.update_stsresource_latest(character varying, character var
 
 
 
--- FUNCTION: public.delete_stsresource(character varying, character varying, integer)
-
--- DROP FUNCTION public.delete_stsresource(character varying, character varying, integer);
 
 CREATE OR REPLACE FUNCTION public.delete_stsresource(
 	_dbactionuser character varying,
 	_resname character varying,
-	_resvnum integer)
+	_resvnum bigint)
     RETURNS SETOF stsresource 
     LANGUAGE 'plpgsql'
 
@@ -738,7 +744,7 @@ BEGIN
 END;
 $BODY$;
 
-ALTER FUNCTION public.delete_stsresource(character varying, character varying, integer)
+ALTER FUNCTION public.delete_stsresource(character varying, character varying, bigint)
     OWNER TO postgres;
 
 
@@ -758,7 +764,7 @@ declare
 	_now timestamp without time zone := now();
 	resoid bigint;
 	newresoid stsresource.oid%TYPE;
-	_resvnum integer;
+	_resvnum bigint;
 BEGIN
 	begin
 		_resvnum := (select vnum from stsresource r where r.resname = _resname and r.validto is null and r.dbaction != 3);
@@ -798,8 +804,6 @@ ALTER FUNCTION public.delete_stsresource_latest(character varying, character var
 
 
 
-
-
 -- Table: public.stsentity
 
 -- DROP TABLE public.stsentity;
@@ -831,141 +835,491 @@ ALTER TABLE public.stsentity
 
 -- DROP INDEX public.stsentity_resourceoid_entname_vnum;
 
+-- Enforce entity version uniqueness.
 CREATE UNIQUE INDEX stsentity_resourceoid_entname_vnum
     ON public.stsentity USING btree
-    (resourceoid ASC NULLS LAST, entname COLLATE pg_catalog."default" ASC NULLS LAST, vnum ASC NULLS LAST)
+	(resourceoid ASC NULLS LAST, entname COLLATE pg_catalog."default" ASC NULLS LAST, vnum ASC NULLS LAST)
     TABLESPACE pg_default;
 
--- Index: stsentity_resourceoid_entname_validto
-
--- DROP INDEX public.stsentity_resourceoid_entname_validto;
-
+-- General current/version lookup.
 CREATE INDEX stsentity_resourceoid_entname_validto
     ON public.stsentity USING btree
     (resourceoid ASC NULLS LAST, entname COLLATE pg_catalog."default" ASC NULLS LAST, validto DESC NULLS LAST)
     TABLESPACE pg_default;
 
+-- Normal application reads and cursor-based pagination.
+CREATE UNIQUE INDEX idx_stsentity_resourceoid_entname_current
+	ON public.stsentity
+	(resourceoid, entname)
+	WHERE validto IS NULL;
 
--- FUNCTION: public.create_stsentity(character varying, character varying, integer, character varying, character varying)
-
--- DROP FUNCTION public.create_stsentity(character varying, character varying, integer, character varying, character varying);
 
 CREATE OR REPLACE FUNCTION public.create_stsentity(
 	_dbactionuser character varying,
 	_resname character varying,
-	_resvnum integer,
+	_resvnum bigint,
 	_entname character varying,
-	_entvalue character varying)
-    RETURNS SETOF stsentity 
-    LANGUAGE 'plpgsql'
+	_entvalue character varying
+)
+RETURNS SETOF stsentity
+LANGUAGE 'plpgsql'
+COST 100
+VOLATILE
+ROWS 1000
 
-    COST 100
-    VOLATILE 
-    ROWS 1000
-    
 AS $BODY$
-declare
-	resoid bigint;
+DECLARE
+	__now timestamp without time zone := now();
+
+	-- Current resource.
+	__resoid bigint;
+
+	-- Current entity, if one exists.
+	__entoid bigint;
+	__entvnum bigint;
+	__entdbaction smallint;
+
+	-- Version to assign to the newly created entity.
+	__newvnum bigint;
+
+	-- Newly inserted entity.
 	__inserted_oid bigint;
-	_entvalue_jsonb JSONB;
+
+	-- Parsed entity JSON.
+	__entvalue_jsonb jsonb;
+
 BEGIN
-	begin
-		_entvalue_jsonb := _entvalue::jsonb;
-		exception
-			when others then
-        		raise exception 'Invalid JSON string: %', _entvalue;
-	end;
 
-	-- Ensure we get the current non-deleted resource.
-	resoid := (select oid from stsresource r where r.resname = _resname and r.vnum = _resvnum and r.validto is null and r.dbaction != 3);
-	if resoid is null then
- 		-- Exception Codes: https://www.postgresql.org/docs/10/errcodes-appendix.html
-	        RAISE 'resname and version not found or not current version (not deleted) within stsresource %', _resname USING ERRCODE = 'no_data_found';
-	end if;
-	if (select count(*) from stsentity e 
-		where e.resourceoid = resoid and e.entname = _entname and e.validto is null and e.dbaction != 3) > 0 then
-	    -- Exception Codes: https://www.postgresql.org/docs/10/errcodes-appendix.html
-	    -- RAISE EXCEPTION 'resname already exists within stsresource %', now();
-        RAISE 'Duplicate entname within stsresource: %', _resname USING ERRCODE = 'unique_violation';
-	else
-		insert into stsentity(resourceoid, entname, entvalue, entvalue_jsonb, vnum, dbaction, dbactionuser, validfrom)
-		values (resoid, _entname, _entvalue, _entvalue_jsonb, 1, 1, _dbactionuser, now())
-		returning oid into __inserted_oid;
+	-- -------------------------------------------------------------------------
+	-- Validate / parse entity JSON
+	-- -------------------------------------------------------------------------
+
+	BEGIN
+		__entvalue_jsonb := _entvalue::jsonb;
+
+	EXCEPTION
+		WHEN others THEN
+			RAISE EXCEPTION
+				'Invalid JSON string: %',
+				_entvalue;
+	END;
+
+	-- -------------------------------------------------------------------------
+	-- Resolve the requested resource.
+	--
+	-- The supplied resource version must still be the current, non-deleted
+	-- version of the resource.
+	-- -------------------------------------------------------------------------
+
+	BEGIN
+		SELECT
+			r.oid
+		INTO STRICT
+			__resoid
+		FROM public.stsresource r
+		WHERE r.resname = _resname
+		  AND r.vnum = _resvnum
+		  AND r.validto IS NULL
+		  AND r.dbaction != 3;
+
+	EXCEPTION
+
+		WHEN no_data_found THEN
+			RAISE
+				'Resource % version % not found, not current, or deleted',
+				_resname,
+				_resvnum
+				USING ERRCODE = 'no_data_found';
+
+		WHEN too_many_rows THEN
+			RAISE
+				'Too many current stsresource records for resource % version %',
+				_resname,
+				_resvnum
+				USING ERRCODE = 'cardinality_violation';
+
+	END;
+
+	-- -------------------------------------------------------------------------
+	-- Find the current entity.
+	--
+	-- IMPORTANT:
+	--
+	-- Do NOT exclude dbaction = 3 here.
+	--
+	-- A logically deleted entity is still the current entity version while
+	-- validto IS NULL. If it exists, it must be closed before the entity can
+	-- be created again.
+	-- -------------------------------------------------------------------------
+
+	BEGIN
+		SELECT
+			e.oid,
+			e.vnum,
+			e.dbaction
+		INTO STRICT
+			__entoid,
+			__entvnum,
+			__entdbaction
+		FROM public.stsentity e
+		WHERE e.resourceoid = __resoid
+		  AND e.entname = _entname
+		  AND e.validto IS NULL;
+
+	EXCEPTION
+
+		WHEN no_data_found THEN
+			__entoid := NULL;
+			__entvnum := NULL;
+			__entdbaction := NULL;
+
+		WHEN too_many_rows THEN
+			RAISE
+				'Too many current stsentity records for entity % within resource %',
+				_entname,
+				_resname
+				USING ERRCODE = 'cardinality_violation';
+
+	END;
+
+	-- -------------------------------------------------------------------------
+	-- Current entity exists
+	-- -------------------------------------------------------------------------
+
+	IF __entoid IS NOT NULL THEN
+
+		-- ---------------------------------------------------------------------
+		-- Current entity is active.
+		--
+		-- CREATE is not allowed because the entity already exists.
+		-- ---------------------------------------------------------------------
+
+		IF __entdbaction != 3 THEN
+
+			RAISE
+				'Duplicate entname % within stsresource %',
+				_entname,
+				_resname
+				USING ERRCODE = 'unique_violation';
+
+		END IF;
+
+		-- ---------------------------------------------------------------------
+		-- Current entity is logically deleted.
+		--
+		-- Close the deleted version and create the next version.
+		-- ---------------------------------------------------------------------
+
+		UPDATE public.stsentity
+		SET validto = __now
+		WHERE oid = __entoid;
+
+		__newvnum := __entvnum + 1;
+
+	ELSE
+
+		-- ---------------------------------------------------------------------
+		-- No current entity exists.
+		--
+		-- Normally this means the entity has never existed and MAX(vnum)
+		-- will be NULL, resulting in version 1.
+		--
+		-- Using MAX(vnum) also protects against an abnormal historical state
+		-- where previous versions exist but none has validto IS NULL.
+		-- ---------------------------------------------------------------------
+
+		SELECT
+			COALESCE(MAX(e.vnum), 0) + 1
+		INTO
+			__newvnum
+		FROM public.stsentity e
+		WHERE e.resourceoid = __resoid
+		  AND e.entname = _entname;
+
+	END IF;
+
+	-- -------------------------------------------------------------------------
+	-- Create new active entity version
+	-- -------------------------------------------------------------------------
+
+	INSERT INTO public.stsentity(
+		resourceoid,
+		entname,
+		entvalue,
+		entvalue_jsonb,
+		vnum,
+		dbaction,
+		dbactionuser,
+		validfrom
+	)
+	VALUES (
+		__resoid,
+		_entname,
+		_entvalue,
+		__entvalue_jsonb,
+		__newvnum,
+		1,
+		_dbactionuser,
+		__now
+	)
+	RETURNING oid
+	INTO __inserted_oid;
+
+	-- -------------------------------------------------------------------------
+	-- Return newly created entity
+	-- -------------------------------------------------------------------------
+
+	RETURN QUERY
+	SELECT *
+	FROM public.stsentity
+	WHERE oid = __inserted_oid;
 
-		return query
-		select * from stsentity where oid = __inserted_oid;
-    END IF;
 END;
 $BODY$;
 
-ALTER FUNCTION public.create_stsentity(character varying, character varying, integer, character varying, character varying)
-    OWNER TO postgres;
-
 
+ALTER FUNCTION public.create_stsentity(
+	character varying, 
+	character varying, 
+	bigint, 
+	character varying, 
+	character varying
+)
+OWNER TO postgres;
 
 
 CREATE OR REPLACE FUNCTION public.create_stsentity_latest(
 	_dbactionuser character varying,
 	_resname character varying,
 	_entname character varying,
-	_entvalue character varying)
-    RETURNS SETOF stsentity 
-    LANGUAGE 'plpgsql'
+	_entvalue character varying
+)
+RETURNS SETOF stsentity
+LANGUAGE 'plpgsql'
+COST 100
+VOLATILE
+ROWS 1000
 
-    COST 100
-    VOLATILE 
-    ROWS 1000
-    
 AS $BODY$
-declare
-	resoid bigint;
+DECLARE
+	__now timestamp without time zone := now();
+
+	-- Current resource.
+	__resoid bigint;
+
+	-- Current entity, if one exists.
+	__entoid bigint;
+	__entvnum bigint;
+	__entdbaction smallint;
+
+	-- Version for the newly created entity.
+	__newvnum bigint;
+
+	-- Newly inserted entity.
 	__inserted_oid bigint;
-	_entvalue_jsonb JSONB;
+
+	-- Parsed JSON.
+	__entvalue_jsonb jsonb;
+
 BEGIN
-	begin
-		_entvalue_jsonb := _entvalue::jsonb;
-		exception
-			when others then
-        		raise exception 'Invalid JSON string: %', _entvalue;
-	end;
 
-	-- Ensure we get the current non-deleted resource.
-	resoid := (select oid from stsresource r where r.resname = _resname and r.validto is null and r.dbaction != 3);
-	if resoid is null then
- 		-- Exception Codes: https://www.postgresql.org/docs/10/errcodes-appendix.html
-	        RAISE 'resname and version not found or not current version (not deleted) within stsresource %', _resname USING ERRCODE = 'no_data_found';
-	end if;
-	if (select count(*) from stsentity e 
-		where e.resourceoid = resoid and e.entname = _entname and e.validto is null and e.dbaction != 3) > 0 then
-	    -- Exception Codes: https://www.postgresql.org/docs/10/errcodes-appendix.html
-	    -- RAISE EXCEPTION 'resname already exists within stsresource %', now();
-        RAISE 'Duplicate entname within stsresource: %', _resname USING ERRCODE = 'unique_violation';
-	else
-		insert into stsentity(resourceoid, entname, entvalue, entvalue_jsonb, vnum, dbaction, dbactionuser, validfrom)
-		values (resoid, _entname, _entvalue, _entvalue_jsonb, 1, 1, _dbactionuser, now())
-		returning oid into __inserted_oid;
+	-- -------------------------------------------------------------------------
+	-- Validate / parse entity JSON
+	-- -------------------------------------------------------------------------
 
-		return query
-		select * from stsentity where oid = __inserted_oid;
-    END IF;
-END;
-$BODY$;
+	BEGIN
+		__entvalue_jsonb := _entvalue::jsonb;
 
-ALTER FUNCTION public.create_stsentity_latest(character varying, character varying, character varying, character varying)
-    OWNER TO postgres;
+	EXCEPTION
+		WHEN others THEN
+			RAISE EXCEPTION
+				'Invalid JSON string: %',
+				_entvalue;
+	END;
 
+	-- -------------------------------------------------------------------------
+	-- Resolve the current, non-deleted resource.
+	-- -------------------------------------------------------------------------
 
+	BEGIN
+		SELECT
+			r.oid
+		INTO STRICT
+			__resoid
+		FROM public.stsresource r
+		WHERE r.resname = _resname
+		  AND r.validto IS NULL
+		  AND r.dbaction != 3;
+
+	EXCEPTION
+
+		WHEN no_data_found THEN
+			RAISE
+				'Resource % not found, not current, or deleted',
+				_resname
+				USING ERRCODE = 'no_data_found';
+
+		WHEN too_many_rows THEN
+			RAISE
+				'Too many current stsresource records for resource %',
+				_resname
+				USING ERRCODE = 'cardinality_violation';
+
+	END;
+
+	-- -------------------------------------------------------------------------
+	-- Find the current entity.
+	--
+	-- IMPORTANT:
+	--
+	-- Do not exclude dbaction = 3.
+	--
+	-- A logically deleted entity is still the latest/current version while
+	-- validto IS NULL. If found, it must be closed before the entity can be
+	-- created again.
+	-- -------------------------------------------------------------------------
+
+	BEGIN
+		SELECT
+			e.oid,
+			e.vnum,
+			e.dbaction
+		INTO STRICT
+			__entoid,
+			__entvnum,
+			__entdbaction
+		FROM public.stsentity e
+		WHERE e.resourceoid = __resoid
+		  AND e.entname = _entname
+		  AND e.validto IS NULL;
+
+	EXCEPTION
+
+		WHEN no_data_found THEN
+			__entoid := NULL;
+			__entvnum := NULL;
+			__entdbaction := NULL;
+
+		WHEN too_many_rows THEN
+			RAISE
+				'Too many current stsentity records for entity % within resource %',
+				_entname,
+				_resname
+				USING ERRCODE = 'cardinality_violation';
+
+	END;
+
+	-- -------------------------------------------------------------------------
+	-- Current entity exists.
+	-- -------------------------------------------------------------------------
+
+	IF __entoid IS NOT NULL THEN
+
+		-- ---------------------------------------------------------------------
+		-- Current entity is active.
+		--
+		-- CREATE is not allowed.
+		-- ---------------------------------------------------------------------
+
+		IF __entdbaction != 3 THEN
+
+			RAISE
+				'Duplicate entname % within stsresource %',
+				_entname,
+				_resname
+				USING ERRCODE = 'unique_violation';
+
+		END IF;
+
+		-- ---------------------------------------------------------------------
+		-- Current entity is logically deleted.
+		--
+		-- Close the deleted version, then create the next version.
+		-- ---------------------------------------------------------------------
+
+		UPDATE public.stsentity
+		SET validto = __now
+		WHERE oid = __entoid;
+
+		__newvnum := __entvnum + 1;
+
+	ELSE
+
+		-- ---------------------------------------------------------------------
+		-- No current entity exists.
+		--
+		-- Normally this means the entity has never existed, so MAX(vnum)
+		-- will be NULL and the new version becomes 1.
+		--
+		-- Using MAX(vnum) also protects against historical data where versions
+		-- exist but there is unexpectedly no current validto IS NULL row.
+		-- ---------------------------------------------------------------------
+
+		SELECT
+			COALESCE(MAX(e.vnum), 0) + 1
+		INTO
+			__newvnum
+		FROM public.stsentity e
+		WHERE e.resourceoid = __resoid
+		  AND e.entname = _entname;
+
+	END IF;
+
+	-- -------------------------------------------------------------------------
+	-- Create new active entity version.
+	-- -------------------------------------------------------------------------
+
+	INSERT INTO public.stsentity(
+		resourceoid,
+		entname,
+		entvalue,
+		entvalue_jsonb,
+		vnum,
+		dbaction,
+		dbactionuser,
+		validfrom
+	)
+	VALUES (
+		__resoid,
+		_entname,
+		_entvalue,
+		__entvalue_jsonb,
+		__newvnum,
+		1,
+		_dbactionuser,
+		__now
+	)
+	RETURNING oid
+	INTO __inserted_oid;
+
+	-- -------------------------------------------------------------------------
+	-- Return newly created entity.
+	-- -------------------------------------------------------------------------
+
+	RETURN QUERY
+	SELECT *
+	FROM public.stsentity
+	WHERE oid = __inserted_oid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.create_stsentity_latest(
+	character varying,
+	character varying,
+	character varying,
+	character varying
+)
+OWNER TO postgres;
 
--- FUNCTION: public.update_stsentity(character varying, character varying, integer, character varying, integer, character varying)
 
--- DROP FUNCTION public.update_stsentity(character varying, character varying, integer, character varying, integer, character varying);
 
 CREATE OR REPLACE FUNCTION public.update_stsentity(
 	_dbactionuser character varying,
 	_resname character varying,
-	_resvnum integer,
+	_resvnum bigint,
 	_entname character varying,
-	_entvnum integer,
+	_entvnum bigint,
 	_entvalue character varying)
     RETURNS SETOF stsentity 
     LANGUAGE 'plpgsql'
@@ -1025,13 +1379,11 @@ BEGIN
 END;
 $BODY$;
 
-ALTER FUNCTION public.update_stsentity(character varying, character varying, integer, character varying, integer, character varying)
+ALTER FUNCTION public.update_stsentity(character varying, character varying, bigint, character varying, bigint, character varying)
     OWNER TO postgres;
 
 
 
-
-
 CREATE OR REPLACE FUNCTION public.update_stsentity_latest(
 	_dbactionuser character varying,
 	_resname character varying,
@@ -1050,7 +1402,7 @@ declare
 	resoid bigint;
 	entoid bigint;
 	__inserted_oid bigint;
-	_entvnum integer;
+	_entvnum bigint;
 	_entvalue_jsonb JSONB;
 BEGIN
 	begin
@@ -1107,16 +1459,12 @@ ALTER FUNCTION public.update_stsentity_latest(character varying, character varyi
     OWNER TO postgres;
 
 
--- FUNCTION: public.delete_stsentity(character varying, character varying, integer, character varying, integer)
-
--- DROP FUNCTION public.delete_stsentity(character varying, character varying, integer, character varying, integer);
-
 CREATE OR REPLACE FUNCTION public.delete_stsentity(
 	_dbactionuser character varying,
 	_resname character varying,
-	_resvnum integer,
+	_resvnum bigint,
 	_entname character varying,
-	_entvnum integer)
+	_entvnum bigint)
     RETURNS SETOF stsentity 
     LANGUAGE 'plpgsql'
 
@@ -1168,14 +1516,11 @@ BEGIN
 END;
 $BODY$;
 
-ALTER FUNCTION public.delete_stsentity(character varying, character varying, integer, character varying, integer)
+ALTER FUNCTION public.delete_stsentity(character varying, character varying, bigint, character varying, bigint)
     OWNER TO postgres;
 
 
 
-
-
-
 CREATE OR REPLACE FUNCTION public.delete_stsentity_latest(
 	_dbactionuser character varying,
 	_resname character varying,
@@ -1193,7 +1538,7 @@ declare
 	resoid bigint;
 	entoid bigint;
 	__inserted_oid bigint;
-	_entvnum integer;
+	_entvnum bigint;
 BEGIN
 	BEGIN
 		-- Ensure we get the current non-deleted resource.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nsshunt/stsdatamanagement",
-    "version": "1.18.195",
+    "version": "1.18.198",
     "description": "STS Data Management Modules, Utilities and Services",
     "type": "module",
     "main": "./dist/dbaccess.js",