@axinom/mosaic-db-common 0.14.1-rc.6 → 0.15.0

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.15.0](https://dev.azure.com/axinom/CMS/_git/Navy/branchCompare?baseVersion=GT@axinom/mosaic-db-common@0.14.0&targetVersion=GT@axinom/mosaic-db-common@0.15.0) (2022-04-01)
+
+
+### Features
+
+* ax-define functions length checking ([6c4a4ae](https://dev.azure.com/axinom/CMS/_git/Navy/commit/6c4a4ae4b188a710e7d8defdab10304bc334844c)), closes [#34155](https://dev.azure.com/axinom/CMS/_workitems/edit/34155)
+* ax-define timestamp propogation ([b9a69b8](https://dev.azure.com/axinom/CMS/_git/Navy/commit/b9a69b859e449e54aef4dc20a0bad3be69ccf676)), closes [#34380](https://dev.azure.com/axinom/CMS/_workitems/edit/34380)
+
+
+### Bug Fixes
+
+* ax-define user trigger creation fails ([e989bd2](https://dev.azure.com/axinom/CMS/_git/Navy/commit/e989bd2dd9bc951f6d3b8492d7c0f43fd07f4a1d))
+* generate-vscode-sql-snippets can now be launched ([5908776](https://dev.azure.com/axinom/CMS/_git/Navy/commit/59087766f02332de6ca3a78d0d4143ad27a74780)), closes [#34157](https://dev.azure.com/axinom/CMS/_workitems/edit/34157)
+* minor PR comment adjustment ([b5ad8f4](https://dev.azure.com/axinom/CMS/_git/Navy/commit/b5ad8f446c35322e797e804c018255e6d051f8c2)), closes [#34157](https://dev.azure.com/axinom/CMS/_workitems/edit/34157)
+
+
+
 ## [0.14.0](https://dev.azure.com/axinom/CMS/_git/Navy/branchCompare?baseVersion=GT@axinom/mosaic-db-common@0.13.0&targetVersion=GT@axinom/mosaic-db-common@0.14.0) (2022-03-16)
 
 

package/migrations/before-migration/002-error-functions.sql

@@ -28,3 +28,32 @@ BEGIN
   RAISE EXCEPTION '%', format(error_message, VARIADIC placeholder_values) using errcode = error_code;
 END;
 $$;
+
+/*-snippet
+{
+  "body": [
+    "PERFORM ax_utils.validate_identifier_length('${1:identifier}');"
+  ],
+  "description": [
+    "Raises an exception if the provided identifer exceeds the PostgreSQL max length (63 bytes).",
+    "This can be useful to prevent name truncation, identifier collisions and silently dropped constraints.",
+    "If called from a function, the calling function will be referenced in the error message.",
+    "An optional second 'hint' parameter can be provided which will be appended to the error message."
+   ]
+}
+snippet-*/
+CREATE OR REPLACE FUNCTION ax_utils.validate_identifier_length(identifier text, hint text default '') RETURNS void
+    LANGUAGE plpgsql
+    AS $$
+DECLARE
+  stack text; fcesig text; callinfo text;
+BEGIN
+  IF LENGTH(identifier) > 63 THEN
+    -- get sig of calling function
+    GET DIAGNOSTICS stack = PG_CONTEXT;
+    fcesig := substring(substring(stack from 'function (.*)') from 'function (.*?) line');
+    callinfo := CASE WHEN fcesig IS NULL THEN '' ELSE 'Invalid identifier in ' || fcesig::regprocedure::text || '. ' END;
+    perform ax_utils.raise_error('%sIdentifier "%s" exceeds 63 bytes. %s', 'SETUP', callinfo, identifier, hint);
+  END IF;
+END;
+$$;

package/migrations/define/define-functions.sql

@@ -71,9 +71,10 @@ $$;
     "SELECT ax_define.define_timestamps_trigger('${1:table_name}', '${2:app_public}');"
   ],
   "description": [
-    "Defines timestamp trigger which automatically populates 'created_date' and 'updated_date' columns.\n",
-    "N.B! It is recommended to use 'ax_define.define_audit_date_fields_on_table' to define both columns and triggers in one go.",
-    "Use this one if you really need to define triggers separately."
+    "Defines timestamp trigger which automatically populates 'created_date' and 'updated_date' columns.",
+    "It is recommended to use 'ax_define.define_audit_date_fields_on_table' to define both columns and triggers in one go.",
+    "Use this one if you really need to define triggers separately.\n",
+    "N.B! The trigger function is not compatible with JSON columns. Use JSONB instead."
   ]
 }
 snippet-*/
@@ -82,6 +83,7 @@ CREATE OR REPLACE FUNCTION ax_define.define_timestamps_trigger(tableName text, s
     AS $$
 BEGIN
   PERFORM ax_define.drop_timestamps_trigger(tableName, schemaName);
+  -- Full row comparison is not compatible with column type JSON. Expect error: "could not identify an equality operator for type json"
   EXECUTE 'CREATE trigger _100_timestamps BEFORE UPDATE ON ' || schemaName || '.' || tableName ||
           ' for each ROW when (old.* is distinct from new.*) EXECUTE PROCEDURE ax_utils.tg__timestamps();';
 END;
@@ -102,6 +104,7 @@ CREATE OR REPLACE FUNCTION ax_define.drop_users_trigger(tableName text, schemaNa
     AS $$
 BEGIN
   EXECUTE 'DROP trigger IF EXISTS _200_username on ' || schemaName || '.' || tableName || ';';
+  EXECUTE 'DROP trigger IF EXISTS _200_username_before_insert on ' || schemaName || '.' || tableName || ';';
 END;
 $$;
 
@@ -111,9 +114,10 @@ $$;
     "SELECT ax_define.define_users_trigger('${1:table_name}', '${2:app_public}');"
   ],
   "description": [
-    "Defines users trigger which automatically populates 'created_user' and 'updated_user' columns.\n",
-    "N.B! It is recommended to use 'ax_define.define_audit_user_fields_on_table' to define both columns and triggers in one go.",
-    "Use this one if you really need to define triggers separately."
+    "Defines users trigger which automatically populates 'created_user' and 'updated_user' columns.",
+    "It is recommended to use 'ax_define.define_audit_user_fields_on_table' to define both columns and triggers in one go.",
+    "Use this one if you really need to define triggers separately.\n",
+    "N.B! The trigger function is not compatible with JSON columns. Use JSONB instead."
   ]
 }
 snippet-*/
@@ -122,8 +126,12 @@ CREATE OR REPLACE FUNCTION ax_define.define_users_trigger(tableName text, schema
     AS $$
 BEGIN
   PERFORM ax_define.drop_users_trigger(tableName, schemaName);
-  EXECUTE 'CREATE trigger _200_username BEFORE INSERT OR UPDATE ON ' || schemaName || '.' || tableName ||
+  -- Full row comparison is not compatible with column type JSON. Expect error: "could not identify an equality operator for type json"
+  EXECUTE 'CREATE trigger _200_username BEFORE UPDATE ON ' || schemaName || '.' || tableName ||
           ' for each ROW when (old.* is distinct from new.*) EXECUTE PROCEDURE ax_utils.tg__username();';
+  -- INSERT trigger's WHEN condition cannot reference OLD values
+  EXECUTE 'CREATE trigger _200_username_before_insert BEFORE INSERT ON ' || schemaName || '.' || tableName ||
+          ' EXECUTE PROCEDURE ax_utils.tg__username();';
 END;
 $$;
 
@@ -216,15 +224,18 @@ $$
     "SELECT ax_define.drop_index('${1:column_name}', '${2:table_name}');"
   ],
   "description": [
-    "Drops previously defined index. Applies to both regular and unique indexes."
+    "Drops previously defined index. Applies to both regular and unique indexes.\n",
+    "Third (optional) parameter: the unique name for this index. If the value is NULL then the name will be generated from the table & field name."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.drop_index(fieldName text, tableName text) RETURNS void
+CREATE OR REPLACE FUNCTION ax_define.drop_index(fieldName text, tableName text, indexName text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 BEGIN
-  EXECUTE 'DROP INDEX IF EXISTS idx_' || tableName || '_' || fieldName || ' cascade;';
+  SELECT COALESCE(indexName, 'idx_' || tableName || '_' || fieldName) INTO indexName;
+  PERFORM ax_utils.validate_identifier_length(indexName, 'If the auto-generated name is too long then an "indexName" argument must be provided.');
+  EXECUTE 'DROP INDEX IF EXISTS ' || indexName || ' cascade;';
 END;
 $$;
 
@@ -235,16 +246,18 @@ $$;
   ],
   "description": [
     "Defines a regular index on a column.\n",
-    "N.B! Keep in mind, that the maximum index name length is 63 characters and it will be truncated if exceeded."
+    "Fourth (optional) parameter: a unique name for this index. If the value is NULL then a name will be generated from the table & field name."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.define_index(fieldName text, tableName text, schemaName text) RETURNS void
+CREATE OR REPLACE FUNCTION ax_define.define_index(fieldName text, tableName text, schemaName text, indexName text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 BEGIN
-  PERFORM ax_define.drop_index(fieldName, tableName);
-  EXECUTE 'CREATE INDEX idx_' || tableName || '_' || fieldName || ' ON ' || schemaName || '.' || tableName || ' (' || fieldName || ');';
+  SELECT COALESCE(indexName, 'idx_' || tableName || '_' || fieldName) INTO indexName;
+  PERFORM ax_utils.validate_identifier_length(indexName, 'If the auto-generated name is too long then an "indexName" argument must be provided.');
+  PERFORM ax_define.drop_index(fieldName, tableName, indexName);
+  EXECUTE 'CREATE INDEX ' || indexName || ' ON ' || schemaName || '.' || tableName || ' (' || fieldName || ');';
 END;
 $$;
 
@@ -254,17 +267,20 @@ $$;
     "SELECT ax_define.drop_multiple_field_index('{\"${1:column_name_one}\", \"${2:column_name_two}\"}','${3:table_name}');"
   ],
   "description": [
-    "Drops previously defined multi-field index."
+    "Drops previously defined multi-field index.\n",
+    "Third (optional) parameter: the unique name for this index. If the value is NULL then the name will be generated from the table & field names."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.drop_multiple_field_index(fieldNames text[], tableName text) RETURNS void
+CREATE OR REPLACE FUNCTION ax_define.drop_multiple_field_index(fieldNames text[], tableName text, indexName text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 DECLARE
   fieldNamesConcat text = array_to_string(array_agg(fieldNames), '_');
 BEGIN
-  EXECUTE 'DROP INDEX IF EXISTS idx_' || tableName || '_' || fieldNamesConcat || ' cascade;';
+  SELECT COALESCE(indexName, 'idx_' || tableName || '_' || fieldNamesConcat) INTO indexName;
+  PERFORM ax_utils.validate_identifier_length(indexName, 'If the auto-generated name is too long then an "indexName" argument must be provided.');
+  EXECUTE 'DROP INDEX IF EXISTS ' || indexName || ' cascade;';
 END;
 $$;
 
@@ -275,19 +291,21 @@ $$;
   ],
   "description": [
     "Defines a regular index on multiple columns.\n",
-    "N.B! Keep in mind, that the maximum index name length is 63 characters and it will be truncated if exceeded."
+    "Fourth (optional) parameter: a unique name for this index. If the value is NULL then a name will be generated from the table & field names."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.define_multiple_field_index(fieldNames text[], tableName text, schemaName text) RETURNS void
+CREATE OR REPLACE FUNCTION ax_define.define_multiple_field_index(fieldNames text[], tableName text, schemaName text, indexName text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 DECLARE
   fieldNamesConcat text = array_to_string(array_agg(fieldNames), '_');
   fieldList text = array_to_string(array_agg(fieldNames), ', ');
 BEGIN
-  PERFORM ax_define.drop_index(fieldNamesConcat, tableName);
-  EXECUTE 'CREATE INDEX idx_' || tableName || '_' || fieldNamesConcat || ' ON ' || schemaName || '.' || tableName || ' (' || fieldList || ');';
+  SELECT COALESCE(indexName, 'idx_' || tableName || '_' || fieldNamesConcat) INTO indexName;
+  PERFORM ax_utils.validate_identifier_length(indexName, 'If the auto-generated name is too long then an "indexName" argument must be provided.');
+  PERFORM ax_define.drop_multiple_field_index(fieldNames, tableName, indexName);
+  EXECUTE 'CREATE INDEX ' || indexName || ' ON ' || schemaName || '.' || tableName || ' (' || fieldList || ');';
 END;
 $$;
 
@@ -298,16 +316,21 @@ $$;
     "SELECT ax_define.drop_indexes_with_id('${1:column_name}', '${2:table_name}');"
   ],
   "description": [
-    "Drops previously defined ASC/DESC indexes based on id and one other column."
+    "Drops previously defined ASC/DESC indexes based on id and one other column.\n",
+    "Third & fourth (optional) parameters: unique names for the indexes. If either value is NULL then the name will be generated from the table & field name."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.drop_indexes_with_id(fieldName text, tableName text) RETURNS void
+CREATE OR REPLACE FUNCTION ax_define.drop_indexes_with_id(fieldName text, tableName text, indexNameAsc text default NULL, indexNameDesc text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 BEGIN
-  EXECUTE 'DROP INDEX IF EXISTS idx_' || tableName || '_' || fieldName || '_asc_with_id cascade;';
-  EXECUTE 'DROP INDEX IF EXISTS idx_' || tableName || '_' || fieldName || '_desc_with_id cascade;';
+  SELECT COALESCE(indexNameAsc, 'idx_' || tableName || '_' || fieldName || '_asc_with_id') INTO indexNameAsc;
+  SELECT COALESCE(indexNameDesc, 'idx_' || tableName || '_' || fieldName || '_desc_with_id') INTO indexNameDesc;
+  PERFORM ax_utils.validate_identifier_length(indexNameAsc, 'If the auto-generated name is too long then an "indexNameAsc" argument must be provided.');
+  PERFORM ax_utils.validate_identifier_length(indexNameDesc, 'If the auto-generated name is too long then an "indexNameDesc" argument must be provided.');
+  EXECUTE 'DROP INDEX IF EXISTS ' || indexNameAsc || ' cascade;';
+  EXECUTE 'DROP INDEX IF EXISTS ' || indexNameDesc || ' cascade;';
 END;
 $$;
 
@@ -319,15 +342,19 @@ $$;
   "description": [
     "Defines ASC/DESC indexes based on id and one other column.",
     "Use these indexes if there is a plan to perform sorting by this column.\n",
-    "N.B! Keep in mind, that the maximum index name length is 63 characters and it will be truncated if exceeded."
+    "Fourth & fifth (optional) parameters: unique names for the indexes. If either value is NULL then a name will be generated from the table & field name."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.define_indexes_with_id(fieldName text, tableName text, schemaName text) RETURNS void
+CREATE OR REPLACE FUNCTION ax_define.define_indexes_with_id(fieldName text, tableName text, schemaName text, indexNameAsc text default NULL, indexNameDesc text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 BEGIN
-  PERFORM ax_define.drop_indexes_with_id(fieldName, tableName);
+  SELECT COALESCE(indexNameAsc, 'idx_' || tableName || '_' || fieldName || '_asc_with_id') INTO indexNameAsc;
+  SELECT COALESCE(indexNameDesc, 'idx_' || tableName || '_' || fieldName || '_desc_with_id') INTO indexNameDesc;
+  PERFORM ax_utils.validate_identifier_length(indexNameAsc, 'If the auto-generated name is too long then an "indexNameAsc" argument must be provided.');
+  PERFORM ax_utils.validate_identifier_length(indexNameDesc, 'If the auto-generated name is too long then an "indexNameDesc" argument must be provided.');
+  PERFORM ax_define.drop_indexes_with_id(fieldName, tableName, indexNameAsc, indexNameDesc);
   EXECUTE 'CREATE INDEX idx_' || tableName || '_' || fieldName || '_asc_with_id ON ' || schemaName || '.' || tableName || ' (' || fieldName || ' ASC, id ASC);';
   EXECUTE 'CREATE INDEX idx_' || tableName || '_' || fieldName || '_desc_with_id ON ' || schemaName || '.' || tableName || ' (' || fieldName || ' DESC, id ASC);';
 END;
@@ -341,16 +368,18 @@ $$;
   "description": [
     "Defines a UNIQUE index on a column.",
     "You can drop a unique index by using the normal 'ax_define.drop_index' function.\n",
-    "N.B! Keep in mind, that the maximum index name length is 63 characters and it will be truncated if exceeded."
+    "Fourth (optional) parameter: a unique name for the index. If the value is NULL then a name will be generated from the table & field name."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.define_unique_index(fieldName text, tableName text, schemaName text) RETURNS void
+CREATE OR REPLACE FUNCTION ax_define.define_unique_index(fieldName text, tableName text, schemaName text, indexName text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 BEGIN
-  PERFORM ax_define.drop_index(fieldName, tableName);
-  EXECUTE 'CREATE UNIQUE INDEX idx_' || tableName || '_' || fieldName || ' ON ' || schemaName || '.' || tableName || ' (' || fieldName || ');';
+  SELECT COALESCE(indexName, 'idx_' || tableName || '_' || fieldName) INTO indexName;
+  PERFORM ax_utils.validate_identifier_length(indexName, 'If the auto-generated name is too long then an "indexName" argument must be provided.');
+  PERFORM ax_define.drop_index(fieldName, tableName, indexName);
+  EXECUTE 'CREATE UNIQUE INDEX ' || indexName || ' ON ' || schemaName || '.' || tableName || ' (' || fieldName || ');';
 END;
 $$;
 
@@ -360,15 +389,18 @@ $$;
     "SELECT ax_define.drop_unique_constraint('${1:column_name}', '${2:table_name}', '${3:app_public}');"
   ],
   "description": [
-    "Drops a UNIQUE constraint based on a column."
+    "Drops a UNIQUE constraint based on a column.\n",
+    "Fourth (optional) parameter: the unique name for the contraint. If the value is NULL then the name will be generated from the table & field name."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.drop_unique_constraint(fieldName text, tableName text, schemaName text) RETURNS void
+CREATE OR REPLACE FUNCTION ax_define.drop_unique_constraint(fieldName text, tableName text, schemaName text, constraintName text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 BEGIN
-  EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' DROP CONSTRAINT IF EXISTS ' || tableName || '_' || fieldName || '_is_unique;';
+  SELECT COALESCE(constraintName, tableName || '_' || fieldName || '_is_unique') INTO constraintName;
+  PERFORM ax_utils.validate_identifier_length(constraintName, 'If the auto-generated name is too long then a "constraintName" argument must be provided.');
+  EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' DROP CONSTRAINT IF EXISTS ' || constraintName || ';';
 END;
 $$;
 
@@ -378,16 +410,19 @@ $$;
     "SELECT ax_define.define_unique_constraint('${1:column_name}', '${2:table_name}', '${3:app_public}');"
   ],
   "description": [
-    "Defines a UNIQUE constraint on a column."
+    "Defines a UNIQUE constraint on a column.\n",
+    "Fourth (optional) parameter: a unique name for the contraint. If the value is NULL then a name will be generated from the table & field name."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.define_unique_constraint(fieldName text, tableName text, schemaName text) RETURNS void
+CREATE OR REPLACE FUNCTION ax_define.define_unique_constraint(fieldName text, tableName text, schemaName text, constraintName text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 BEGIN
-  PERFORM ax_define.drop_unique_constraint(fieldName, tableName, schemaName);
-  EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' ADD CONSTRAINT ' || tableName || '_' || fieldName || '_is_unique UNIQUE (' || fieldName || ');';
+  SELECT COALESCE(constraintName, tableName || '_' || fieldName || '_is_unique') INTO constraintName;
+  PERFORM ax_utils.validate_identifier_length(constraintName, 'If the auto-generated name is too long then a "constraintName" argument must be provided.');
+  PERFORM ax_define.drop_unique_constraint(fieldName, tableName, schemaName, constraintName);
+  EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' ADD CONSTRAINT ' ||constraintName || ' UNIQUE (' || fieldName || ');';
 END;
 $$;
 
@@ -399,16 +434,19 @@ $$;
   "description": [
     "Defines a deferred UNIQUE constraint on a column.\n",
     "Uniqueness is only checked when the transaction is committed.",
-    "If you want to drop it - use 'ax_define.drop_unique_constraint'."
+    "If you want to drop it - use 'ax_define.drop_unique_constraint'.\n",
+    "Fourth (optional) parameter: a unique name for the contraint. If the value is NULL then a name will be generated from the table & field name."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.define_deferred_unique_constraint(fieldName text, tableName text, schemaName text) RETURNS void
+CREATE OR REPLACE FUNCTION ax_define.define_deferred_unique_constraint(fieldName text, tableName text, schemaName text, constraintName text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 BEGIN
-  PERFORM ax_define.drop_unique_constraint(fieldName, tableName, schemaName);
-  EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' ADD CONSTRAINT ' || tableName || '_' || fieldName || '_is_unique UNIQUE (' || fieldName || ') DEFERRABLE INITIALLY DEFERRED;';
+SELECT COALESCE(constraintName, tableName || '_' || fieldName || '_is_unique') INTO constraintName;
+  PERFORM ax_utils.validate_identifier_length(constraintName, 'If the auto-generated name is too long then a "constraintName" argument must be provided.');
+  PERFORM ax_define.drop_unique_constraint(fieldName, tableName, schemaName, constraintName);
+  EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' ADD CONSTRAINT ' || constraintName || ' UNIQUE (' || fieldName || ') DEFERRABLE INITIALLY DEFERRED;';
 END;
 $$;
 
@@ -418,15 +456,18 @@ $$;
     "SELECT ax_define.drop_like_index('${1:column_name}', '${2:table_name}');"
   ],
   "description": [
-    "Drops a gin_trgm_ops index (for LIKE/ILIKE searches) based on a column."
+    "Drops a gin_trgm_ops index (for LIKE/ILIKE searches) based on a column.\n",
+    "Third (optional) parameter: the unique name for the index. If the value is NULL then the name will be generated from the table & field name."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.drop_like_index(fieldName text, tableName text) RETURNS void
+CREATE OR REPLACE FUNCTION ax_define.drop_like_index(fieldName text, tableName text, indexName text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 BEGIN
-  EXECUTE 'DROP INDEX IF EXISTS idx_trgm_' || tableName || '_' || fieldName || ' cascade;';
+  SELECT COALESCE(indexName, 'idx_trgm_' || tableName || '_' || fieldName) INTO indexName;
+  PERFORM ax_utils.validate_identifier_length(indexName, 'If the auto-generated name is too long then an "indexName" argument must be provided.');
+  EXECUTE 'DROP INDEX IF EXISTS ' || indexName || ' cascade;';
 END;
 $$;
 
@@ -438,16 +479,19 @@ $$;
   "description": [
     "Defines a gin_trgm_ops index (for LIKE/ILIKE searches) on a column.",
     "Read more here: https://niallburkley.com/blog/index-columns-for-like-in-postgres/\n",
-    "N.B! Keep in mind, that the maximum index name length is 63 characters and it will be truncated if exceeded."
+    "Fourth (optional) parameter: a unique name for the index. If the value is NULL then a name will be generated from the table & field name."
   ]
 }
 snippet-*/
-CREATE OR REPLACE FUNCTION ax_define.define_like_index(fieldName text, tableName text, schemaName text) RETURNS void
+
+CREATE OR REPLACE FUNCTION ax_define.define_like_index(fieldName text, tableName text, schemaName text, indexName text default NULL) RETURNS void
     LANGUAGE plpgsql
     AS $$
 BEGIN
-  PERFORM ax_define.drop_like_index(fieldName, tableName);
-  EXECUTE 'CREATE INDEX idx_trgm_' || tableName || '_' || fieldName || ' ON ' || schemaName || '.' || tableName || ' USING gin (' || fieldName || ' gin_trgm_ops);';
+  SELECT COALESCE(indexName, 'idx_trgm_' || tableName || '_' || fieldName) INTO indexName;
+  PERFORM ax_utils.validate_identifier_length(indexName, 'If the auto-generated name is too long then an "indexName" argument must be provided.');
+  PERFORM ax_define.drop_like_index(fieldName, tableName, indexName);
+  EXECUTE 'CREATE INDEX ' || indexName || ' ON ' || schemaName || '.' || tableName || ' USING gin (' || fieldName || ' gin_trgm_ops);';
 END;
 $$;
 
@@ -576,7 +620,8 @@ $$;
     "Also defines triggers that populate these columns on row create/update.\n",
     "The third parameter is a placeholder for the default username value.",
     "Please make sure that this placeholder is defined in the 'graphile-migrate' settings object,",
-    "in the placeholders property with the same name e.g. ':DEFAULT_USERNAME'."
+    "in the placeholders property with the same name e.g. ':DEFAULT_USERNAME'.\n",
+    "N.B! The trigger functions are not compatible with JSON columns. Use JSONB instead."
   ]
 }
 snippet-*/
@@ -863,7 +908,8 @@ $$;
     "If the column does not exist - it is created with type text.\n",
     "The sixth parameter is optional. Do not define if the column already exists or if the new column should not have a default value.",
     "The seventh parameter is optional and decides if the column should be required or optional.",
-    "The default value is 'NOT NULL'. Use 'NULL' if the new column should be optional."
+    "The default value is 'NOT NULL'. Use 'NULL' if the new column should be optional.",
+    "The eighth parameter is optional: a unique name for the generated constraint. If the value is NULL then a name will be generated from the table & column name."
   ]
 }
 snippet-*/
@@ -874,12 +920,14 @@ CREATE OR REPLACE FUNCTION ax_define.bind_enum_schema_table_to_table(
   enumName text, -- 'example_status'
   enumSchemaName text, -- 'app_public'
   defaultEnumValue text default '', -- 'DASH'
-  notNullOptions text default 'NOT NULL' -- 'NOT NULL'
+  notNullOptions text default 'NOT NULL', -- 'NOT NULL'
+  constraintName text default NULL
   ) RETURNS void LANGUAGE plpgsql AS $$
 DECLARE
-  fk_constraint_name TEXT = tableName || '_' || columnName || '_fkey';
   default_setting TEXT = '';
 BEGIN
+  SELECT COALESCE(constraintName, tableName || '_' || columnName || '_fkey') INTO constraintName;
+  PERFORM ax_utils.validate_identifier_length(constraintName, 'If the auto-generated name is too long then a "constraintName" argument must be provided.');
   IF NOT coalesce(defaultEnumValue, '') = '' THEN
     default_setting = 'DEFAULT ''' || defaultEnumValue || '''::text';
   END IF;
@@ -888,7 +936,7 @@ BEGIN
   END IF; 
 
   -- Set the column that uses enum value as a foreign key
-  EXECUTE 'ALTER TABLE  ' || schemaName || '.' || tableName || ' ADD CONSTRAINT ' || fk_constraint_name || ' FOREIGN KEY ('|| columnName ||') REFERENCES ' || enumSchemaName || '.' || enumName || '(value);'; 
+  EXECUTE 'ALTER TABLE  ' || schemaName || '.' || tableName || ' ADD CONSTRAINT ' || constraintName || ' FOREIGN KEY ('|| columnName ||') REFERENCES ' || enumSchemaName || '.' || enumName || '(value);'; 
 END;
 $$;
 
@@ -1012,3 +1060,117 @@ BEGIN
 
 END;
 $function$;
+
+/*-snippet
+{
+  "body": [
+    "SELECT ax_define.drop_timestamp_propagation('${1:fk_column}', '${2:table_name}', '${3:app_public}', '${4:id}', '${5:parent_table}', '${6:app_public}');"
+  ],
+  "description": [
+    "Removes a function and trigger created by 'ax_define.define_timestamp_propagation' in an idempotent way.\n",
+    "The call signature mirrors 'ax_define.define_timestamp_propagation' and should be applied with the same arguments.\n",
+    "Seventh (optional) parameter: the unique name for the generated function. If the value is NULL then the name will be generated from the table names."
+  ]
+}
+snippet-*/
+CREATE OR REPLACE FUNCTION ax_define.drop_timestamp_propagation(
+  idColumnName text,
+  tableName text,
+  schemaName text,
+  foreignIdColumnName text,
+  foreignTableName text,
+  foreignSchemaName text,
+  functionName text default NULL
+  ) RETURNS void
+    LANGUAGE plpgsql
+    AS $$
+BEGIN
+  SELECT COALESCE(functionName, 'tg_' || tableName || '__' || foreignTableName || '_ts_propagation') INTO functionName;
+  PERFORM ax_utils.validate_identifier_length(functionName, 'If the auto-generated name is too long then a "functionName" argument must be provided.');
+  EXECUTE  'DROP TRIGGER IF EXISTS _200_propogate_timestamps on ' || schemaName || '.' || tableName;
+  EXECUTE  'DROP FUNCTION IF EXISTS ' || schemaName || '.' || functionName || '()';
+END;
+$$;
+
+/*-snippet
+{
+  "body": [
+    "SELECT ax_define.define_timestamp_propagation('${1:fk_column}', '${2:table_name}', '${3:app_public}', '${4:id}', '${5:parent_table}', '${6:app_public}');"
+  ],
+  "description": [
+    "Defines a function and trigger to propagate 'updated_date' changes to related entities.\n",
+    "Propagation can trigger 'UPDATED' triggers on the target entity including chained timestamp propagation.\n",
+    "First parameter: a column name from the \"table_name\" table that the trigger should be associated with.",
+    "Fourth parameter: a column name from the \"parent_table\" that 'updated_date' should be propagated to.",
+    "Seventh (optional) parameter: a unique name for the generated function. If the value is NULL then a name will be generated from the table names.\n",
+    "NB!. This function uses SECURITY DEFINER permission. It will always be executed as DB_OWNER."
+  ]
+}
+snippet-*/
+CREATE OR REPLACE FUNCTION ax_define.define_timestamp_propagation(
+  idColumnName text,
+  tableName text,
+  schemaName text,
+  foreignIdColumnName text,
+  foreignTableName text,
+  foreignSchemaName text,
+  functionName text default NULL
+  ) RETURNS void
+    LANGUAGE plpgsql
+    AS $a$
+BEGIN
+  SELECT COALESCE(functionName, 'tg_' || tableName || '__' || foreignTableName || '_ts_propagation') INTO functionName;
+  PERFORM ax_utils.validate_identifier_length(functionName, 'If the auto-generated name is too long then a "functionName" argument must be provided.');
+  -- Set updated_date=now() on the foreign table. This will propogate UPDATE triggers.
+  --
+  -- A new function is created for each table to do this.
+  --     It *may* be possible to use a stock function with trigger arguments but its not easy as NEW and OLD cannot be accessed with dynamic column names. A possible 
+  --     solution to that is described here: https://itectec.com/database/postgresql-assignment-of-a-column-with-dynamic-column-name/. But even there the advise is 
+  --     to: "Just write a new trigger function for each table. Less hassle, better performance. Byte the bullet on code duplication:"
+  --
+  -- WARNING: This function uses "SECURITY DEFINER". This is required to ensure that update to the target table is allowed. This means that the function is 
+  --          executed with role "DB_OWNER". Any propogated trigger functions will also execute with role "DB_OWNER".
+  EXECUTE  '
+            CREATE OR REPLACE FUNCTION ' || schemaName || '.' || functionName || '() RETURNS TRIGGER
+            LANGUAGE plpgsql 
+            SECURITY DEFINER
+            SET search_path = pg_temp
+            AS $b$
+            BEGIN
+                -- if updated_date exists on source and its not changed, then exit here
+                -- this prevents multiple propogation from different children in one transaction
+                if (to_jsonb(NEW) ? ''updated_date'') THEN
+                    -- must be a seperate condition to prevent exception if column does not exist
+                    IF (OLD.updated_date = NEW.updated_date) THEN
+                        RETURN NULL;
+                    END IF;
+                END IF;
+                
+                -- UPDATE (where relationship is unchanged, or changed to another entity in which case a change is triggered on both the old and new relation)
+                IF (OLD.' || idColumnName || ' IS NOT NULL AND NEW.' || idColumnName || ' IS NOT NULL) THEN
+                    UPDATE ' || foreignSchemaName || '.' || foreignTableName || ' SET updated_date=now()
+                    WHERE (' || foreignIdColumnName || ' = OLD.' || idColumnName || ') OR (' || foreignIdColumnName || ' = NEW.' || idColumnName || ');
+                
+                -- INSERT (or UPDATE which sets nullable relationship)
+                ELSIF (NEW.' || idColumnName || ' IS NOT NULL) THEN
+                    UPDATE ' || foreignSchemaName || '.' || foreignTableName || ' SET updated_date=now()
+                    WHERE ' || foreignIdColumnName || ' = NEW.' || idColumnName || ';
+                
+                -- DELETE (or UPDATE which removes nullable relationship)
+                ELSIF (OLD.' || idColumnName || ' IS NOT NULL) THEN
+                    UPDATE ' || foreignSchemaName || '.' || foreignTableName || ' SET updated_date=now()
+                    WHERE ' || foreignIdColumnName || ' = OLD.' || idColumnName || ';
+                    
+                END IF;
+                RETURN NULL;
+            END $b$;
+            REVOKE EXECUTE ON FUNCTION ' || schemaName || '.' || functionName || '() FROM public;
+            ';
+  
+  -- Function runs *AFTER* INSERT, UPDATE, DELETE. Propogated queries can still raise an error and rollback the transaction
+  EXECUTE  'DROP TRIGGER IF EXISTS _200_propogate_timestamps on ' || schemaName || '.' || tableName;
+  EXECUTE  'CREATE trigger _200_propogate_timestamps 
+            AFTER INSERT OR UPDATE OR DELETE ON ' || schemaName || '.' || tableName || '
+            FOR EACH ROW EXECUTE PROCEDURE ' || schemaName || '.' || functionName || '();';
+END;
+$a$;

package/migrations/define/define-multitenancy-functions.sql

@@ -21,9 +21,7 @@ CREATE OR REPLACE FUNCTION ax_define.define_multitenancy_on_table(
     AS $$
 BEGIN
   SELECT COALESCE(constraintName, tableName || '_unique_id_tenant_environment') INTO constraintName;
-  IF LENGTH(constraintName) > 63 THEN
-    perform ax_utils.raise_error('Invalid parameters provided to "ax_define.define_multitenancy_on_table". Constraint name "%s" exceeds 63 bytes. If the auto-generated name exceeds 63 bytes then a "constraintName" argument must be provided.', 'SETUP', constraintName);
-  END IF;
+  PERFORM ax_utils.validate_identifier_length(constraintName, 'If the auto-generated name is too long then a "constraintName" argument must be provided.');
   EXECUTE '
     DO $do$ BEGIN 
       BEGIN
@@ -85,9 +83,7 @@ CREATE OR REPLACE FUNCTION ax_define.define_multitenancy_relation(
     AS $$
 BEGIN
   SELECT COALESCE(constraintName, 'multitenancy_relation_' || tableName || '_to_' || foreignTableName) INTO constraintName;
-  IF LENGTH(constraintName) > 63 THEN
-    perform ax_utils.raise_error('Invalid parameters provided to "ax_define.define_multitenancy_relation". Constraint name "%s" exceeds 63 bytes. If the auto-generated name exceeds 63 bytes then a "constraintName" argument must be provided.', 'SETUP', constraintName);
-  END IF;
+  PERFORM ax_utils.validate_identifier_length(constraintName, 'If the auto-generated name is too long then a "constraintName" argument must be provided.');
   EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' DROP CONSTRAINT IF EXISTS ' || constraintName || ';';
   EXECUTE '
     ALTER TABLE ' || schemaName || '.' || tableName || ' ADD CONSTRAINT ' || constraintName || '
@@ -112,9 +108,7 @@ CREATE OR REPLACE FUNCTION ax_define.define_multitenancy_unique_field_constraint
     AS $$
 BEGIN
   SELECT COALESCE(constraintName, tableName || '_' || fieldName || '_is_unique') INTO constraintName;
-  IF LENGTH(constraintName) > 63 THEN
-    perform ax_utils.raise_error('Invalid parameters provided to "ax_define.define_multitenancy_unique_constraint". Constraint name "%s" exceeds 63 bytes. If the auto-generated name exceeds 63 bytes then a "constraintName" argument must be provided.', 'SETUP', constraintName);
-  END IF;
+  PERFORM ax_utils.validate_identifier_length(constraintName, 'If the auto-generated name is too long then a "constraintName" argument must be provided.');
   EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' DROP CONSTRAINT IF EXISTS ' || constraintName || ';';
   EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' ADD CONSTRAINT ' || constraintName || ' UNIQUE (' || fieldName || ', tenant_id, environment_id);';
 END;
@@ -139,9 +133,7 @@ DECLARE
   fieldList text = array_to_string(array_agg(fieldNames), ', ');
 BEGIN
   SELECT COALESCE(constraintName, tableName || '_' || fieldNamesConcat || '_is_unique') INTO constraintName;
-  IF LENGTH(constraintName) > 63 THEN
-    perform ax_utils.raise_error('Invalid parameters provided to "ax_define.define_multitenancy_multi_unique_constraint". Constraint name "%s" exceeds 63 bytes. If the auto-generated name exceeds 63 bytes then a "constraintName" argument must be provided.', 'SETUP', constraintName);
-  END IF;
+  PERFORM ax_utils.validate_identifier_length(constraintName, 'If the auto-generated name is too long then a "constraintName" argument must be provided.');
   EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' DROP CONSTRAINT IF EXISTS ' || constraintName || ';';
   EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' ADD CONSTRAINT ' || constraintName || ' UNIQUE (' || fieldList || ', tenant_id, environment_id);';
 END;
@@ -163,9 +155,7 @@ CREATE OR REPLACE FUNCTION ax_define.define_multitenancy_unique_constraint(table
     AS $$
 BEGIN
   SELECT COALESCE(constraintName, tableName || '_multitenancy_entry_is_unique') INTO constraintName;
-  IF LENGTH(constraintName) > 63 THEN
-    perform ax_utils.raise_error('Invalid parameters provided to "ax_define.define_multitenancy_unique_constraint". Constraint name "%s" exceeds 63 bytes. If the auto-generated name exceeds 63 bytes then a "constraintName" argument must be provided.', 'SETUP', constraintName);
-  END IF;
+  PERFORM ax_utils.validate_identifier_length(constraintName, 'If the auto-generated name is too long then a "constraintName" argument must be provided.');
   EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' DROP CONSTRAINT IF EXISTS ' || constraintName || ';';
   EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' ADD CONSTRAINT ' || constraintName || ' UNIQUE (tenant_id, environment_id);';
 END;
@@ -188,9 +178,7 @@ CREATE OR REPLACE FUNCTION ax_define.define_multitenancy_primary_key(fieldNames
     AS $$
 BEGIN
   SELECT COALESCE(constraintName, tableName || '_pkey') INTO constraintName;
-  IF LENGTH(constraintName) > 63 THEN
-    perform ax_utils.raise_error('Invalid parameters provided to "ax_define.define_multitenancy_primary_key". Constraint name "%s" exceeds 63 bytes. If the auto-generated name exceeds 63 bytes then a "constraintName" argument must be provided.', 'SETUP', constraintName);
-  END IF;
+  PERFORM ax_utils.validate_identifier_length(constraintName, 'If the auto-generated name is too long then a "constraintName" argument must be provided.');
   EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' DROP CONSTRAINT IF EXISTS ' || constraintName || ';';
   EXECUTE 'ALTER TABLE ' || schemaName || '.' || tableName || ' ADD CONSTRAINT ' || constraintName || ' PRIMARY KEY (' || fieldNames || ',tenant_id, environment_id);';
 END;
@@ -212,9 +200,7 @@ CREATE OR REPLACE FUNCTION ax_define.define_multitenancy_index(fieldName text, t
     AS $$
 BEGIN
   SELECT COALESCE(indexName, 'idx_' || tableName || '_' || fieldName || '_mt') INTO indexName;
-  IF LENGTH(indexName) > 63 THEN
-    perform ax_utils.raise_error('Invalid parameters provided to "ax_define.define_multitenancy_index". Index name "%s" exceeds 63 bytes. If the auto-generated name exceeds 63 bytes then an "indexName" argument must be provided.', 'SETUP', indexName);
-  END IF;
+  PERFORM ax_utils.validate_identifier_length(indexName, 'If the auto-generated name is too long then an "indexName" argument must be provided.');
   EXECUTE 'DROP INDEX IF EXISTS ' || indexName || ' cascade;';
   EXECUTE 'CREATE INDEX ' || indexName || ' ON ' || schemaName || '.' || tableName || ' (' || fieldName || ', tenant_id, environment_id);';
 END;
@@ -285,9 +271,7 @@ CREATE OR REPLACE FUNCTION ax_define.drop_multitenancy_timestamp_propagation(
     AS $$
 BEGIN
   SELECT COALESCE(functionName, 'tg_' || tableName || '__' || foreignTableName || '_mt_ts_propagation') INTO functionName;
-  IF LENGTH(functionName) > 63 THEN
-    perform ax_utils.raise_error('Invalid parameters provided to "ax_define.drop_multitenancy_timestamp_propagation". Function name "%s" exceeds 63 bytes. If the auto-generated name exceeds 63 bytes then a "functionName" argument must be provided.', 'SETUP', functionName);
-  END IF;
+  PERFORM ax_utils.validate_identifier_length(functionName, 'If the auto-generated name is too long then a "functionName" argument must be provided.');
   EXECUTE  'DROP TRIGGER IF EXISTS _200_propogate_timestamps on ' || schemaName || '.' || tableName;
   EXECUTE  'DROP FUNCTION IF EXISTS ' || schemaName || '.' || functionName || '()';
 END;
@@ -304,7 +288,8 @@ $$;
     "The call signature mirrors ax_define.define_multitenancy_relation and can generally be applied with the same arguments.\n",
     "First parameter: a column name from the \"table_name\" table that the trigger should be associated with.",
     "Fourth parameter: a column name from the \"parent_table\" that 'updated_date' should be propagated to.",
-    "Seventh (optional) parameter: a unique name for the generated function. If the value is NULL then a name will be generated from the table names."
+    "Seventh (optional) parameter: a unique name for the generated function. If the value is NULL then a name will be generated from the table names.\n",
+    "NB!. This function uses SECURITY DEFINER permission. It will always be executed as DB_OWNER."
   ]
 }
 snippet-*/
@@ -321,9 +306,7 @@ CREATE OR REPLACE FUNCTION ax_define.define_multitenancy_timestamp_propagation(
     AS $a$
 BEGIN
   SELECT COALESCE(functionName, 'tg_' || tableName || '__' || foreignTableName || '_mt_ts_propagation') INTO functionName;
-  IF LENGTH(functionName) > 63 THEN
-    perform ax_utils.raise_error('Invalid parameters provided to "ax_define.define_multitenancy_timestamp_propagation". Function name "%s" exceeds 63 bytes. If the auto-generated name exceeds 63 bytes then a "functionName" argument must be provided.', 'SETUP', functionName);
-  END IF;
+  PERFORM ax_utils.validate_identifier_length(functionName, 'If the auto-generated name is too long then a "functionName" argument must be provided.');
   -- Set updated_date=now() on the foreign table. This will propogate UPDATE triggers.
   --
   -- A new function is created for each table to do this.
@@ -341,18 +324,26 @@ BEGIN
             SET search_path = pg_temp
             AS $b$
             BEGIN
-                if (OLD.updated_date = NEW.updated_date) THEN
-                   RETURN NULL;
+                -- if updated_date exists on source and its not changed, then exit here
+                -- this prevents multiple propogation from different children in one transaction
+                if (to_jsonb(NEW) ? ''updated_date'') THEN
+                    -- must be a seperate condition to prevent exception if column does not exist
+                    IF (OLD.updated_date = NEW.updated_date) THEN
+                        RETURN NULL;
+                    END IF;
                 END IF;
+
                 -- UPDATE (where relationship is unchanged, or changed to another entity in which case a change is triggered on both the old and new relation)
                 IF (OLD.' || idColumnName || ' IS NOT NULL AND NEW.' || idColumnName || ' IS NOT NULL) THEN
                     UPDATE ' || foreignSchemaName || '.' || foreignTableName || ' SET updated_date=now()
                         WHERE (' || foreignIdColumnName || ' = OLD.' || idColumnName || ' AND tenant_id = OLD.tenant_id AND environment_id = OLD.environment_id)
                         OR (' || foreignIdColumnName || ' = NEW.' || idColumnName || ' AND tenant_id = NEW.tenant_id AND environment_id = NEW.environment_id);
+
                 -- INSERT (or UPDATE which sets nullable relationship)
                 ELSIF (NEW.' || idColumnName || ' IS NOT NULL) THEN
                     UPDATE ' || foreignSchemaName || '.' || foreignTableName || ' SET updated_date=now()
                         WHERE ' || foreignIdColumnName || ' = NEW.' || idColumnName || ' AND tenant_id = NEW.tenant_id AND environment_id = NEW.environment_id;
+
                 -- DELETE (or UPDATE which removes nullable relationship)
                 ELSIF (OLD.' || idColumnName || ' IS NOT NULL) THEN
                     UPDATE ' || foreignSchemaName || '.' || foreignTableName || ' SET updated_date=now()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axinom/mosaic-db-common",
-  "version": "0.14.1-rc.6",
+  "version": "0.15.0",
   "description": "This library encapsulates database-related functionality to develop Mosaic based services.",
   "author": "Axinom",
   "license": "PROPRIETARY",
@@ -48,5 +48,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9fa0c83deed32d7f1581fb976f88c5c73ce37877"
+  "gitHead": "2d8cec2958a2cc6f80ee764d21e66b4fe1729bb5"
 }