Skip to content

Make ClickHouse Alembic operation classes public - #1180

Merged
joe-clickhouse merged 2 commits into
mainfrom
joe/alembic-operation-classification
Nov 11, 2026
Merged

joe-clickhouse merged 2 commits into
mainfrom
joe/alembic-operation-classification

Conversation

@joe-clickhouse

@joe-clickhouse joe-clickhouse commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The 21 ClickHouse Alembic operation classes are now public. Apps can match them with isinstance in process_revision_directives hooks and Alembic Rewriters.

  • Drop the leading underscore and add typed fields for policy checks.
  • Keep the old private names as aliases to the same classes, so existing imports and Rewriter registrations still work.
  • Add a recipe to the docs and WORKED_EXAMPLE.md that checks generated upgrade and downgrade operations.
  • Install Alembic in the CI consumer typing job, since it now scans these classes.

Checklist

  • Unit and integration tests covering the common scenarios were added
  • A human-readable description of the changes was provided to include in CHANGELOG

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are recorded for the change exposing public Alembic operation classes while retaining private names as aliases.

No open issues 🎉

What changed in this PR

This PR exposes all 21 ClickHouse Alembic operation classes so applications can inspect migration operations in policy hooks and Rewriters, while retaining the old private names as aliases.

Changes:

  • Export public operation classes with typed inspection fields.
  • Add a policy recipe that classifies both migration directions and blocks unapproved upgrades.
  • Add compatibility and typing coverage, and install Alembic in the consumer typing job.

No findings to report. Tests and type checks were not run.

File Description
tests/​unit_tests/​test_sqlalchemy/​test_alembic.py Update expected public exports.
tests/​unit_tests/​test_sqlalchemy/​test_alembic_public_operations.py Cover aliases, rendering, Rewriters, reverse operations, and policy recipes.
tests/​type_check/​consumer_smoke.py Check public operation field types.
docs/​sqlalchemy.mdx Document inspection fields and the migration policy recipe.
clickhouse_connect/​cc_sqlalchemy/​alembic/​WORKED_EXAMPLE.md Add the same policy recipe to the worked example.
clickhouse_connect/​cc_sqlalchemy/​alembic/​operations.py Make classes public, annotate fields, and preserve private aliases.
clickhouse_connect/​cc_sqlalchemy/​alembic/​__init__.py Export all 21 operation classes.
CHANGELOG.md Record the public API addition.
.github/​workflows/​on_push.yml Install Alembic for consumer typing checks and update explanatory comments.

Review effort: Balanced

@polyglotAI-bot polyglotAI-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. I found no blocking issues. The three inline notes are optional.

What I checked:

  • The 21 renamed classes and the 21 _-prefixed aliases are the same objects. Internal callers (adapter.py, indexes.py, projections.py, compare.py) and the existing tests still use the private names, so CI also covers the alias path.
  • Every __init__ parameter is stored on an attribute with an annotation of the same type. The only differences are Sequence[...] parameters stored as tuple[...], and that is correct.
  • The comparators emit only single index, projection, and settings ops. So the recipe's single-op replacement pairing matches what autogenerate produces. Grouped ops come only from hand-written migrations, and the recipe sends them to review or rejects them.
  • The recipe test runs the snippet from both docs and checks that the two copies are identical. This is a good guard against drift between the docs.

Residual compatibility note (no change requested): type(op).__name__, __qualname__, and the default repr() now show the public names. The aliases keep imports, isinstance, Rewriter.rewrites, and pickles working. Code that compares a class-name string with "_AddClickHouseIndexOp" will stop matching. I think this is acceptable for this change.

Comment thread .github/workflows/on_push.yml Resolved
Comment thread CHANGELOG.md Resolved
@joe-clickhouse
joe-clickhouse merged commit 61e7d59 into main Nov 11, 2026
55 checks passed
@joe-clickhouse
joe-clickhouse deleted the joe/alembic-operation-classification branch November 11, 2026 15:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants