feat(schema): implement schema-diff support and DataType refactoring for PostgreSQL backend (#46)

* feat(types): implement PostgreSQL DataType subclasses and type support mixin

- Add ~45 PostgreSQL-specific DataType subclasses in expression/types.py
- Add PostgresTypeFormatSupportMixin with TypeFormattingSupport + TypeParsingSupport
- Integrate type support into PostgresDialect
- Update exports in __init__.py, expression/__init__.py, mixins/__init__.py, mixins/types/__init__.py

* refactor(types): add __eq__/__hash__, remove synonyms, add CharacterVaryingType

- Replace _type_params() with __eq__/__hash__ in PostgresBitType,
  PostgresVarBitType, PostgresVectorType
- Remove synonyms() from PostgresSmallSerialType, PostgresSerialType,
  PostgresBigSerialType
- Add PostgresCharacterVaryingType(VarCharType) for CHARACTER VARYING(n)
- Register new type in data_type_formatting mixin
- Clean up unused imports (ClassVar, Set, Tuple)

* feat(schema): add parsed_data_type to PostgreSQL _parse_columns

Call DataType.parse_data_type_str(dialect, data_type) when
constructing ColumnInfo so that introspection results carry
structured DataType instances for schema comparison.

* feat(types): add synonyms to PostgreSQL types

- PostgresSerialType ↔ IntegerType/SerialType
- PostgresSmallSerialType ↔ SmallIntType/SmallSerialType
- PostgresBigSerialType ↔ BigIntType/BigSerialType
- PostgresCharacterVaryingType ↔ VarCharType

* feat(types): add synonyms to PostgresByteaType

PostgresByteaType ↔ BlobType for cross-backend schema comparison.

* refactor(types): inherit DDLTypeMixin in Postgres type formatting

* refactor(types): update to DDLTypeSupport protocol

* refactor(types): use @DDLTypeMixin.handles, remove format_data_type override

- Add @DDLTypeMixin.handles decorators to all 56 formatter methods
- Remove custom format_data_type() dispatch and supports_data_types() list
- Move Postgres type imports from TYPE_CHECKING to runtime

* fix(types): rewrite Postgres core type formatters, fix missing PostgresTypeFormatSupportMixin base

- Replace _default_sql() calls with explicit PostgreSQL SQL strings
  for all 18 core type handlers (SmallIntType→SMALLINT, etc.)
- Add PostgresTypeFormatSupportMixin as base of PostgresDialect
  (was imported but never used as base, causing format_data_type
  to resolve to protocol stub and return None)
- Create test_core_type_mappings.py with 15 tests for core type→SQL
  rendering via PostgreSQL dialect

* feat(postgres): implement array type support

- Add PostgresArrayType parameterised container type (element_type, dimensions)
- Add format_data_type_array handler that recursively formats element types
- Update parse_type to detect ARRAY keyword and [] suffix before standard dispatch
- Add 25 tests covering core type mappings and array rendering/parsing

* refactor(postgres): use core ArrayType, keep PostgresArrayType as alias

- PostgresArrayType is now just 'PostgresArrayType = ArrayType'
- Update handler registration to use core ArrayType
- Update parse_type to return ArrayType directly
- Add test for is_element_type_equivalent

* feat(postgres): add element type validation and PostgresArrayType subclass

- format_data_type_array validates element_type is in _type_formatters
- PostgresArrayType is now a proper subclass with is_equivalent ignoring
  dimensions (PG normalises multi-dim arrays to 1-D internally)
- parse_type always creates PostgresArrayType with dimensions=1
- Update tests for new PostgresArrayType subclass and PG array semantics

* feat(schema): add PostgresSchemaDiffer

Column order has no semantic meaning in PostgreSQL; array dimension
equivalence is handled by PostgresArrayType.is_equivalent().

* feat(schema): add schema-diff examples and refactor for PostgreSQL backend

- Add 6 schema-diff example scripts: table_changes, column_order_irrelevant, postgres10_identity, array_type_diff, index_type_diff, serialization_roundtrip
- All DDL uses expression objects, call introspect_and_adapt() after connect
- Refactor format_column_definition to use col_def.data_type.to_sql() and add identity dialect_options support
- Update existing DDL examples to use expression API (table param, QueryExpression for verification)

* refactor(types): remove _default_sql(), make format_data_type return Tuple[str, tuple]

- Delete all _default_sql() methods from Postgres expression types
- Change all PostgresTypeFormatSupportMixin formatters to return Tuple[str, tuple]
- Inline _default_sql() logic directly into each format_data_type_* method
- Unpack format_data_type() call in array formatter

* style(types): add complete type annotations to all format_data_type_* methods

* feat(examples): strengthen serialization roundtrip with table data assertions

* fix(tests): replace string data_type with DataType instances across 22 test files

ColumnDefinition now validates that data_type must be a DataType
instance. Replace all string data_type values (SERIAL, TEXT, INTEGER,
etc.) with proper instance references.

Also add PostgresCitextType, PostgresCubeType, PostgresLtreeType,
PostgresRasterType missing extension DataType subclasses.

Update security injection tests to verify TypeError at construction
time instead of ValueError at format time.

* docs: add changelog fragment for PR #46

* fix(tests): replace positional string data_type with DataType instances in 6 more files

* fix(types): register PostgresCitextType, PostgresCubeType, PostgresLtreeType, PostgresRasterType formatters

* fix: restore PostgresCidrType import accidentally removed in type formatter registration

Author: vistart

changelog.d/46.added.md

@@ -0,0 +1 @@
+Added PostgreSQL-specific DataType subclasses and schema-diff support with `PostgresSchemaDiffer` for accurate schema introspection and column comparison.

src/rhosocial/activerecord/backend/impl/postgres/__init__.py

@@ -23,6 +23,55 @@
 from .dialect import PostgresDialect
 from .transaction import PostgresTransactionManager, AsyncPostgresTransactionManager
 from .types import PostgresEnumType
+from .expression.types import (
+    PostgresBigSerialType,
+    PostgresBitType,
+    PostgresBoxType,
+    PostgresByteaType,
+    PostgresCIDType,
+    PostgresCircleType,
+    PostgresDateMultirangeType,
+    PostgresDateRangeType,
+    PostgresGeographyType,
+    PostgresGeometryType,
+    PostgresHstoreType,
+    PostgresInetType,
+    PostgresInt4MultirangeType,
+    PostgresInt4RangeType,
+    PostgresInt8MultirangeType,
+    PostgresInt8RangeType,
+    PostgresJsonPathType,
+    PostgresLineSegmentType,
+    PostgresLineType,
+    PostgresMacAddr8Type,
+    PostgresMacAddrType,
+    PostgresMoneyType,
+    PostgresNumMultirangeType,
+    PostgresNumRangeType,
+    PostgresOIDType,
+    PostgresPathType,
+    PostgresPgLSNType,
+    PostgresPointType,
+    PostgresPolygonType,
+    PostgresRegClassType,
+    PostgresRegTypeType,
+    PostgresSerialType,
+    PostgresSmallSerialType,
+    PostgresTIDType,
+    PostgresTSQueryType,
+    PostgresTSVectorType,
+    PostgresTsMultirangeType,
+    PostgresTsRangeType,
+    PostgresTsTzMultirangeType,
+    PostgresTsTzRangeType,
+    PostgresUUIDType,
+    PostgresVarBitType,
+    PostgresVectorType,
+    PostgresXID8Type,
+    PostgresXIDType,
+    PostgresXMLType,
+    PostgresCidrType,
+)
 from .explain import PostgresExplainResult, PostgresExplainPlanLine
 from .expression.ddl import (
     PostgresCreateEnumTypeExpression,
@@ -505,4 +554,52 @@
     # hstore functions - Subscript
     "hstore_subscript_get",
     "hstore_subscript_set",
+    # PostgreSQL DataType subclasses for DDL
+    "PostgresBigSerialType",
+    "PostgresBitType",
+    "PostgresBoxType",
+    "PostgresByteaType",
+    "PostgresCIDType",
+    "PostgresCircleType",
+    "PostgresDateMultirangeType",
+    "PostgresDateRangeType",
+    "PostgresGeographyType",
+    "PostgresGeometryType",
+    "PostgresHstoreType",
+    "PostgresInetType",
+    "PostgresInt4MultirangeType",
+    "PostgresInt4RangeType",
+    "PostgresInt8MultirangeType",
+    "PostgresInt8RangeType",
+    "PostgresJsonPathType",
+    "PostgresLineSegmentType",
+    "PostgresLineType",
+    "PostgresMacAddr8Type",
+    "PostgresMacAddrType",
+    "PostgresMoneyType",
+    "PostgresNumMultirangeType",
+    "PostgresNumRangeType",
+    "PostgresOIDType",
+    "PostgresPathType",
+    "PostgresPgLSNType",
+    "PostgresPointType",
+    "PostgresPolygonType",
+    "PostgresRegClassType",
+    "PostgresRegTypeType",
+    "PostgresSerialType",
+    "PostgresSmallSerialType",
+    "PostgresTIDType",
+    "PostgresTSQueryType",
+    "PostgresTSVectorType",
+    "PostgresTsMultirangeType",
+    "PostgresTsRangeType",
+    "PostgresTsTzMultirangeType",
+    "PostgresTsTzRangeType",
+    "PostgresUUIDType",
+    "PostgresVarBitType",
+    "PostgresVectorType",
+    "PostgresXID8Type",
+    "PostgresXIDType",
+    "PostgresXMLType",
+    "PostgresCidrType",
 ]

src/rhosocial/activerecord/backend/impl/postgres/dialect.py

@@ -90,6 +90,7 @@
     IntrospectionSupport,
     TransactionControlSupport,
     SQLFunctionSupport,
+    DDLTypeSupport,
 )
 from .mixins import (
     PostgresExtensionMixin,
@@ -169,6 +170,7 @@
     PostgresRangeTypeMixin,
     PostgresJSONBEnhancedMixin,
     PostgresArrayEnhancedMixin,
+    PostgresTypeFormatSupportMixin,
     # DDL/DML operation mixins (new)
     PostgresExtendedStatisticsMixin,
     PostgresStoredProcedureMixin,
@@ -400,6 +402,7 @@ class PostgresDialect(
     PostgresFullTextSearchMixin,
     PostgresRangeTypeMixin,
     PostgresArrayEnhancedMixin,
+    PostgresTypeFormatSupportMixin,
     # DDL/DML operation mixins (new)
     PostgresExtendedStatisticsMixin,
     PostgresStoredProcedureMixin,
@@ -524,6 +527,8 @@ class PostgresDialect(
     PostgresRangeTypeSupport,
     PostgresJSONBEnhancedSupport,
     PostgresArrayEnhancedSupport,
+    # DataType Support Protocol
+    DDLTypeSupport,
     # New feature protocols
     PostgresParallelQuerySupport,
     PostgresStoredProcedureSupport,

src/rhosocial/activerecord/backend/impl/postgres/examples/conftest.py

@@ -416,4 +416,46 @@
         'max_version': '18',
         'note': 'Requires superuser or pg_read_server_files role; only available in PG15+ docker images',
     },
+    'schema_diff/table_changes.py': {
+        'title': 'Schema Diff — Table Add/Remove',
+        'dialect_protocols': [],
+        'priority': 10,
+        'min_version': '9',
+        'max_version': '18',
+    },
+    'schema_diff/column_order_irrelevant.py': {
+        'title': 'Schema Diff — Column Order Is Ignored',
+        'dialect_protocols': [],
+        'priority': 10,
+        'min_version': '9',
+        'max_version': '18',
+    },
+    'schema_diff/postgres10_identity.py': {
+        'title': 'Schema Diff — PG9 SERIAL vs PG10+ IDENTITY',
+        'dialect_protocols': [],
+        'priority': 10,
+        'min_version': '9',
+        'max_version': '18',
+    },
+    'schema_diff/array_type_diff.py': {
+        'title': 'Schema Diff — Array Type Dimension Changes',
+        'dialect_protocols': [],
+        'priority': 10,
+        'min_version': '9',
+        'max_version': '18',
+    },
+    'schema_diff/index_type_diff.py': {
+        'title': 'Schema Diff — PostgreSQL Index Type Switches',
+        'dialect_protocols': [],
+        'priority': 10,
+        'min_version': '9',
+        'max_version': '18',
+    },
+    'schema_diff/serialization_roundtrip.py': {
+        'title': 'Schema Diff — Snapshot Serialization Roundtrip',
+        'dialect_protocols': [],
+        'priority': 10,
+        'min_version': '9',
+        'max_version': '18',
+    },
 }

src/rhosocial/activerecord/backend/impl/postgres/examples/ddl/alter_table.py

@@ -38,7 +38,7 @@
 
 drop_table = DropTableExpression(
     dialect=dialect,
-    table_name='users',
+    table='users',
     if_exists=True,
     cascade=True,
 )
@@ -47,7 +47,7 @@
 
 create_table = CreateTableExpression(
     dialect=dialect,
-    table_name='users',
+    table='users',
     columns=[
         ColumnDefinition(
             'id',
@@ -148,13 +148,23 @@
 print("Column renamed successfully")
 
 # Verify table structure
-options = ExecutionOptions(stmt_type=StatementType.DQL)
-result = backend.execute(
-    "SELECT column_name, data_type, is_nullable "
-    "FROM information_schema.columns "
-    "WHERE table_name = 'users' ORDER BY ordinal_position",
-    options=options
+from rhosocial.activerecord.backend.expression import QueryExpression, TableExpression
+from rhosocial.activerecord.backend.expression.core import WildcardExpression, Column
+from rhosocial.activerecord.backend.expression.query_parts import OrderByClause
+
+verify_expr = QueryExpression(
+    dialect=dialect,
+    select=[
+        Column(dialect, 'column_name'),
+        Column(dialect, 'data_type'),
+        Column(dialect, 'is_nullable'),
+    ],
+    from_=TableExpression(dialect, 'columns', schema_name='information_schema'),
+    where=Column(dialect, 'table_name') == Literal(dialect, 'users'),
+    order_by=OrderByClause(dialect, [Column(dialect, 'ordinal_position')]),
 )
+options = ExecutionOptions(stmt_type=StatementType.DQL)
+result = backend.execute(*verify_expr.to_sql(), options=options)
 print("Table structure after alterations:")
 for row in result.data or []:
     print(f" {row}")

src/rhosocial/activerecord/backend/impl/postgres/examples/ddl/create_index.py

@@ -33,7 +33,7 @@
 
 drop_table = DropTableExpression(
     dialect=dialect,
-    table_name='products',
+    table='products',
     if_exists=True,
     cascade=True,
 )
@@ -42,7 +42,7 @@
 
 create_table = CreateTableExpression(
     dialect=dialect,
-    table_name='products',
+    table='products',
     columns=[
         ColumnDefinition(
             'id',
@@ -83,11 +83,17 @@
 print("Index created: idx_category_price")
 
 # Verify index creation
-options = ExecutionOptions(stmt_type=StatementType.DQL)
-verify_result = backend.execute(
-    "SELECT indexname FROM pg_indexes WHERE indexname = 'idx_category_price'",
-    options=options
+from rhosocial.activerecord.backend.expression import QueryExpression, TableExpression
+from rhosocial.activerecord.backend.expression.core import Column, Literal
+
+verify_expr = QueryExpression(
+    dialect=dialect,
+    select=[Column(dialect, 'indexname')],
+    from_=TableExpression(dialect, 'pg_indexes'),
+    where=Column(dialect, 'indexname') == Literal(dialect, 'idx_category_price'),
 )
+options = ExecutionOptions(stmt_type=StatementType.DQL)
+verify_result = backend.execute(*verify_expr.to_sql(), options=options)
 print(f"Index info: {verify_result.data}")
 
 # ============================================================