Merge branch 'feature/unique-keys-with-predicate'

Author: jhf

README.md

@@ -24,7 +24,7 @@ In the context of this extension, a **Saga** represents the complete history of
 ## Temporal Tables with Foreign Keys example
 
 A simplified example to illustrate the concept.
-A temporal table has `valid_from` and `valid_until` columns, which define a `[)` period (inclusive start, exclusive end), aligning with PostgreSQL's native range types.
+A temporal table has `valid_from` and `valid_until` columns, which define a `[)` period (inclusive start, exclusive end), aligning with PostgreSQL's native range types. While `DATE` is used in these examples for simplicity, any data type that can form a range is supported, including `TIMESTAMPTZ`, `TIMESTAMP`, `INTEGER`, `BIGINT`, and `NUMERIC`.
 
 ### Entity Identifiers
 
@@ -178,8 +178,9 @@ CREATE TABLE legal_unit (
   id SERIAL NOT NULL,
   legal_ident VARCHAR NOT NULL,
   name VARCHAR NOT NULL,
-  valid_from TIMESTAMPTZ,
-  valid_until TIMESTAMPTZ,
+  status TEXT, -- e.g., 'active', 'inactive'
+  valid_from DATE,
+  valid_until DATE,
   valid_to DATE -- Optional: for human-readable inclusive end dates
   -- Note: A primary key on temporal tables is often not on the temporal columns
 );
@@ -193,17 +194,23 @@ CREATE TRIGGER legal_unit_synchronize_validity
 SELECT sql_saga.add_era(table_oid => 'legal_unit', valid_from_column_name => 'valid_from', valid_until_column_name => 'valid_until');
 -- Add temporal unique keys. A name is generated if the last argument is omitted.
 SELECT sql_saga.add_unique_key(table_oid => 'legal_unit', column_names => ARRAY['id'], unique_key_name => 'legal_unit_id_valid');
-SELECT sql_saga.add_unique_key(table_oid => 'legal_unit', column_names => ARRAY['name'], unique_key_name => 'legal_unit_name_valid');
 SELECT sql_saga.add_unique_key(table_oid => 'legal_unit', column_names => ARRAY['legal_ident'], unique_key_name => 'legal_unit_legal_ident_valid');
+-- Add a predicated unique key (e.g., only active units must have a unique name).
+SELECT sql_saga.add_unique_key(
+    table_oid => 'legal_unit',
+    column_names => ARRAY['name'],
+    predicate => 'status = ''active''',
+    unique_key_name => 'legal_unit_active_name_valid'
+);
 
 
 CREATE TABLE establishment (
   id SERIAL NOT NULL,
   name VARCHAR NOT NULL,
   address TEXT NOT NULL,
   legal_unit_id INTEGER NOT NULL,
-  valid_from TIMESTAMPTZ,
-  valid_until TIMESTAMPTZ
+  valid_from DATE,
+  valid_until DATE
 );
 
 SELECT sql_saga.add_era(table_oid => 'establishment', valid_from_column_name => 'valid_from', valid_until_column_name => 'valid_until');
@@ -237,14 +244,14 @@ SELECT sql_saga.drop_foreign_key(
     era_name => 'valid'
 );
 
-SELECT sql_saga.drop_unique_key(table_oid => 'establishment', key_name => 'establishment_id_valid');
-SELECT sql_saga.drop_unique_key(table_oid => 'establishment', key_name => 'establishment_name_valid');
+SELECT sql_saga.drop_unique_key_by_name(table_oid => 'establishment', key_name => 'establishment_id_valid');
+SELECT sql_saga.drop_unique_key_by_name(table_oid => 'establishment', key_name => 'establishment_name_valid');
 SELECT sql_saga.drop_era('establishment');
 
 
-SELECT sql_saga.drop_unique_key(table_oid => 'legal_unit', key_name => 'legal_unit_id_valid');
-SELECT sql_saga.drop_unique_key(table_oid => 'legal_unit', key_name => 'legal_unit_name_valid');
-SELECT sql_saga.drop_unique_key(table_oid => 'legal_unit', key_name => 'legal_unit_legal_ident_valid');
+SELECT sql_saga.drop_unique_key_by_name(table_oid => 'legal_unit', key_name => 'legal_unit_id_valid');
+SELECT sql_saga.drop_unique_key_by_name(table_oid => 'legal_unit', key_name => 'legal_unit_active_name_valid');
+SELECT sql_saga.drop_unique_key_by_name(table_oid => 'legal_unit', key_name => 'legal_unit_legal_ident_valid');
 SELECT sql_saga.drop_era('legal_unit');
 ```
 
@@ -279,7 +286,7 @@ The test suite uses `pg_regress` and is designed to be fully idempotent, creatin
 - `drop_era(table_oid regclass, era_name name DEFAULT 'valid', drop_behavior sql_saga.drop_behavior DEFAULT 'RESTRICT', cleanup boolean DEFAULT false) RETURNS boolean`
 
 ### Unique Keys
-- `add_unique_key(table_oid regclass, column_names name[], era_name name DEFAULT 'valid', unique_key_name name DEFAULT NULL, unique_constraint name DEFAULT NULL, exclude_constraint name DEFAULT NULL) RETURNS name`
+- `add_unique_key(table_oid regclass, column_names name[], era_name name DEFAULT 'valid', unique_key_name name DEFAULT NULL, unique_constraint name DEFAULT NULL, exclude_constraint name DEFAULT NULL, predicate text DEFAULT NULL) RETURNS name`
 - `drop_unique_key(table_oid regclass, column_names name[], era_name name, drop_behavior sql_saga.drop_behavior DEFAULT 'RESTRICT', cleanup boolean DEFAULT true) RETURNS void`
 - `drop_unique_key_by_name(table_oid regclass, key_name name, drop_behavior sql_saga.drop_behavior DEFAULT 'RESTRICT', cleanup boolean DEFAULT true) RETURNS void`
 

expected/03_api_symmetry_test.out

@@ -122,9 +122,9 @@ TABLE sql_saga.foreign_keys;
 
 -- Test overloaded drop_unique_key
 TABLE sql_saga.unique_keys;
- unique_key_name | table_schema | table_name | column_names | era_name |          unique_constraint           |    exclude_constraint    
------------------+--------------+------------+--------------+----------+--------------------------------------+--------------------------
- parent_id_p     | public       | parent     | {id}         | p        | parent_id_valid_from_valid_until_key | parent_id_int4range_excl
+ unique_key_name | table_schema | table_name | column_names | era_name |          unique_constraint           | exclude_constraint | predicate 
+-----------------+--------------+------------+--------------+----------+--------------------------------------+--------------------+-----------
+ parent_id_p     | public       | parent     | {id}         | p        | parent_id_valid_from_valid_until_key | parent_id_p_excl   | 
 (1 row)
 
 SELECT sql_saga.drop_unique_key('parent', ARRAY['id'], 'p');
@@ -134,8 +134,8 @@ SELECT sql_saga.drop_unique_key('parent', ARRAY['id'], 'p');
 (1 row)
 
 TABLE sql_saga.unique_keys;
- unique_key_name | table_schema | table_name | column_names | era_name | unique_constraint | exclude_constraint 
------------------+--------------+------------+--------------+----------+-------------------+--------------------
+ unique_key_name | table_schema | table_name | column_names | era_name | unique_constraint | exclude_constraint | predicate 
+-----------------+--------------+------------+--------------+----------+-------------------+--------------------+-----------
 (0 rows)
 
 -- Test original drop_unique_key (with positional and named arguments)
@@ -146,9 +146,9 @@ SELECT sql_saga.add_unique_key('parent', ARRAY['id'], 'p');
 (1 row)
 
 TABLE sql_saga.unique_keys;
- unique_key_name | table_schema | table_name | column_names | era_name |          unique_constraint           |    exclude_constraint    
------------------+--------------+------------+--------------+----------+--------------------------------------+--------------------------
- parent_id_p     | public       | parent     | {id}         | p        | parent_id_valid_from_valid_until_key | parent_id_int4range_excl
+ unique_key_name | table_schema | table_name | column_names | era_name |          unique_constraint           | exclude_constraint | predicate 
+-----------------+--------------+------------+--------------+----------+--------------------------------------+--------------------+-----------
+ parent_id_p     | public       | parent     | {id}         | p        | parent_id_valid_from_valid_until_key | parent_id_p_excl   | 
 (1 row)
 
 -- by name (positional)
@@ -159,8 +159,8 @@ SELECT sql_saga.drop_unique_key_by_name('parent', 'parent_id_p');
 (1 row)
 
 TABLE sql_saga.unique_keys;
- unique_key_name | table_schema | table_name | column_names | era_name | unique_constraint | exclude_constraint 
------------------+--------------+------------+--------------+----------+-------------------+--------------------
+ unique_key_name | table_schema | table_name | column_names | era_name | unique_constraint | exclude_constraint | predicate 
+-----------------+--------------+------------+--------------+----------+-------------------+--------------------+-----------
 (0 rows)
 
 -- Re-create to test named arguments
@@ -171,9 +171,9 @@ SELECT sql_saga.add_unique_key('parent', ARRAY['id'], 'p');
 (1 row)
 
 TABLE sql_saga.unique_keys;
- unique_key_name | table_schema | table_name | column_names | era_name |          unique_constraint           |    exclude_constraint    
------------------+--------------+------------+--------------+----------+--------------------------------------+--------------------------
- parent_id_p     | public       | parent     | {id}         | p        | parent_id_valid_from_valid_until_key | parent_id_int4range_excl
+ unique_key_name | table_schema | table_name | column_names | era_name |          unique_constraint           | exclude_constraint | predicate 
+-----------------+--------------+------------+--------------+----------+--------------------------------------+--------------------+-----------
+ parent_id_p     | public       | parent     | {id}         | p        | parent_id_valid_from_valid_until_key | parent_id_p_excl   | 
 (1 row)
 
 -- by name (named)
@@ -184,8 +184,8 @@ SELECT sql_saga.drop_unique_key_by_name(table_oid => 'parent', key_name => 'pare
 (1 row)
 
 TABLE sql_saga.unique_keys;
- unique_key_name | table_schema | table_name | column_names | era_name | unique_constraint | exclude_constraint 
------------------+--------------+------------+--------------+----------+-------------------+--------------------
+ unique_key_name | table_schema | table_name | column_names | era_name | unique_constraint | exclude_constraint | predicate 
+-----------------+--------------+------------+--------------+----------+-------------------+--------------------+-----------
 (0 rows)
 
 -- Test symmetrical add_era/drop_era with column management

expected/06_unique_foreign.out

@@ -42,16 +42,16 @@ SELECT sql_saga.add_unique_key('uk'::regclass, ARRAY['id'], 'p', unique_key_name
 (1 row)
 
 TABLE sql_saga.unique_keys;
- unique_key_name | table_schema | table_name | column_names | era_name | unique_constraint |  exclude_constraint  
------------------+--------------+------------+--------------+----------+-------------------+----------------------
- uk_id_p         | public       | uk         | {id}         | p        | uk_pkey           | uk_id_int4range_excl
+ unique_key_name | table_schema | table_name | column_names | era_name | unique_constraint | exclude_constraint | predicate 
+-----------------+--------------+------------+--------------+----------+-------------------+--------------------+-----------
+ uk_id_p         | public       | uk         | {id}         | p        | uk_pkey           | uk_id_p_excl       | 
 (1 row)
 
 INSERT INTO uk (id, valid_from, valid_until) VALUES (100, 2, 4), (100, 4, 5), (100, 5, 11); -- success
 INSERT INTO uk (id, valid_from, valid_until) VALUES (200, 2, 4), (200, 4, 5), (200, 6, 11); -- success
 SAVEPOINT pristine;
 INSERT INTO uk (id, valid_from, valid_until) VALUES (300, 2, 4), (300, 4, 6), (300, 5, 11); -- fail
-ERROR:  conflicting key value violates exclusion constraint "uk_id_int4range_excl"
+ERROR:  conflicting key value violates exclusion constraint "uk_id_p_excl"
 DETAIL:  Key (id, int4range(valid_from, valid_until))=(300, [5,11)) conflicts with existing key (id, int4range(valid_from, valid_until))=(300, [4,6)).
 ROLLBACK TO SAVEPOINT pristine;
 CREATE TABLE fk (id integer, uk_id integer, valid_from integer, valid_until integer, PRIMARY KEY (id));

expected/09_drop_protection.out

@@ -102,12 +102,12 @@ SELECT sql_saga.add_unique_key('dp', ARRAY['id'], 'p', 'k', 'u', 'x');
 SAVEPOINT s7;
 ALTER TABLE dp DROP CONSTRAINT u; -- fails
 ERROR:  cannot drop constraint "u" on table "dp" because it is used in era unique key "k"
-CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 219 at RAISE
+CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 232 at RAISE
 ROLLBACK TO SAVEPOINT s7;
 SAVEPOINT s8;
 ALTER TABLE dp DROP CONSTRAINT x; -- fails
 ERROR:  cannot drop constraint "x" on table "dp" because it is used in era unique key "k"
-CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 231 at RAISE
+CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 248 at RAISE
 ROLLBACK TO SAVEPOINT s8;
 SAVEPOINT s9;
 ALTER TABLE dp DROP CONSTRAINT dp_p_check; -- fails
@@ -129,22 +129,22 @@ SELECT sql_saga.add_foreign_key('dp_ref', ARRAY['id'], 'p', 'k', foreign_key_nam
 SAVEPOINT s10;
 DROP TRIGGER f_fk_insert ON dp_ref; -- fails
 ERROR:  cannot drop trigger "f_fk_insert" on table "dp_ref" because it is used in era foreign key "f"
-CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 247 at RAISE
+CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 265 at RAISE
 ROLLBACK TO SAVEPOINT s10;
 SAVEPOINT s11;
 DROP TRIGGER f_fk_update ON dp_ref; -- fails
 ERROR:  cannot drop trigger "f_fk_update" on table "dp_ref" because it is used in era foreign key "f"
-CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 258 at RAISE
+CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 276 at RAISE
 ROLLBACK TO SAVEPOINT s11;
 SAVEPOINT s12;
 DROP TRIGGER f_uk_update ON dp; -- fails
 ERROR:  cannot drop trigger "f_uk_update" on table "dp" because it is used in era foreign key "f"
-CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 270 at RAISE
+CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 288 at RAISE
 ROLLBACK TO SAVEPOINT s12;
 SAVEPOINT s13;
 DROP TRIGGER f_uk_delete ON dp; -- fails
 ERROR:  cannot drop trigger "f_uk_delete" on table "dp" because it is used in era foreign key "f"
-CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 282 at RAISE
+CONTEXT:  PL/pgSQL function sql_saga.drop_protection() line 300 at RAISE
 ROLLBACK TO SAVEPOINT s13;
 SELECT sql_saga.drop_foreign_key('dp_ref', ARRAY['id'], 'p');
  drop_foreign_key 

expected/10_rename_following.out

@@ -113,18 +113,18 @@ SELECT sql_saga.add_unique_key('rename_test', ARRAY['col2', 'col1', 'col3'], 'p'
 (1 row)
 
 TABLE sql_saga.unique_keys;
-       unique_key_name        | table_schema | table_name  |   column_names   | era_name |                    unique_constraint                    |            exclude_constraint             
-------------------------------+--------------+-------------+------------------+----------+---------------------------------------------------------+-------------------------------------------
- rename_test_col2_col1_col3_p | public       | rename_test | {col2,col1,col3} | p        | rename_test_col2_col1_col3_s < e_embedded " symbols_key | rename_test_col2_col1_col3_int4range_excl
+       unique_key_name        | table_schema | table_name  |   column_names   | era_name |                    unique_constraint                    |        exclude_constraint         | predicate 
+------------------------------+--------------+-------------+------------------+----------+---------------------------------------------------------+-----------------------------------+-----------
+ rename_test_col2_col1_col3_p | public       | rename_test | {col2,col1,col3} | p        | rename_test_col2_col1_col3_s < e_embedded " symbols_key | rename_test_col2_col1_col3_p_excl | 
 (1 row)
 
 ALTER TABLE rename_test RENAME COLUMN col1 TO "COLUMN1";
 ALTER TABLE rename_test RENAME CONSTRAINT "rename_test_col2_col1_col3_s < e_embedded "" symbols_key" TO unconst;
-ALTER TABLE rename_test RENAME CONSTRAINT rename_test_col2_col1_col3_int4range_excl TO exconst;
+ALTER TABLE rename_test RENAME CONSTRAINT rename_test_col2_col1_col3_p_excl TO exconst;
 TABLE sql_saga.unique_keys;
-       unique_key_name        | table_schema | table_name  |    column_names     | era_name | unique_constraint | exclude_constraint 
-------------------------------+--------------+-------------+---------------------+----------+-------------------+--------------------
- rename_test_col2_col1_col3_p | public       | rename_test | {col2,COLUMN1,col3} | p        | unconst           | exconst
+       unique_key_name        | table_schema | table_name  |    column_names     | era_name | unique_constraint | exclude_constraint | predicate 
+------------------------------+--------------+-------------+---------------------+----------+-------------------+--------------------+-----------
+ rename_test_col2_col1_col3_p | public       | rename_test | {col2,COLUMN1,col3} | p        | unconst           | exconst            | 
 (1 row)
 
 /* foreign_keys */

expected/13_issues.out

@@ -166,7 +166,7 @@ ROLLBACK TO SAVEPOINT s4;
 SAVEPOINT s5;
 INSERT INTO uk(id, f, u)        VALUES    (4, 1, 4),
                                           (4, 3, 5);
-ERROR:  conflicting key value violates exclusion constraint "uk_id_int4range_excl"
+ERROR:  conflicting key value violates exclusion constraint "uk_id_p_excl"
 DETAIL:  Key (id, int4range(f, u))=(4, [3,5)) conflicts with existing key (id, int4range(f, u))=(4, [1,4)).
 ROLLBACK TO SAVEPOINT s5;
 SELECT sql_saga.drop_foreign_key('fk', ARRAY['uk_id'], 'q');