Repository navigation
Add refreshable and inner-engine materialized view forms to Alembic ops - #1204
joe-clickhouse wants to merge 2 commits into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
The refresh clause lacks online literal-percent escaping, so a dependency name such as dep%% becomes dep%, potentially referencing the wrong view or causing creation to fail.
1 open issue
What changed in this PR
This PR extends the driver's Alembic support to create refreshable and inner-engine materialized views, while retaining the existing target-table form.
Changes:
- Adds
ClickHouseRefresh, engine selection, comments, and initial-refresh control. - Adds operations to modify refresh schedules and SELECT queries.
- Adds tests, public exports, typing updates, and migration policy guidance.
| File | Description |
|---|---|
tests/unit_tests/test_sqlalchemy/test_alembic.py |
Tests validation, SQL generation, rendering, and reversal. |
tests/unit_tests/test_sqlalchemy/test_alembic_public_operations.py |
Covers the new public operations. |
tests/integration_tests/test_sqlalchemy/test_alembic.py |
Tests live creation, modification, and data behavior. |
docs/sqlalchemy.mdx |
Documents new forms, limits, and policy checks. |
clickhouse_connect/cc_sqlalchemy/ddl/tableengine.py |
Adds engine type annotations. |
clickhouse_connect/cc_sqlalchemy/ddl/refresh.py |
Defines and renders refresh specifications. |
clickhouse_connect/cc_sqlalchemy/alembic/WORKED_EXAMPLE.md |
Adds migration examples and safety guidance. |
clickhouse_connect/cc_sqlalchemy/alembic/operations.py |
Implements expanded creation and modification operations. |
clickhouse_connect/cc_sqlalchemy/alembic/adapter.py |
Renders new options and operations into revisions. |
clickhouse_connect/cc_sqlalchemy/alembic/__init__.py |
Exports refresh specifications and modification operations. |
clickhouse_connect/cc_sqlalchemy/__init__.py |
Exports ClickHouseRefresh from the SQLAlchemy API. |
CHANGELOG.md |
Records new capabilities and data-loss considerations. |
Review effort: Balanced
| f"TO {full_table(operation.to_table, operation.to_schema)} AS {operation.select}" | ||
| parts = [f"CREATE MATERIALIZED VIEW{exists} {full_table(operation.name, operation.schema)}"] | ||
| if operation.refresh is not None: | ||
| parts.append(operation.refresh.render()) |
There was a problem hiding this comment.
Auto-approved by the AI review gate on d22af93. Details in the approver's comment on this pull request.
AI review gate — auto-approved
History (latest 5 heads, newest first)
|
There was a problem hiding this comment.
Auto-approved by the AI review gate on 18f7c3e. Details in the approver's comment on this pull request.

Summary
create_clickhouse_materialized_viewonly handled the TO form. It now creates refreshable and inner-engine views too, so policy hooks can classify them by field instead of parsing SQL.engine,refresh,emptyandcommentarguments. The plain TO form renders the same SQL and revision text as before.ClickHouseRefreshdataclass for the REFRESH clause.modify_clickhouse_materialized_view_refreshandmodify_clickhouse_materialized_view_queryops.CreateClickHouseMaterializedViewOp. Hooks that approve byisinstanceshould checkengineandrefresh.TableEngineso the public type check does not regress.Known limit: create still collapses
%%to%online in the SELECT and comment. The modify ops keep%%.Checklist
🤖 Generated with Claude Code
Note
Medium Risk
Adds DDL migration paths that can create destructive inner-engine materialized views and alter refresh/query definitions; mistakes in migrations could drop or reshape stored data on apply.
Overview
Extends Alembic
create_clickhouse_materialized_viewbeyond the TO-table form so migrations can create inner-engine views (to_table=None+engine) and refreshable views via a newClickHouseRefreshhelper that renders the fullREFRESHclause (intervals, dependencies, settings,APPEND, etc.). Create also gainsempty,comment, and validation that exactly one ofto_tableorengineis set.Adds
modify_clickhouse_materialized_view_refreshandmodify_clickhouse_materialized_view_queryAlembic ops (with reversible behavior when prior definitions are supplied), updates autogen rendering/exports (23 public ops), and documents policy-hook guidance: all create shapes shareCreateClickHouseMaterializedViewOp, so reviewers should inspectengineandrefresh; drops may delete inner-table data for inner-engine views.TableEnginegets minor type annotations; integration and unit tests cover offline SQL, rendering round-trips, and live refresh/query behavior.Reviewed by Cursor Bugbot for commit 18f7c3e. Bugbot is set up for automated code reviews on this repo. Configure here.