feat: parallel testing infrastructure and PostgreSQL backend improvements (#55)

* feat: parallel scenario tests with per-worker database pooling

Wire the testsuite database pool for postgres: register the pool reset
handler, make scenario resolution pool-aware, install core and testsuite
from the feature/parallel-testing branches, and run tests with -n 8.

* fix(test): load testsuite conftest plugin and guard --scenarios registration

Without -p rhosocial.activerecord.testsuite.conftest the pooling hooks never
run, so configure_pool_size stays 0 and every xdist worker falls back to the
shared scenario database, racing on schema DDL. Load the plugin and guard the
backend's own --scenarios option so both conftests coexist.

* fix(test): apply pooled database names in backend and connection feature conftests

* fix(test): apply pooled database names in worker connection params

* fix(test): check for simultaneous double-hold instead of id uniqueness

* fix(test): use a non-empty LSN range for pg_get_wal_records_info

* feat: CLI async unification, --ssl param; postgres backend fixes

* feat(postgres): add named expression/procedure example modules

- Add named_expressions order_expressions (import-safe, prepare_orders_demo helper)
- Add named_procedures order_workflow (OrderProcessingProcedure, max_concurrency=1
  for psycopg single-connection concurrency limit)
- Update bash scripts to reference real module paths instead of placeholders
  and full module paths for --list (package path returns no entries)

* test(expression): add serialization round-trip coverage for PostgreSQL expressions

* fix(dialect): translate is_auto_increment to GENERATED BY DEFAULT AS IDENTITY

ColumnConstraint(is_auto_increment=True) on PRIMARY_KEY was silently ignored,
producing INTEGER PRIMARY KEY without auto-increment. PostgreSQL requires
explicit GENERATED BY DEFAULT AS IDENTITY for auto-increment columns.
The existing dialect_options['identity'] path is unaffected.

* test: add is_auto_increment/DDL regression tests

Dialect-level tests (no DB needed) verifying:
1. is_auto_increment=True produces correct auto-increment DDL keyword
2. All standard types (Integer/Text/Boolean/VarChar/Timestamp) compile
3. BooleanType + DEFAULT True is accepted
4. TimestampType maps to correct backend-specific type

Prevents recurrence of bugs found in rbac cross-backend testing.

* fix(config): declare missing autocommit field on PostgresConnectionConfig

The backend read config.autocommit (requires_manual_commit and the
auto-commit handlers in sync/async backends) to decide whether an
explicit COMMIT is needed outside managed transactions, but the field
did not exist on the dataclass, so passing autocommit=True raised a
TypeError and the option was effectively dead. All other backends
(mysql, sqlserver, clickhouse, snowflake, firebird) already declare it.

Replace the defensive getattr() fallbacks with direct attribute access
and add unit tests covering the default value, explicit assignment,
conninfo exclusion, and requires_manual_commit() for both backends.

* test: cover column qualifier resolution under JOINs

Regression tests for qualifier generation vs FROM context: plain field
accessors, mixed/partial aliases, prebuilt-predicate reuse across
contexts, explicit-alias joins, and an xfail sentinel documenting the
accepted dynamic __table_name__ drift limitation. Companion to the
python-activerecord fix that stops forcing table-name aliases on JOIN
ranges.

* test: cover dynamic table/schema names as supported usage

Replace the R4 xfail sentinel with positive tests for the documented
contract: after changing __table_name__ / __schema_name__, expressions
built through field proxies pick up the new identity, and full DQL stays
consistent across FROM / WHERE / SELECT. Seed an archive table and a
second tenant-style schema so both switch directions assert real data.

* feat(test): provide cross-schema fixtures for testsuite

Implements the optional setup_schema_fixtures capability: provisions
ar_crm / ar_shop schemas with customers and orders tables (sync + async
variants; DDL runs through a short-lived sync connection for async),
tracks created schemas, and drops them in cleanup_after_test. Declares
supports_schema() == True.

* feat(dialect): declare supports_schema capability and schema DDL tests

* fix(protocols): declare supports_schema and supports_schema_authorization in PostgresSchemaSupport

* test(provider): provision mixed default/non-default schema fixtures

* test(adapters): offline adapter round-trip coverage for all types

* docs: record stateflow cross-backend test issues (JSON/bool/RETURNING)

* fix(hstore): pass raw % operator to format_binary_operator to avoid double escaping

hstore_to_array_operator passed the already-escaped '%%' operator to
format_binary_operator, which escapes '%' again to '%%%%' (psycopg folds
to '%%' instead of the expected '%'). Pass the raw '%' so
format_binary_operator performs the single %->%% escape as the sole
collection point.

* fix(adapters): parse array literals on read for list fields in TEXT columns

PostgresListAdapter now parses JSON and PostgreSQL array literals via psycopg's
array loader when reading list fields stored in TEXT columns, fixing the
cross-backend round-trip exposed by stateflow tests.

* test: add format_binary_operator % escaping and hstore operator tests

* ci: update testsuite branch to release/v1.0.0.dev17

* ci: update rhosocial-activerecord branch to release/v1.0.0.dev30

* ci: update testsuite branch to release/v1.0.0.dev17

* feat(postgres): add pgvector vector_search function and expression type support

- Add vector_search.py function module with pgvector search capabilities
- Extend expression types with pgvector-related serialization
- Add data_type_formatting mixin improvements
- Add vector search and example compile test coverage

* test: add targeted coverage for low-coverage patch areas

- extend PostgresListAdapter string parsing tests (JSON + PG array literal)
- add HALFVEC/SPARSEVEC DDL format/parse and eq/hash coverage
- cover vector_search edge cases (ip similarity, index options, invalid metric)
- add _get_default_schema config-aware resolution tests for both introspection stacks
- cover backend autocommit handler branches (sync + async, True/False)
- add CLI --ssl mapping and --async flag tests
- add CLI blackbox tests for introspect/status --async

fix(cli): correct async introspect method names (remove _async suffix)

The _handle_introspect_async path called nonexistent list_tables_async,
list_views_async etc. Async introspector methods use the same names as
sync (no _async suffix). Fixes broken async introspect branch.

* fix(test): tolerate empty table list in introspect blackbox tests

CI runs against a fresh test_db where 'introspect tables' returns [],
so assert json.loads(out) (truthy) fails. Assert the parsed JSON is a
list instead, which holds whether or not tables exist.

* chore: add changelog fragment for PR #55

* docs: remove non-standard changelog fragment

The file name stateflow-cross-backend-issues.fixed.md does not follow
the <issue_number>.<type>.md convention. Its content was already
merged into the relevant fix commit.

Author: vistart

.github/workflows/test.yml

@@ -68,8 +68,8 @@ jobs:
 
       - name: Install activerecord and testsuite
         run: |
-          pip install rhosocial-activerecord==1.0.0.dev29
-          pip install rhosocial-activerecord-testsuite==1.0.0.dev16
+          pip install "rhosocial-activerecord @ git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17"
 
       - name: Create postgres scenario config
         run: |
@@ -279,8 +279,8 @@ jobs:
 
       - name: Install activerecord and testsuite
         run: |
-          pip install rhosocial-activerecord==1.0.0.dev29
-          pip install rhosocial-activerecord-testsuite==1.0.0.dev16
+          pip install "rhosocial-activerecord @ git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17"
 
       - name: Create postgres scenario config
         run: |
@@ -322,7 +322,7 @@ jobs:
       - name: Run tests
         run: |
           export PYTHONPATH=src:tests
-          python -m pytest tests/ --tb=short --scenario-parallel -n 2 --dist=loadgroup
+          python -m pytest tests/ --tb=short -n 8 --dist=loadgroup
 
   test:
     name: Python ${{ matrix.python-version }} / postgres ${{ matrix.postgres-version }}
@@ -391,8 +391,8 @@ jobs:
 
       - name: Install activerecord and testsuite
         run: |
-          pip install rhosocial-activerecord==1.0.0.dev29
-          pip install rhosocial-activerecord-testsuite==1.0.0.dev16
+          pip install "rhosocial-activerecord @ git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17"
 
       - name: Create postgres scenario config
         run: |
@@ -435,14 +435,14 @@ jobs:
         if: matrix.postgres-version != '18'
         run: |
           export PYTHONPATH=src:tests
-          python -m pytest tests/ --tb=short --scenario-parallel -n 2 --dist=loadgroup
+          python -m pytest tests/ --tb=short -n 8 --dist=loadgroup
 
       - name: Run tests with coverage (only for postgres 18)
         if: matrix.postgres-version == '18'
         run: |
           export PYTHONPATH=src:tests
           pip install codecov
-          python -m pytest tests/ --tb=short --scenario-parallel -n 2 --dist=loadgroup --cov=src --cov-report=xml
+          python -m pytest tests/ --tb=short -n 8 --dist=loadgroup --cov=src --cov-report=xml
 
       - name: Upload coverage to Codecov
         if: matrix.postgres-version == '18'
@@ -490,8 +490,8 @@ jobs:
 
       - name: Install activerecord and testsuite
         run: |
-          pip install rhosocial-activerecord==1.0.0.dev29
-          pip install rhosocial-activerecord-testsuite==1.0.0.dev16
+          pip install "rhosocial-activerecord @ git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@release/v1.0.0.dev17"
 
       - name: Create postgres scenario config
         run: |
@@ -522,4 +522,4 @@ jobs:
       - name: Run tests
         run: |
           export PYTHONPATH=src:tests
-          python -m pytest tests/ --tb=short --scenario-parallel -n 2 --dist=loadgroup
+          python -m pytest tests/ --tb=short -n 8 --dist=loadgroup

changelog.d/55.added.md

@@ -0,0 +1 @@
+Add parallel testing infrastructure and PostgreSQL backend improvements

pyproject.toml

@@ -79,7 +79,7 @@ rhosocial = ["**/*.pyi", "**/*.py"]
 
 [tool.pytest.ini_options]
 minversion = "7.0"
-addopts = "-ra -q"
+addopts = "-ra -q -p rhosocial.activerecord.testsuite.conftest"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 testpaths = [

src/rhosocial/activerecord/backend/impl/postgres/README.md

@@ -30,7 +30,7 @@ python -m rhosocial.activerecord.backend.impl.postgres [OPTIONAL_FLAGS] [YOUR_SQ
 | `--database`      | `POSTGRES_DATABASE` env var or _None_              | Database name to connect to.                                                                                                                                            |
 | `--user`          | `POSTGRES_USER` env var or `postgres`              | Database user.                                                                                                                                                          |
 | `--password`      | `POSTGRES_PASSWORD` env var or _empty string_      | Database password.                                                                                                                                                      |
-| `--use-async`     | _False_                                            | Use the asynchronous backend.                                                                                                                                           |
+| `--async`         | _False_                                            | Use the asynchronous backend.                                                                                                                                           |
 | `--output`        | `table` (if rich available) or `json` (fallback)    | Output format. Choices are `table` (rich formatted), `json`, `csv`, `tsv`.                                                                                             |
 | `--log-level`     | `INFO`                                             | Set the logging level (e.g., `DEBUG`, `INFO`).                                                                                                                        |
 | `--rich-ascii`    | _False_                                            | Use ASCII characters for table borders.                                                                                                                                 |

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

@@ -67,6 +67,8 @@
     PostgresUUIDType,
     PostgresVarBitType,
     PostgresVectorType,
+    PostgresHalfvecType,
+    PostgresSparsevecType,
     PostgresXID8Type,
     PostgresXIDType,
     PostgresXMLType,
@@ -598,6 +600,8 @@
     "PostgresUUIDType",
     "PostgresVarBitType",
     "PostgresVectorType",
+    "PostgresHalfvecType",
+    "PostgresSparsevecType",
     "PostgresXID8Type",
     "PostgresXIDType",
     "PostgresXMLType",

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

@@ -23,18 +23,18 @@ def _build_parser():
     return parser
 
 
-def parse_args():
+def parse_args(argv=None):
     """Parse command-line arguments.
 
     Provided for test compatibility. In production, main() is used instead.
     """
     parser = _build_parser()
-    return parser.parse_args()
+    return parser.parse_args(argv)
 
 
-def main():
+def main(argv=None):
     parser = _build_parser()
-    args = parser.parse_args()
+    args = parser.parse_args(argv)
 
     if args.command is None:
         cmd_list = ", ".join(f"'{c}'" for c in COMMAND_NAMES[:-1])

src/rhosocial/activerecord/backend/impl/postgres/adapters/base.py

@@ -18,21 +18,59 @@ class PostgresListAdapter(BaseSQLTypeAdapter):
     """
     Adapts Python list to PostgreSQL array types.
 
-    This adapter does not perform any conversion - psycopg handles
-    Python lists natively for PostgreSQL array types.
+    This adapter passes Python lists through to psycopg for native array
+    column support. On read, if the database returns a string (e.g. when
+    a list was stored in a TEXT column via psycopg array serialization),
+    it parses the value back using psycopg's own array loader — the exact
+    mirror of the ``ListDumper`` used on write — and falls back to JSON
+    for the portable ``["a","b"]`` representation.
     """
 
     def __init__(self):
         super().__init__()
         self._register_type(list, list)
 
     def _do_to_database(self, value: list, target_type: Type, options: Optional[Dict[str, Any]] = None) -> Any:
-        # psycopg handles list natively for PostgreSQL arrays
         return value
 
+    @staticmethod
+    def _parse_array_literal(value: str) -> list:
+        """Parse a PostgreSQL array literal using psycopg's array loader.
+
+        ``psycopg.types.array._load_text`` is the exact reverse of the
+        ``ListDumper`` that psycopg uses to serialize a Python list on
+        write, so the round-trip is symmetric and handles quoting,
+        backslash escaping, ``NULL`` elements and nested arrays correctly.
+        """
+        from psycopg.types.array import _load_text
+
+        class _TextElementLoader:
+            def load(self, data):
+                return data.decode("utf-8")
+
+        try:
+            return _load_text(value.encode("utf-8"), _TextElementLoader())
+        except Exception:
+            raise ValueError(f"Not a PostgreSQL array literal: {value!r}") from None
+
     def _do_from_database(self, value: Any, target_type: Type, options: Optional[Dict[str, Any]] = None) -> list:
         if isinstance(value, list):
             return value
+        if isinstance(value, str):
+            stripped = value.strip()
+            # Try JSON first (more portable format)
+            if stripped.startswith("["):
+                try:
+                    return json.loads(stripped)
+                except (json.JSONDecodeError, ValueError):
+                    pass
+            # Try PostgreSQL array literal
+            if stripped.startswith("{"):
+                try:
+                    return self._parse_array_literal(stripped)
+                except (ValueError, IndexError):
+                    pass
+            raise TypeError(f"Cannot convert str to list: {value!r}")
         raise TypeError(f"Cannot convert {type(value).__name__} to list")
 
     def to_database_batch(

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

@@ -644,7 +644,7 @@ async def _handle_auto_commit(self) -> None:
             # Check if we're not in an active transaction
             if not self.in_transaction:
                 # For PostgreSQL, if autocommit is disabled, we need to commit explicitly
-                if not getattr(self.config, "autocommit", False):
+                if not self.config.autocommit:
                     await self._connection.commit()
                     self.log(logging.DEBUG, "Auto-committed operation (not in active transaction)")
         except Exception as e:
@@ -658,7 +658,7 @@ async def _handle_auto_commit_if_needed(self) -> None:
         PostgreSQL respects the autocommit setting, but we also need to handle explicit commits.
         """
         if not self.in_transaction and self._connection:
-            if not getattr(self.config, "autocommit", False):
+            if not self.config.autocommit:
                 await self._connection.commit()
                 self.log(logging.DEBUG, "Auto-committed operation (not in active transaction)")
 

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

@@ -82,7 +82,7 @@ def threadsafety(self) -> int:
 
     def requires_manual_commit(self) -> bool:
         """Check if manual commit is required for this database."""
-        return not getattr(self.config, "autocommit", False)
+        return not self.config.autocommit
 
     def _register_postgres_adapters(self):
         """Register PostgreSQL-specific type adapters.

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

@@ -645,7 +645,7 @@ def _handle_auto_commit(self) -> None:
             # Check if we're not in an active transaction
             if not self.in_transaction:
                 # For PostgreSQL, if autocommit is disabled, we need to commit explicitly
-                if not getattr(self.config, "autocommit", False):
+                if not self.config.autocommit:
                     self._connection.commit()
                     self.log(logging.DEBUG, "Auto-committed operation (not in active transaction)")
         except Exception as e:
@@ -659,7 +659,7 @@ def _handle_auto_commit_if_needed(self) -> None:
         PostgreSQL respects the autocommit setting, but we also need to handle explicit commits.
         """
         if not self.in_transaction and self._connection:
-            if not getattr(self.config, "autocommit", False):
+            if not self.config.autocommit:
                 self._connection.commit()
                 self.log(logging.DEBUG, "Auto-committed operation (not in active transaction)")