[vistart]

Description

Adds PostgreSQL dialect support for datetime interval expressions and EXPLAIN-backed index usage verification.

This PR covers:

• PostgreSQL dialect formatting for datetime extraction (EXTRACT/DATE_PART), datetime truncation (DATE_TRUNC), datetime add/subtract with INTERVAL, and datetime diff (DATE_PART for difference).
• PostgreSQL-specific temporal expression factory implementations in backend.impl.postgres.functions.
• EXPLAIN example tests that validate datetime range predicates use expected indexes when temporal expressions appear in the SELECT list.
• Sync/async test parity for all datetime interval EXPLAIN scenarios.
• PostgreSQL planner-aware assertions: default planner may choose Seq Scan for small tables; tests use SET enable_seqscan = off to verify index availability.

Related to python-activerecord#99 (coordinated backend support for datetime interval feature).

Type of change

• feat: A new feature
• test: Adding missing tests or correcting existing tests (for the new feature)

Breaking Change

• Yes, for end-users (backward-incompatible API changes)
• Yes, for backend developers (internal architectural changes that may affect custom implementations)
• No breaking changes

Impact on End-Users:
No backward-incompatible changes are expected for typical end-user applications.

Impact on Backend Developers (Custom Implementations):
No existing formatter signatures were removed. Custom dialects can opt into the new temporal expression support by implementing the corresponding formatter methods.

Applicable rhosocial-activerecord Version Range:
>=1.0.0.dev15,<2.0.0

Related Repositories/Packages

Coordinated backend support has been added separately for:

• python-activerecord#99 (core expression system)

Testing

• I have added new tests to cover my changes.
• I have updated existing tests to reflect my changes.
• All existing tests pass for the targeted test scope.
• This change has been tested on PostgreSQL 12+.

Test Plan:

source .venv3.8/bin/activate
pytest tests/rhosocial/activerecord_postgres_test/feature/backend/test_postgres_datetime_interval_explain_examples.py -v
pytest tests/rhosocial/activerecord_postgres_test/feature/backend/postgres/test_postgres_datetime_interval_expressions.py -v
pytest tests/rhosocial/activerecord_postgres_test/feature/backend/test_backend_explain.py -v
deactivate

Results:

• 4 passed — PostgreSQL datetime interval EXPLAIN examples
• 46 passed — PostgreSQL datetime interval expression tests
• 216 passed — PostgreSQL backend explain tests

PostgreSQL test conclusions:

• The new datetime interval feature is exercised through the expression system using QueryExpression, Column, Literal, ComparisonPredicate, LogicalPredicate, OrderByClause, and temporal expression factories.
• Temporal expressions can participate in full SELECT queries while datetime range predicates remain index-friendly in the WHERE clause.
• PostgreSQL EXPLAIN results confirm that indexed datetime predicates produce efficient plans using idx_temporal_category_created, idx_temporal_created_at, or idx_temporal_started_ended indexes when the planner chooses to use them.
• Due to PostgreSQL's cost-based planner, tests verify index availability using SET enable_seqscan = off rather than forcing specific plan choices.
• Combining extract, date_trunc, date_add, date_sub, and date_diff in the SELECT list does not prevent the category + created_at indexed filter from being used.
• The queries are executed against real PostgreSQL tables, validating both generated SQL semantics and runtime results, including extracted year values, truncated month values, shifted timestamps, and 30-minute duration calculations.

Checklist

• My code follows the project's code style guidelines.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation (Docstrings, README.md, etc.).
• My changes generate no new warnings in the targeted test scope.
• I have added a Changelog fragment (changelog.d/<issue_number>.<type>.md).
• I have verified that my changes do not introduce SQL injection vulnerabilities.
• I have checked for potential performance regressions.

Additional Notes

The EXPLAIN example tests intentionally build verification queries through QueryExpression and predicate/expression objects rather than raw SQL strings, so they validate end-to-end expression semantics as well as backend-specific SQL generation.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.13%. Comparing base (42cd978) to head (7be4627).

Additional details and impacted files

@@                   Coverage Diff                    @@
##           release/v1.0.0.dev15      #42      +/-   ##
========================================================
+ Coverage                 71.09%   71.13%   +0.04%     
========================================================
  Files                       232      232              
  Lines                     10269    10284      +15     
  Branches                   1617     1619       +2     
========================================================
+ Hits                       7301     7316      +15     
  Misses                     2441     2441              
  Partials                    527      527              

Flag	Coverage Δ
postgres-18	71.13% <100.00%> (+0.04%)	⬆️
python-3.14	71.13% <100.00%> (+0.04%)	⬆️
unittests	71.13% <100.00%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud