[vistart]

Description

This PR aligns python-activerecord-clickhouse with the new semantic error taxonomy and execute-phase contract:

• Maps code 57 duplicate and 70 not-null conversion to IntegrityError, 159 timeout / 202 concurrency limit / 241 memory to transient OperationalError, 47/60/81/62 to QueryError, 497/516 auth to non-transient ConnectionError, 164 read-only to non-transient OperationalError.
• Fixes the ordering bug where OperationalError was swallowed by DatabaseError.
• Retries framework transient errors; auto-commit failures raise TransactionError; ClickHouse has no deadlock semantics.

Adds # (no issue)

Type of change

• feat: A new feature
• test: Adding missing tests or correcting existing tests (for the new feature)
• docs: Documentation only changes (if related to the new feature)
• perf: A code change that improves performance (if part of the feature)
• chore: Changes to the build process or auxiliary tools and libraries suchs as documentation generation (if related to the new feature)
• ci: Changes to our CI configuration files and scripts (if related to the new feature)
• build: Changes that affect the build system or external dependencies (if related to the new feature)
• revert: Reverts a previous commit

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: concrete error classes keep their names, and every error remains a DatabaseError. Behavioural change: auto-commit failures now raise TransactionError instead of being logged and ignored, and transient connection retries now actually run.

Impact on Backend Developers (Custom Implementations):
No signature changes. Custom _handle_error implementations should raise taxonomy errors; the core pipeline adds a defensive fallback when a handler returns.

Related Repositories/Packages

• python-activerecord PR #139.
• python-activerecord-testsuite PR (taxonomy contract).
• CI pins in this repository currently point at feature/error-taxonomy for both core and testsuite, and will be restored to release branches after the merge.

Testing

• I have added new tests to cover my changes.
• I have updated existing tests to reflect my changes.
• All existing tests pass.
• This change has been tested against the backend matrix via CI.

Test Plan:

Local contract suites: 36 passed. Feature-branch CI run 42973520253: success.

Reproduction:

PYTHONPATH=src:tests pytest tests -k 'test_execute_error_contract or test_driver_error_mapping or test_error_taxonomy_contract'

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.
• 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 changelog fragment is added as changelog.d/<PR>.added.md once the PR number exists, because the checker requires the fragment number to equal the PR number.
• CI intentionally installs core and testsuite from feature/error-taxonomy; restore release pins after this PR and the core PR merge.

[sonarqubecloud]

Quality Gate passed

Issues
2 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

[codecov]

Codecov Report

❌ Patch coverage is 78.57143% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.79%. Comparing base (cc7d202) to head (c8c4ccd).

Files with missing lines	Patch %	Lines
...rd/backend/impl/clickhouse/mixins/backend_mixin.py	81.03%	7 Missing and 4 partials ⚠️
...erecord/backend/impl/clickhouse/backend/backend.py	73.07%	5 Missing and 2 partials ⚠️

Additional details and impacted files

@@                   Coverage Diff                   @@
##           release/v1.0.0.dev1      #12      +/-   ##
=======================================================
+ Coverage                76.45%   76.79%   +0.34%     
=======================================================
  Files                      138      138              
  Lines                     8468     8511      +43     
  Branches                   954      959       +5     
=======================================================
+ Hits                      6474     6536      +62     
+ Misses                    1702     1682      -20     
- Partials                   292      293       +1     

Flag	Coverage Δ
clickhouse-26.7	76.79% <78.57%> (+0.34%)	⬆️
python-3.14	76.79% <78.57%> (+0.34%)	⬆️
unittests	76.79% <78.57%> (+0.34%)	⬆️

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.