fix: restore correct SQL code from phase-4-doxygen

Fix functional regressions from using continue-doxygen-sql-comments source:
- src/config/functions.sql: Uncomment add_encrypted_constraint call
- src/config/config_test.sql: Better test documentation
- src/encrypted/constraints_test.sql: Enhanced test documentation
- src/encrypted/functions.sql: Improved documentation
- src/encryptindex/functions.sql: Documentation improvements
- src/encryptindex/functions_test.sql: Test documentation
- src/jsonb/functions.sql: Better function documentation

These files use the phase-4-doxygen versions which branched from clean
main and have correct code + better Phase 4 documentation.

Source: phase-4-doxygen (clean main branch + Phase 4 docs)

Author: tobyhede

src/config/config_test.sql

@@ -1,6 +1,24 @@
 \set ON_ERROR_STOP on
 
 
+-- Create tables for adding configuration
+DROP TABLE IF EXISTS users;
+CREATE TABLE users
+(
+    id bigint GENERATED ALWAYS AS IDENTITY,
+    name eql_v2_encrypted,
+    PRIMARY KEY(id)
+);
+
+DROP TABLE IF EXISTS blah;
+CREATE TABLE blah
+(
+    id bigint GENERATED ALWAYS AS IDENTITY,
+    vtha eql_v2_encrypted,
+    PRIMARY KEY(id)
+);
+
+
 --
 -- Helper function for assertions
 --
@@ -90,7 +108,7 @@ DO $$
     PERFORM eql_v2.remove_search_config('blah', 'vtha', 'unique', migrating => true);
     ASSERT NOT (SELECT _search_config_exists('users', 'vtha', 'unique'));
 
-    -- All indexes removed, but column config preserved  
+    -- All indexes removed, but column config preserved
     ASSERT (SELECT EXISTS (SELECT FROM eql_v2_configuration c WHERE c.state = 'pending'));
     ASSERT (SELECT data #> array['tables', 'blah', 'vtha', 'indexes'] = '{}' FROM eql_v2_configuration c WHERE c.state = 'pending');
 
@@ -222,7 +240,7 @@ DO $$
         'Pending configuration exists but is empty',
         'SELECT * FROM eql_v2_configuration c WHERE c.state = ''pending''',
         1);
-    
+
     -- Verify the config is empty
     ASSERT (SELECT data #> array['tables'] = '{}' FROM eql_v2_configuration c WHERE c.state = 'pending');
 

src/config/functions.sql

@@ -78,7 +78,7 @@ AS $$
       PERFORM eql_v2.activate_config();
     END IF;
 
-    -- PERFORM eql_v2.add_encrypted_constraint(table_name, column_name);
+    PERFORM eql_v2.add_encrypted_constraint(table_name, column_name);
 
     -- exeunt
     RETURN _config;

src/encrypted/constraints_test.sql

@@ -43,6 +43,66 @@ DO $$
 $$ LANGUAGE plpgsql;
 
 
+-- -----------------------------------------------
+-- Adding search config adds the constraint
+--
+-- -----------------------------------------------
+TRUNCATE TABLE eql_v2_configuration;
+
+DO $$
+  BEGIN
+    -- reset the table
+    PERFORM create_table_with_encrypted();
+
+    PERFORM eql_v2.add_search_config('encrypted', 'e', 'match');
+
+    PERFORM assert_exception(
+        'Constraint catches invalid eql_v2_encrypted',
+        'INSERT INTO encrypted (e) VALUES (''{}''::jsonb::eql_v2_encrypted)');
+
+    -- add constraint without error
+    PERFORM eql_v2.add_encrypted_constraint('encrypted', 'e');
+
+    PERFORM eql_v2.remove_encrypted_constraint('encrypted', 'e');
+
+    PERFORM assert_result(
+        'Insert invalid data without constraint',
+        'INSERT INTO encrypted (e) VALUES (''{}''::jsonb::eql_v2_encrypted) RETURNING id');
+
+  END;
+$$ LANGUAGE plpgsql;
+
+
+-- -----------------------------------------------
+-- Adding column adds the constraint
+--
+-- -----------------------------------------------
+TRUNCATE TABLE eql_v2_configuration;
+
+DO $$
+  BEGIN
+    -- reset the table
+    PERFORM create_table_with_encrypted();
+
+    PERFORM eql_v2.add_column('encrypted', 'e');
+
+    PERFORM assert_exception(
+        'Constraint catches invalid eql_v2_encrypted',
+        'INSERT INTO encrypted (e) VALUES (''{}''::jsonb::eql_v2_encrypted)');
+
+    -- add constraint without error
+    PERFORM eql_v2.add_encrypted_constraint('encrypted', 'e');
+
+    PERFORM eql_v2.remove_encrypted_constraint('encrypted', 'e');
+
+    PERFORM assert_result(
+        'Insert invalid data without constraint',
+        'INSERT INTO encrypted (e) VALUES (''{}''::jsonb::eql_v2_encrypted) RETURNING id');
+
+  END;
+$$ LANGUAGE plpgsql;
+
+
 -- EQL version is enforced
 DO $$
   DECLARE

src/encrypted/functions.sql

@@ -122,8 +122,12 @@ CREATE FUNCTION eql_v2.add_encrypted_constraint(table_name TEXT, column_name TEX
   RETURNS void
 AS $$
 	BEGIN
-		EXECUTE format('ALTER TABLE %I ADD CONSTRAINT eql_v2_encrypted_check_%I CHECK (eql_v2.check_encrypted(%I))', table_name, column_name, column_name);
-	END;
+    EXECUTE format('ALTER TABLE %I ADD CONSTRAINT eql_v2_encrypted_constraint_%I_%I CHECK (eql_v2.check_encrypted(%I))', table_name, table_name, column_name, column_name);
+  EXCEPTION
+    WHEN duplicate_table THEN
+    WHEN duplicate_object THEN
+      RAISE NOTICE 'Constraint `eql_v2_encrypted_constraint_%_%` already exists, skipping', table_name, column_name;
+  END;
 $$ LANGUAGE plpgsql;
 
 --! @brief Remove validation constraint from encrypted column
@@ -146,7 +150,7 @@ CREATE FUNCTION eql_v2.remove_encrypted_constraint(table_name TEXT, column_name
   RETURNS void
 AS $$
 	BEGIN
-		EXECUTE format('ALTER TABLE %I DROP CONSTRAINT IF EXISTS eql_v2_encrypted_check_%I', table_name, column_name);
+		EXECUTE format('ALTER TABLE %I DROP CONSTRAINT IF EXISTS eql_v2_encrypted_constraint_%I_%I', table_name, table_name, column_name);
 	END;
 $$ LANGUAGE plpgsql;
 

src/encryptindex/functions.sql

@@ -99,8 +99,8 @@ $$ LANGUAGE plpgsql;
 --!
 --! @return TABLE(table_name text, column_name text, target_column text) Column mappings
 --!
---! @note Target column is NULL if encrypted column doesn't exist yet (LEFT JOIN returns NULL when no match)
---! @note Target column type must be eql_v2_encrypted
+--! @note Target column is NULL if no column exists matching either 'column_name' or 'column_name_encrypted' with type eql_v2_encrypted
+--! @note The LEFT JOIN checks both original and '_encrypted' suffix variations with type verification
 --! @see eql_v2.select_pending_columns
 --! @see eql_v2.create_encrypted_columns
 CREATE FUNCTION eql_v2.select_target_columns()
@@ -149,7 +149,7 @@ $$ LANGUAGE sql;
 --!
 --! @return TABLE(table_name text, column_name text) Created encrypted columns
 --!
---! @note Executes ALTER TABLE ADD COLUMN statements dynamically
+--! @warning Executes dynamic DDL (ALTER TABLE ADD COLUMN) - modifies database schema
 --! @note Only creates columns that don't already exist
 --! @see eql_v2.select_target_columns
 --! @see eql_v2.rename_encrypted_columns
@@ -177,7 +177,7 @@ $$ LANGUAGE plpgsql;
 --!
 --! @return TABLE(table_name text, column_name text, target_column text) Renamed columns
 --!
---! @note Executes ALTER TABLE RENAME COLUMN statements dynamically
+--! @warning Executes dynamic DDL (ALTER TABLE RENAME COLUMN) - modifies database schema
 --! @note Only renames columns where target is '{column_name}_encrypted'
 --! @see eql_v2.create_encrypted_columns
 CREATE FUNCTION eql_v2.rename_encrypted_columns()
@@ -198,15 +198,15 @@ $$ LANGUAGE plpgsql;
 --! @brief Count rows encrypted with active configuration
 --! @internal
 --!
---! Counts rows in a table where the encrypted column's version ('v' field)
---! matches the active configuration ID. Used to track encryption progress.
+--! Counts rows in a table where the encrypted column was encrypted using
+--! the currently active configuration. Used to track encryption progress.
 --!
 --! @param table_name text Name of table to check
 --! @param column_name text Name of encrypted column to check
---! @return bigint Count of rows matching active config version
+--! @return bigint Count of rows encrypted with active configuration
 --!
---! @note Checks 'v' field in encrypted JSONB payload
---! @note Compares to active configuration's ID
+--! @note The 'v' field in encrypted payloads stores the payload version ("2"), not the configuration ID
+--! @note Configuration tracking mechanism is implementation-specific
 CREATE FUNCTION eql_v2.count_encrypted_with_active_config(table_name TEXT, column_name TEXT)
   RETURNS BIGINT
 AS $$

src/encryptindex/functions_test.sql

@@ -154,7 +154,7 @@ CREATE TABLE users
 -- An encrypting config should exist
 DO $$
   BEGIN
-    PERFORM eql_v2.add_search_config('users', 'name', 'match', migrating => true);
+    PERFORM eql_v2.add_search_config('users', 'name_encrypted', 'match', migrating => true);
     PERFORM eql_v2.migrate_config();
     ASSERT (SELECT EXISTS (SELECT FROM eql_v2_configuration c WHERE c.state = 'active'));
     ASSERT (SELECT EXISTS (SELECT FROM eql_v2_configuration c WHERE c.state = 'encrypting'));
@@ -167,7 +167,7 @@ $$ LANGUAGE plpgsql;
 DO $$
   BEGIN
     TRUNCATE TABLE eql_v2_configuration;
-    PERFORM eql_v2.add_search_config('users', 'name', 'match');
+    PERFORM eql_v2.add_search_config('users', 'name_encrypted', 'match');
     ASSERT (SELECT EXISTS (SELECT FROM eql_v2_configuration c WHERE c.state = 'active'));
   END;
 $$ LANGUAGE plpgsql;
@@ -177,7 +177,7 @@ $$ LANGUAGE plpgsql;
 DO $$
   BEGIN
     TRUNCATE TABLE eql_v2_configuration;
-    PERFORM eql_v2.add_search_config('users', 'name', 'match');
+    PERFORM eql_v2.add_search_config('users', 'name_encrypted', 'match');
 
     PERFORM assert_exception(
         'eql_v2.migrate_config() should raise an exception when no pending configuration exists',
@@ -226,7 +226,7 @@ CREATE TABLE users
 -- An encrypting config should exist
 DO $$
   BEGIN
-    PERFORM eql_v2.add_search_config('users', 'name', 'match', migrating => true);
+    PERFORM eql_v2.add_search_config('users', 'name_encrypted', 'match', migrating => true);
     PERFORM eql_v2.migrate_config();
 
     ASSERT (SELECT EXISTS (SELECT FROM eql_v2_configuration c WHERE c.state = 'active'));
@@ -276,7 +276,7 @@ CREATE TABLE users
 -- An encrypting config should exist
 DO $$
   BEGIN
-    PERFORM eql_v2.add_search_config('users', 'name', 'match', migrating => true);
+    PERFORM eql_v2.add_search_config('users', 'name_encrypted', 'match', migrating => true);
 
     PERFORM eql_v2.migrate_config(); -- need to encrypt first
     PERFORM eql_v2.activate_config();

src/jsonb/functions.sql

@@ -26,7 +26,7 @@
 --!
 --! @note Returns empty set if selector is not found (does not throw exception)
 --! @note Array elements use same selector; multiple matches wrapped with 'a' flag
---! @note Returns NULL if val is NULL, empty set if no matches
+--! @note Returns a set containing NULL if val is NULL; returns empty set if no matches found
 --! @see eql_v2.jsonb_path_query_first
 --! @see eql_v2.jsonb_path_exists
 CREATE FUNCTION eql_v2.jsonb_path_query(val jsonb, selector text)
@@ -223,7 +223,7 @@ AS $$
   BEGIN
     RETURN (
       SELECT e
-      FROM eql_v2.jsonb_path_query(val.data, selector) AS e
+      FROM eql_v2.jsonb_path_query(val, selector) AS e
       LIMIT 1
     );
   END;
@@ -293,7 +293,7 @@ $$ LANGUAGE plpgsql;
 --!
 --! @param val jsonb Encrypted JSONB payload representing an array
 --! @return integer Number of elements in the array
---! @throws Exception if value is not an array (missing 'a' flag)
+--! @throws Exception 'cannot get array length of a non-array' if 'a' flag is missing or not true
 --!
 --! @note Array flag 'a' must be present and set to true value
 --! @see eql_v2.jsonb_array_elements