velocity-python 0.0.105__py3-none-any.whl → 0.0.155__py3-none-any.whl

velocity/db/servers/postgres/sql.py

@@ -1,13 +1,14 @@
 import re
 import hashlib
 import sqlparse
-from psycopg2 import sql
+from psycopg2 import sql as psycopg2_sql
 
 from velocity.db import exceptions
+from ..base.sql import BaseSQLDialect
 
 from .reserved import reserved_words
 from .types import TYPES
-from .operators import OPERATORS
+from .operators import OPERATORS, PostgreSQLOperators
 from ..tablehelper import TableHelper
 from collections.abc import Mapping, Sequence
 
@@ -17,66 +18,46 @@ TableHelper.reserved = reserved_words
 TableHelper.operators = OPERATORS
 
 
-def _get_table_helper(tx, table):
-    """
-    Utility function to create a TableHelper instance.
-    Ensures consistent configuration across all SQL methods.
-    """
-    return TableHelper(tx, table)
-
-
-def _validate_table_name(table):
-    """Validate table name format."""
-    if not table or not isinstance(table, str):
-        raise ValueError("Table name must be a non-empty string")
-    # Add more validation as needed
-    return table.strip()
-
-
-def _handle_predicate_errors(predicates, operation="WHERE"):
-    """Process a list of predicates with error handling."""
-    sql_parts = []
-    vals = []
-    
-    for pred, val in predicates:
-        sql_parts.append(pred)
-        if val is None:
-            pass
-        elif isinstance(val, tuple):
-            vals.extend(val)
-        else:
-            vals.append(val)
-    
-    return sql_parts, vals
-
-
 system_fields = [
     "sys_id",
     "sys_created",
     "sys_modified",
     "sys_modified_by",
+    "sys_modified_row",
+    "sys_modified_count",
     "sys_dirty",
     "sys_table",
     "description",
 ]
 
 
-class SQL:
+class SQL(BaseSQLDialect):
     server = "PostGreSQL"
     type_column_identifier = "data_type"
     is_nullable = "is_nullable"
 
     default_schema = "public"
 
-    ApplicationErrorCodes = ["22P02", "42883", "42501", "42601", "25P01", "25P02"]
+    ApplicationErrorCodes = ["22P02", "42883", "42501", "42601", "25P01", "25P02", "42804"]  # Added 42804 for datatype mismatch
 
     DatabaseMissingErrorCodes = ["3D000"]
     TableMissingErrorCodes = ["42P01"]
     ColumnMissingErrorCodes = ["42703"]
     ForeignKeyMissingErrorCodes = ["42704"]
 
-    ConnectionErrorCodes = ["08001", "08S01", "57P03", "08006", "53300", "08003", "08004", "08P01"]
-    DuplicateKeyErrorCodes = ["23505"]  # unique_violation - no longer relying only on regex
+    ConnectionErrorCodes = [
+        "08001",
+        "08S01",
+        "57P03",
+        "08006",
+        "53300",
+        "08003",
+        "08004",
+        "08P01",
+    ]
+    DuplicateKeyErrorCodes = [
+        "23505"
+    ]  # unique_violation - no longer relying only on regex
     RetryTransactionCodes = ["40001", "40P01", "40002"]
     TruncationErrorCodes = ["22001"]
     LockTimeoutErrorCodes = ["55P03"]
@@ -84,7 +65,7 @@ class SQL:
     DataIntegrityErrorCodes = ["23503", "23502", "23514", "23P01", "22003"]
 
     @classmethod
-    def get_error(self, e):
+    def get_error(cls, e):
         error_code = getattr(e, "pgcode", None)
         error_mesg = getattr(e, "pgerror", None)
         return error_code, error_mesg
@@ -111,7 +92,7 @@ class SQL:
         """
         if not table:
             raise ValueError("Table name is required.")
-            
+
         # Validate pagination parameters
         if start is not None and not isinstance(start, int):
             raise ValueError("Start (OFFSET) must be an integer.")
@@ -131,7 +112,7 @@ class SQL:
         vals = []
 
         # Create table helper instance
-        th = _get_table_helper(tx, table)
+        th = TableHelper(tx, table)
 
         # Handle columns and DISTINCT before aliasing
         if columns is None:
@@ -148,7 +129,7 @@ class SQL:
         columns = [c.strip() for c in columns if c.strip()]  # Remove empty columns
         if not columns:
             raise ValueError("No valid columns specified")
-            
+
         distinct = False
 
         # Check for DISTINCT keyword in any column
@@ -188,7 +169,7 @@ class SQL:
         new_orderby = []
         if isinstance(orderby, str):
             orderby = th.split_columns(orderby)
-            
+
         # Handle orderby references
         if isinstance(orderby, Sequence):
             for column in orderby:
@@ -200,7 +181,9 @@ class SQL:
                             # Validate direction
                             direction = direction.upper()
                             if direction not in ("ASC", "DESC"):
-                                raise ValueError(f"Invalid ORDER BY direction: {direction}")
+                                raise ValueError(
+                                    f"Invalid ORDER BY direction: {direction}"
+                                )
                             col_name = th.resolve_references(
                                 col_name.strip(), options={"alias_only": True}
                             )
@@ -213,7 +196,9 @@ class SQL:
                         )
                         new_orderby.append(resolved_col)
                 except Exception as e:
-                    raise ValueError(f"Error processing ORDER BY column '{column}': {e}")
+                    raise ValueError(
+                        f"Error processing ORDER BY column '{column}': {e}"
+                    )
 
         elif isinstance(orderby, Mapping):
             for key, val in orderby.items():
@@ -222,11 +207,13 @@ class SQL:
                     direction = str(val).upper()
                     if direction not in ("ASC", "DESC"):
                         raise ValueError(f"Invalid ORDER BY direction: {direction}")
-                    parsed_key = th.resolve_references(key, options={"alias_only": True})
+                    parsed_key = th.resolve_references(
+                        key, options={"alias_only": True}
+                    )
                     new_orderby.append(f"{parsed_key} {direction}")
                 except Exception as e:
                     raise ValueError(f"Error processing ORDER BY key '{key}': {e}")
-                    
+
         orderby = new_orderby
 
         # Handle groupby
@@ -256,7 +243,9 @@ class SQL:
 
         # FROM clause
         if th.foreign_keys:
-            sql_parts["FROM"].append(f"{TableHelper.quote(table)} AS {TableHelper.quote(alias)}")
+            sql_parts["FROM"].append(
+                f"{TableHelper.quote(table)} AS {TableHelper.quote(alias)}"
+            )
             # Handle joins
             done = []
             for key, ref_info in th.foreign_keys.items():
@@ -276,11 +265,44 @@ class SQL:
         else:
             sql_parts["FROM"].append(TableHelper.quote(table))
 
-        # WHERE
+        # WHERE - Enhanced validation to prevent malformed SQL
         if where:
             if isinstance(where, str):
+                # Validate string WHERE clauses to prevent malformed SQL
+                where_stripped = where.strip()
+                if not where_stripped:
+                    raise ValueError("WHERE clause cannot be empty string.")
+                # Check for boolean literals first (includes '1' and '0')
+                if where_stripped in ('True', 'False', '1', '0'):
+                    raise ValueError(
+                        f"Invalid WHERE clause: '{where}'. "
+                        "Boolean literals alone are not valid WHERE clauses. "
+                        "Use complete SQL expressions like 'sys_active = true' instead."
+                    )
+                # Then check for other numeric values (excluding '1' and '0' already handled above)
+                elif where_stripped.isdigit():
+                    raise ValueError(
+                        f"Invalid WHERE clause: '{where}'. "
+                        "Bare integers are not valid WHERE clauses. "
+                        "Use a dictionary like {{'sys_id': {where_stripped}}} or "
+                        f"a complete SQL expression like 'sys_id = {where_stripped}' instead."
+                    )
                 sql_parts["WHERE"].append(where)
-            else:
+            elif isinstance(where, (int, float, bool)):
+                # Handle primitive types that should be converted to proper WHERE clauses
+                suggested_fix = "{'sys_id': " + str(where) + "}" if isinstance(where, int) else "complete SQL expression"
+                raise ValueError(
+                    f"Invalid WHERE clause: {where} (type: {type(where).__name__}). "
+                    f"Primitive values cannot be WHERE clauses directly. "
+                    f"Use a dictionary like {suggested_fix} or a complete SQL string instead. "
+                    f"This error prevents PostgreSQL 'argument of WHERE must be type boolean' errors."
+                )
+            elif isinstance(where, Mapping):
+                # Convert dictionary to predicate list
+                new_where = []
+                for key, val in where.items():
+                    new_where.append(th.make_predicate(key, val))
+                where = new_where
                 for pred, val in where:
                     sql_parts["WHERE"].append(pred)
                     if val is None:
@@ -289,6 +311,22 @@ class SQL:
                         vals.extend(val)
                     else:
                         vals.append(val)
+            else:
+                # Handle list of tuples or other iterable
+                try:
+                    for pred, val in where:
+                        sql_parts["WHERE"].append(pred)
+                        if val is None:
+                            pass
+                        elif isinstance(val, tuple):
+                            vals.extend(val)
+                        else:
+                            vals.append(val)
+                except (TypeError, ValueError) as e:
+                    raise ValueError(
+                        f"Invalid WHERE clause format: {where}. "
+                        "Expected dictionary, list of (predicate, value) tuples, or SQL string."
+                    ) from e
 
         # GROUP BY
         if groupby:
@@ -378,7 +416,7 @@ class SQL:
         if not isinstance(data, Mapping) or not data:
             raise ValueError("data must be a non-empty mapping of column-value pairs.")
 
-        th = _get_table_helper(tx, table)
+        th = TableHelper(tx, table)
         set_clauses = []
         vals = []
 
@@ -417,17 +455,53 @@ class SQL:
                     for key, val in where.items():
                         new_where.append(th.make_predicate(key, val))
                     where = new_where
-                if isinstance(where, str):
+                elif isinstance(where, str):
+                    # Enhanced validation for string WHERE clauses
+                    where_stripped = where.strip()
+                    if not where_stripped:
+                        raise ValueError("WHERE clause cannot be empty string.")
+                    # Check for boolean literals first (includes '1' and '0')
+                    if where_stripped in ('True', 'False', '1', '0'):
+                        raise ValueError(
+                            f"Invalid WHERE clause: '{where}'. "
+                            "Boolean literals alone are not valid WHERE clauses. "
+                            "Use complete SQL expressions like 'sys_active = true' instead."
+                        )
+                    # Then check for other numeric values (excluding '1' and '0' already handled above)
+                    elif where_stripped.isdigit():
+                        raise ValueError(
+                            f"Invalid WHERE clause: '{where}'. "
+                            "Bare integers are not valid WHERE clauses. "
+                            f"Use a dictionary like {{'sys_id': {where_stripped}}} or "
+                            f"a complete SQL expression like 'sys_id = {where_stripped}' instead."
+                        )
                     where_clauses.append(where)
-                else:
-                    for pred, value in where:
-                        where_clauses.append(pred)
-                        if value is None:
-                            pass
-                        elif isinstance(value, tuple):
-                            vals.extend(value)
-                        else:
-                            vals.append(value)
+                elif isinstance(where, (int, float, bool)):
+                    # Handle primitive types that should be converted to proper WHERE clauses
+                    suggested_fix = "{'sys_id': " + str(where) + "}" if isinstance(where, int) else "complete SQL expression"
+                    raise ValueError(
+                        f"Invalid WHERE clause: {where} (type: {type(where).__name__}). "
+                        f"Primitive values cannot be WHERE clauses directly. "
+                        f"Use a dictionary like {suggested_fix} or a complete SQL string instead. "
+                        f"This error prevents PostgreSQL 'argument of WHERE must be type boolean' errors."
+                    )
+                
+                # Process the where clause if it's a list of tuples
+                if not isinstance(where, str):
+                    try:
+                        for pred, value in where:
+                            where_clauses.append(pred)
+                            if value is None:
+                                pass
+                            elif isinstance(value, tuple):
+                                vals.extend(value)
+                            else:
+                                vals.append(value)
+                    except (TypeError, ValueError) as e:
+                        raise ValueError(
+                            f"Invalid WHERE clause format: {where}. "
+                            "Expected dictionary, list of (predicate, value) tuples, or SQL string."
+                        ) from e
             if not where_clauses:
                 raise ValueError(
                     "No WHERE clause could be constructed. Update would affect all rows."
@@ -463,7 +537,7 @@ class SQL:
         # Create a temporary TableHelper instance for quoting
         # Note: We pass None for tx since we only need quoting functionality
         temp_helper = TableHelper(None, table)
-        
+
         keys = []
         vals_placeholders = []
         args = []
@@ -490,51 +564,164 @@ class SQL:
 
     @classmethod
     def merge(cls, tx, table, data, pk, on_conflict_do_nothing, on_conflict_update):
+        if not isinstance(data, Mapping) or not data:
+            raise ValueError("data must be a non-empty mapping of column-value pairs.")
+
+        table_helper = TableHelper(tx, table)
+        data = dict(data)  # work with a copy to avoid mutating the caller's dict
+
         if pk is None:
             pkeys = tx.table(table).primary_keys()
             if not pkeys:
                 raise ValueError("Primary key required for merge.")
-            # If there are multiple primary keys, use all of them
-            if len(pkeys) > 1:
-                pk = {pk: data[pk] for pk in pkeys}
-            else:
-                pk = {pkeys[0]: data[pkeys[0]]}
-            # Remove primary keys from data; they will be used in the conflict target
-            data = {k: v for k, v in data.items() if k not in pk}
+            missing = [key for key in pkeys if key not in data]
+            if missing:
+                missing_cols = ", ".join(missing)
+                raise ValueError(
+                    "Primary key values missing from data for merge: "
+                    f"{missing_cols}. Provide pk=... or include the key values in data."
+                )
+            pk = {key: data[key] for key in pkeys}
+        else:
+            pk = dict(pk)
+            for key, value in pk.items():
+                if key in data and data[key] != value:
+                    raise ValueError(
+                        f"Conflicting values for primary key '{key}' between data and pk arguments."
+                    )
 
-        # Create a merged dictionary for insert (data + primary key columns)
-        full_data = {}
-        full_data.update(data)
-        full_data.update(pk)
+        insert_data = dict(data)
+        insert_data.update(pk)
 
-        sql, vals = cls.insert(table, full_data)
-        sql = [sql]
-        vals = list(vals)  # Convert to a mutable list
+        update_data = {k: v for k, v in data.items() if k not in pk}
 
-        if on_conflict_do_nothing != on_conflict_update:
-            sql.append("ON CONFLICT")
-            sql.append("(")
-            sql.append(",".join(pk.keys()))
-            sql.append(")")
-            sql.append("DO")
-            if on_conflict_do_nothing:
-                sql.append("NOTHING")
-            elif on_conflict_update:
-                # Call update() with excluded=True to produce the SET clause for the upsert.
-                sql_update, vals_update = cls.update(tx, table, data, pk, excluded=True)
-                sql.append(sql_update)
-                # Use list.extend to add the update values to vals.
-                vals.extend(vals_update)
-        else:
+        if not update_data and on_conflict_update:
+            # Nothing to update, fall back to a no-op on conflict resolution.
+            on_conflict_do_nothing = True
+            on_conflict_update = False
+
+        if on_conflict_do_nothing == on_conflict_update:
             raise Exception(
                 "Update on conflict must have one and only one option to complete on conflict."
             )
 
+        sql, vals = cls.insert(table, insert_data)
+        sql = [sql]
+        vals = list(vals)  # Convert to a mutable list
+
+        sql.append("ON CONFLICT")
+        conflict_columns = [TableHelper.quote(column) for column in pk.keys()]
+        sql.append("(")
+        sql.append(", ".join(conflict_columns))
+        sql.append(")")
+        sql.append("DO")
+        if on_conflict_do_nothing:
+            sql.append("NOTHING")
+        elif on_conflict_update:
+            sql_update, vals_update = cls.update(
+                tx, table, update_data, pk, excluded=True
+            )
+            sql.append(sql_update)
+            vals.extend(vals_update)
+
         import sqlparse
 
         final_sql = sqlparse.format(" ".join(sql), reindent=True, keyword_case="upper")
         return final_sql, tuple(vals)
 
+    @classmethod
+    def insnx(cls, tx, table, data, where=None):
+        """Insert only when the supplied predicate finds no existing row."""
+        if not table:
+            raise ValueError("Table name is required.")
+        if not isinstance(data, Mapping) or not data:
+            raise ValueError("data must be a non-empty mapping of column-value pairs.")
+
+        # Helper used for quoting and foreign key resolution
+        th = TableHelper(tx, table)
+        quote_helper = TableHelper(None, table)
+
+        columns_sql = []
+        select_parts = []
+        vals = []
+
+        for key, val in data.items():
+            columns_sql.append(quote_helper.quote(key.lower()))
+            if isinstance(val, str) and len(val) > 2 and val.startswith("@@") and val[2:]:
+                select_parts.append(val[2:])
+            else:
+                select_parts.append("%s")
+                vals.append(val)
+
+        if not select_parts:
+            raise ValueError("At least one column is required for insert.")
+
+        if where is None:
+            if tx is None:
+                raise ValueError(
+                    "A transaction context is required when deriving WHERE from primary keys."
+                )
+            pk_cols = tx.table(table).primary_keys()
+            if not pk_cols:
+                raise ValueError("Primary key required to derive WHERE clause.")
+            missing = [pk for pk in pk_cols if pk not in data]
+            if missing:
+                raise ValueError(
+                    "Missing primary key value(s) for insert condition: " + ", ".join(missing)
+                )
+            where = {pk: data[pk] for pk in pk_cols}
+
+        where_clauses = []
+        where_vals = []
+
+        if isinstance(where, Mapping):
+            compiled = []
+            for key, val in where.items():
+                compiled.append(th.make_predicate(key, val))
+            where = compiled
+
+        if isinstance(where, str):
+            where_clauses.append(where)
+        else:
+            try:
+                for predicate, value in where:
+                    where_clauses.append(predicate)
+                    if value is None:
+                        continue
+                    if isinstance(value, tuple):
+                        where_vals.extend(value)
+                    else:
+                        where_vals.append(value)
+            except (TypeError, ValueError) as exc:
+                raise ValueError(
+                    "Invalid WHERE clause format. Expected mapping, SQL string, or iterable of predicate/value pairs."
+                ) from exc
+
+        vals.extend(where_vals)
+
+        exists_sql = [
+            "SELECT 1 FROM",
+            TableHelper.quote(table),
+        ]
+        if where_clauses:
+            exists_sql.append("WHERE " + " AND ".join(where_clauses))
+
+        sql_parts = [
+            "INSERT INTO",
+            TableHelper.quote(table),
+            f"({','.join(columns_sql)})",
+            "SELECT",
+            ", ".join(select_parts),
+            "WHERE NOT EXISTS (",
+            " ".join(exists_sql),
+            ")",
+        ]
+
+        final_sql = sqlparse.format(" ".join(sql_parts), reindent=True, keyword_case="upper")
+        return final_sql, tuple(vals)
+
+    insert_if_not_exists = insnx
+
     @classmethod
     def version(cls):
         return "select version()", tuple()
@@ -614,14 +801,56 @@ class SQL:
     def drop_database(cls, name):
         return f"drop database if exists {name}", tuple()
 
+    @staticmethod
+    def _sys_modified_function_sql(schema_identifier):
+        return f"""
+            CREATE OR REPLACE FUNCTION {schema_identifier}.on_sys_modified()
+              RETURNS TRIGGER AS
+            $BODY$
+            BEGIN
+                IF (TG_OP = 'INSERT') THEN
+                    NEW.sys_table := TG_TABLE_NAME;
+                    NEW.sys_created := transaction_timestamp();
+                    NEW.sys_modified := transaction_timestamp();
+                    NEW.sys_modified_row := clock_timestamp();
+                    NEW.sys_modified_count := 0;
+                ELSIF (TG_OP = 'UPDATE') THEN
+                    NEW.sys_table := TG_TABLE_NAME;
+                    NEW.sys_created := OLD.sys_created;
+                    NEW.sys_modified_count := COALESCE(OLD.sys_modified_count, 0);
+                    IF ROW(NEW.*) IS DISTINCT FROM ROW(OLD.*) THEN
+                        IF OLD.sys_dirty IS TRUE AND NEW.sys_dirty IS FALSE THEN
+                            NEW.sys_dirty := FALSE;
+                        ELSE
+                            NEW.sys_dirty := TRUE;
+                        END IF;
+                        NEW.sys_modified := transaction_timestamp();
+                        NEW.sys_modified_row := clock_timestamp();
+                        NEW.sys_modified_count := COALESCE(OLD.sys_modified_count, 0) + 1;
+                    END IF;
+                END IF;
+                RETURN NEW;
+            END;
+            $BODY$
+              LANGUAGE plpgsql VOLATILE
+              COST 100;
+        """
+
     @classmethod
     def create_table(cls, name, columns={}, drop=False):
         if "." in name:
             fqtn = TableHelper.quote(name)
         else:
             fqtn = f"public.{TableHelper.quote(name)}"
+
         schema, table = fqtn.split(".")
-        name = fqtn.replace(".", "_")
+        schema_unquoted = schema.replace('"', "")
+        table_unquoted = table.replace('"', "")
+        trigger_name = (
+            f"on_update_row_{schema_unquoted}_{table_unquoted}".replace(".", "_")
+        )
+        trigger_identifier = TableHelper.quote(trigger_name)
+        schema_identifier = TableHelper.quote(schema_unquoted)
         sql = []
         if drop:
             sql.append(cls.drop_table(fqtn)[0])
@@ -629,39 +858,25 @@ class SQL:
             f"""
             CREATE TABLE {fqtn} (
               sys_id BIGSERIAL PRIMARY KEY,
-              sys_modified TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
               sys_created TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-              sys_modified_by TEXT,
+              sys_modified TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+              sys_modified_by TEXT NOT NULL DEFAULT 'SYSTEM',
+              sys_modified_row TIMESTAMP NOT NULL DEFAULT CLOCK_TIMESTAMP(),
+              sys_modified_count INTEGER NOT NULL DEFAULT 0,
               sys_dirty BOOLEAN NOT NULL DEFAULT FALSE,
-              sys_table TEXT,
+              sys_table TEXT NOT NULL,
               description TEXT
             );
 
             SELECT SETVAL(PG_GET_SERIAL_SEQUENCE('{fqtn}', 'sys_id'),1000,TRUE);
 
-            CREATE OR REPLACE FUNCTION {schema}.on_sys_modified()
-              RETURNS TRIGGER AS
-            $BODY$
-                        BEGIN
-                        -- update sys_modified on each insert/update.
-                        NEW.sys_modified := now();
-                        if (TG_OP = 'INSERT') THEN
-                            NEW.sys_created :=now();
-                        ELSEIF (TG_OP = 'UDPATE') THEN
-                         -- Do not allow sys_created to be modified.
-                            NEW.sys_created := OLD.sys_created;
-                        END IF;
-                        -- Insert table name to row
-                        NEW.sys_table := TG_TABLE_NAME;
-                        RETURN NEW;
-                        END;
-            $BODY$
-              LANGUAGE plpgsql VOLATILE
-              COST 100;
+            {cls._sys_modified_function_sql(schema_identifier)}
+
+            DROP TRIGGER IF EXISTS {trigger_identifier} ON {fqtn};
 
-            CREATE TRIGGER on_update_row_{fqtn.replace('.', '_')}
+            CREATE TRIGGER {trigger_identifier}
             BEFORE INSERT OR UPDATE ON {fqtn}
-            FOR EACH ROW EXECUTE PROCEDURE {schema}.on_sys_modified();
+            FOR EACH ROW EXECUTE PROCEDURE {schema_identifier}.on_sys_modified();
 
         """
         )
@@ -677,6 +892,145 @@ class SQL:
         sql = sqlparse.format(" ".join(sql), reindent=True, keyword_case="upper")
         return sql, tuple()
 
+    @classmethod
+    def ensure_system_columns(cls, name, existing_columns=None, force=False):
+        """Ensure all Velocity system columns and triggers exist for the table."""
+        existing_columns = {
+            col.lower() for col in (existing_columns or [])
+        }
+
+        required_columns = [
+            "sys_id",
+            "sys_created",
+            "sys_modified",
+            "sys_modified_by",
+            "sys_modified_row",
+            "sys_modified_count",
+            "sys_dirty",
+            "sys_table",
+            "description",
+        ]
+
+        missing_columns = [
+            column for column in required_columns if column not in existing_columns
+        ]
+
+        if not missing_columns and not force:
+            return None
+
+        if "." in name:
+            schema_name, table_name = name.split(".", 1)
+        else:
+            schema_name = cls.default_schema
+            table_name = name
+
+        schema_unquoted = schema_name.replace('"', "")
+        table_unquoted = table_name.replace('"', "")
+
+        schema_identifier = TableHelper.quote(schema_unquoted)
+        table_identifier = TableHelper.quote(table_unquoted)
+        fqtn = f"{schema_identifier}.{table_identifier}"
+
+        trigger_name = (
+            f"on_update_row_{schema_unquoted}_{table_unquoted}".replace(".", "_")
+        )
+        trigger_identifier = TableHelper.quote(trigger_name)
+
+        statements = []
+        added_columns = set()
+        columns_after = set(existing_columns)
+
+        if "sys_id" in missing_columns:
+            statements.append(
+                f"ALTER TABLE {fqtn} ADD COLUMN {TableHelper.quote('sys_id')} BIGSERIAL PRIMARY KEY;"
+            )
+            added_columns.add("sys_id")
+            columns_after.add("sys_id")
+
+        column_definitions = {
+            "sys_created": "TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP",
+            "sys_modified": "TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP",
+            "sys_modified_by": "TEXT NOT NULL DEFAULT 'SYSTEM'",
+            "sys_modified_row": "TIMESTAMP NOT NULL DEFAULT CLOCK_TIMESTAMP()",
+            "sys_modified_count": "INTEGER NOT NULL DEFAULT 0",
+            "sys_dirty": "BOOLEAN NOT NULL DEFAULT FALSE",
+            "sys_table": "TEXT",
+            "description": "TEXT",
+        }
+
+        for column, definition in column_definitions.items():
+            if column in missing_columns:
+                statements.append(
+                    f"ALTER TABLE {fqtn} ADD COLUMN {TableHelper.quote(column)} {definition};"
+                )
+                added_columns.add(column)
+                columns_after.add(column)
+
+        default_map = {
+            "sys_created": "CURRENT_TIMESTAMP",
+            "sys_modified": "CURRENT_TIMESTAMP",
+            "sys_modified_by": "'SYSTEM'",
+            "sys_modified_row": "CLOCK_TIMESTAMP()",
+            "sys_modified_count": "0",
+            "sys_dirty": "FALSE",
+        }
+
+        for column, default_sql in default_map.items():
+            if column in columns_after and (force or column in added_columns):
+                quoted_column = TableHelper.quote(column)
+                statements.append(
+                    f"UPDATE {fqtn} SET {quoted_column} = {default_sql} WHERE {quoted_column} IS NULL;"
+                )
+                statements.append(
+                    f"ALTER TABLE {fqtn} ALTER COLUMN {quoted_column} SET DEFAULT {default_sql};"
+                )
+
+        if "sys_table" in columns_after and (force or "sys_table" in added_columns):
+            quoted_column = TableHelper.quote("sys_table")
+            table_literal = table_unquoted.replace("'", "''")
+            statements.append(
+                f"UPDATE {fqtn} SET {quoted_column} = COALESCE({quoted_column}, '{table_literal}') WHERE {quoted_column} IS NULL;"
+            )
+
+        not_null_columns = {
+            "sys_created",
+            "sys_modified",
+            "sys_modified_by",
+            "sys_modified_row",
+            "sys_modified_count",
+            "sys_dirty",
+            "sys_table",
+        }
+
+        for column in not_null_columns:
+            if column in columns_after and (force or column in added_columns):
+                statements.append(
+                    f"ALTER TABLE {fqtn} ALTER COLUMN {TableHelper.quote(column)} SET NOT NULL;"
+                )
+
+        reset_trigger = force or bool(added_columns)
+
+        if reset_trigger:
+            statements.append(
+                f"DROP TRIGGER IF EXISTS {trigger_identifier} ON {fqtn};"
+            )
+            statements.append(cls._sys_modified_function_sql(schema_identifier))
+            statements.append(
+                f"""
+                CREATE TRIGGER {trigger_identifier}
+                BEFORE INSERT OR UPDATE ON {fqtn}
+                FOR EACH ROW EXECUTE PROCEDURE {schema_identifier}.on_sys_modified();
+            """
+            )
+
+        if not statements:
+            return None
+
+        sql = sqlparse.format(
+            " ".join(statements), reindent=True, keyword_case="upper"
+        )
+        return sql, tuple()
+
     @classmethod
     def drop_table(cls, name):
         return f"drop table if exists {TableHelper.quote(name)} cascade;", tuple()
@@ -966,7 +1320,7 @@ class SQL:
             columns = TableHelper.quote(columns)
         sql = ["DROP"]
         sql.append("INDEX IF EXISTS")
-        tablename = TableHelper.quote(table)
+        _tablename = TableHelper.quote(table)
         if not name:
             name = re.sub(
                 r"\([^)]*\)",
@@ -1136,9 +1490,9 @@ class SQL:
     @classmethod
     def missing(cls, tx, table, list, column="SYS_ID", where=None):
         sql = [
-            f"SELECT * FROM",
+            "SELECT * FROM",
             f"UNNEST('{{{','.join([str(x) for x in list])}}}'::int[]) id",
-            f"EXCEPT ALL",
+            "EXCEPT ALL",
             f"SELECT {column} FROM {table}",
         ]
         vals = []