src/main/resources/db/changelog/2-rbactest/201-rbactest-customer/2013-rbactest-customer-rbac.sql

@@ -183,11 +183,26 @@ call rbac.generateRbacRestrictedView('rbactest.customer',
 --changeset RbacRbacSystemRebuildGenerator:rbactest-customer-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table rbactest.customer after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table rbactest.customer', null, <<insert executing global admin user here>>);
 --  call rbactest.customer_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `rbactest.customer.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`rbactest.customer.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure rbactest.customer_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/2-rbactest/202-rbactest-package/2023-rbactest-package-rbac.sql

@@ -248,11 +248,26 @@ call rbac.generateRbacRestrictedView('rbactest.package',
 --changeset RbacRbacSystemRebuildGenerator:rbactest-package-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table rbactest.package after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table rbactest.package', null, <<insert executing global admin user here>>);
 --  call rbactest.package_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `rbactest.package.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`rbactest.package.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure rbactest.package_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/2-rbactest/203-rbactest-domain/2033-rbactest-domain-rbac.sql

@@ -247,11 +247,26 @@ call rbac.generateRbacRestrictedView('rbactest.domain',
 --changeset RbacRbacSystemRebuildGenerator:rbactest-domain-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table rbactest.domain after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table rbactest.domain', null, <<insert executing global admin user here>>);
 --  call rbactest.domain_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `rbactest.domain.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`rbactest.domain.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure rbactest.domain_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/5-hs-office/501-contact/5013-hs-office-contact-rbac.sql

@@ -107,11 +107,26 @@ call rbac.generateRbacRestrictedView('hs_office.contact',
 --changeset RbacRbacSystemRebuildGenerator:hs-office-contact-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_office.contact after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_office.contact', null, <<insert executing global admin user here>>);
 --  call hs_office.contact_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_office.contact.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_office.contact.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_office.contact_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/5-hs-office/502-person/5023-hs-office-person-rbac.sql

@@ -109,11 +109,26 @@ call rbac.generateRbacRestrictedView('hs_office.person',
 --changeset RbacRbacSystemRebuildGenerator:hs-office-person-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_office.person after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_office.person', null, <<insert executing global admin user here>>);
 --  call hs_office.person_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_office.person.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_office.person.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_office.person_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/5-hs-office/503-relation/5033-hs-office-relation-rbac.sql

@@ -257,11 +257,26 @@ call rbac.generateRbacRestrictedView('hs_office.relation',
 --changeset RbacRbacSystemRebuildGenerator:hs-office-relation-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_office.relation after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_office.relation', null, <<insert executing global admin user here>>);
 --  call hs_office.relation_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_office.relation.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_office.relation.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_office.relation_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/5-hs-office/504-partner/5043-hs-office-partner-rbac.sql

@@ -258,11 +258,26 @@ call rbac.generateRbacRestrictedView('hs_office.partner',
 --changeset RbacRbacSystemRebuildGenerator:hs-office-partner-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_office.partner after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_office.partner', null, <<insert executing global admin user here>>);
 --  call hs_office.partner_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_office.partner.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_office.partner.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_office.partner_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/5-hs-office/504-partner/5044-hs-office-partner-details-rbac.sql

@@ -170,11 +170,26 @@ call rbac.generateRbacRestrictedView('hs_office.partner_details',
 --changeset RbacRbacSystemRebuildGenerator:hs-office-partner-details-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_office.partner_details after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_office.partner_details', null, <<insert executing global admin user here>>);
 --  call hs_office.partner_details_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_office.partner_details.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_office.partner_details.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_office.partner_details_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/5-hs-office/505-bankaccount/5053-hs-office-bankaccount-rbac.sql

@@ -106,11 +106,26 @@ call rbac.generateRbacRestrictedView('hs_office.bankaccount',
 --changeset RbacRbacSystemRebuildGenerator:hs-office-bankaccount-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_office.bankaccount after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_office.bankaccount', null, <<insert executing global admin user here>>);
 --  call hs_office.bankaccount_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_office.bankaccount.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_office.bankaccount.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_office.bankaccount_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/5-hs-office/506-debitor/5063-hs-office-debitor-rbac.sql

@@ -247,11 +247,26 @@ call rbac.generateRbacRestrictedView('hs_office.debitor',
 --changeset RbacRbacSystemRebuildGenerator:hs-office-debitor-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_office.debitor after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_office.debitor', null, <<insert executing global admin user here>>);
 --  call hs_office.debitor_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_office.debitor.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_office.debitor.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_office.debitor_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/5-hs-office/507-sepamandate/5073-hs-office-sepamandate-rbac.sql

@@ -216,11 +216,26 @@ call rbac.generateRbacRestrictedView('hs_office.sepamandate',
 --changeset RbacRbacSystemRebuildGenerator:hs-office-sepamandate-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_office.sepamandate after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_office.sepamandate', null, <<insert executing global admin user here>>);
 --  call hs_office.sepamandate_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_office.sepamandate.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_office.sepamandate.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_office.sepamandate_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/5-hs-office/510-membership/5103-hs-office-membership-rbac.sql

@@ -198,11 +198,26 @@ call rbac.generateRbacRestrictedView('hs_office.membership',
 --changeset RbacRbacSystemRebuildGenerator:hs-office-membership-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_office.membership after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_office.membership', null, <<insert executing global admin user here>>);
 --  call hs_office.membership_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_office.membership.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_office.membership.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_office.membership_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/5-hs-office/511-coopshares/5113-hs-office-coopshares-rbac.sql

@@ -169,11 +169,26 @@ call rbac.generateRbacRestrictedView('hs_office.coopsharetx',
 --changeset RbacRbacSystemRebuildGenerator:hs-office-coopsharetx-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_office.coopsharetx after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_office.coopsharetx', null, <<insert executing global admin user here>>);
 --  call hs_office.coopsharetx_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_office.coopsharetx.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_office.coopsharetx.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_office.coopsharetx_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/5-hs-office/512-coopassets/5123-hs-office-coopassets-rbac.sql

@@ -169,11 +169,26 @@ call rbac.generateRbacRestrictedView('hs_office.coopassettx',
 --changeset RbacRbacSystemRebuildGenerator:hs-office-coopassettx-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_office.coopassettx after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_office.coopassettx', null, <<insert executing global admin user here>>);
 --  call hs_office.coopassettx_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_office.coopassettx.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_office.coopassettx.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_office.coopassettx_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/6-hs-booking/620-booking-project/6203-hs-booking-project-rbac.sql

@@ -209,11 +209,26 @@ call rbac.generateRbacRestrictedView('hs_booking.project',
 --changeset RbacRbacSystemRebuildGenerator:hs-booking-project-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_booking.project after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_booking.project', null, <<insert executing global admin user here>>);
 --  call hs_booking.project_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_booking.project.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_booking.project.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_booking.project_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/6-hs-booking/630-booking-item/6303-hs-booking-item-rbac.sql

@@ -280,11 +280,26 @@ call rbac.generateRbacRestrictedView('hs_booking.item',
 --changeset RbacRbacSystemRebuildGenerator:hs-booking-item-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_booking.item after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_booking.item', null, <<insert executing global admin user here>>);
 --  call hs_booking.item_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_booking.item.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_booking.item.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_booking.item_rebuild_rbac_system()
     language plpgsql as $$

src/main/resources/db/changelog/7-hs-hosting/701-hosting-asset/7013-hs-hosting-asset-rbac.sql

@@ -186,11 +186,26 @@ call rbac.generateRbacRestrictedView('hs_hosting.asset',
 --changeset RbacRbacSystemRebuildGenerator:hs-hosting-asset-rbac-rebuild endDelimiter:--//
 -- ----------------------------------------------------------------------------
 
+-- HOWTO: Rebuild RBAC-system for table hs_hosting.asset after changing its RBAC specification.
 --
 -- begin transaction;
 --  call base.defineContext('re-creating RBAC for table hs_hosting.asset', null, <<insert executing global admin user here>>);
 --  call hs_hosting.asset_rebuild_rbac_system();
 -- commit;
+--
+-- How it works:
+-- 1. All grants previously created from the RBAC specification of this table will be deleted.
+--    These grants are identified by `hs_hosting.asset.grantedByTriggerOf IS NOT NULL`.
+--    User-induced grants (`hs_hosting.asset.grantedByTriggerOf IS NULL`) are NOT deleted.
+-- 2. New role types will be created, but existing role types which are not specified anymore,
+--    will NOT be deleted!
+-- 3. All newly specified grants will be created.
+--
+-- IMPORTANT:
+-- Make sure not to skip any previously defined role-types or you might break indirect grants!
+-- E.g. If, in an updated version of the RBAC system for a table, you remove the AGENT role type
+-- and now directly grant the TENANT role to the ADMIN role, all external grants to the AGENT role
+-- of this table would be in a dead end.
 
 create or replace procedure hs_hosting.asset_rebuild_rbac_system()
     language plpgsql as $$