"""rename the template tables and columns to the title vocabulary Three names described the same thing by different words, so the schema read as if it held four concepts: template_field_library the catalogue of reusable headings (字段库) template_field one heading placed in one template, with its sort ``template_field`` is one word away from ``template_field_library`` and means the opposite kind of thing — a row versus the catalogue of rows — and neither name says what a row actually is. Every row of the library is a **heading**: a piece of text like 「1. Introduction」 with a level and typography, which is what the reader sees at the top of a paragraph. So the library becomes ``template_title`` and the placement becomes ``template_title_placement``, and the placement's reference to the library becomes ``title_id``. The name now says which is the catalogue and which is a placement, which is the distinction the old pair hid. template_title one reusable heading (字段库) template_title_placement that heading placed in a template, with `sort` Nothing else moves: ``template`` keeps its name, and every row in every table is preserved. ``RENAME TABLE`` moves the data in place, and TiDB carries a referencing foreign key along with both a renamed table and a renamed column (rehearsed against the cluster before this revision was written), so the constraint in ``template_title_placement`` follows without a drop/recreate step and stays enforced. Revision ID: b19e4d7a3c58 Revises: a83f5c21d7b6 Create Date: 2026-09-22 """ from collections.abc import Sequence import sqlalchemy as sa from alembic import op # revision identifiers, used by Alembic. revision: str = "b19e4d7a3c58" down_revision: str | None = "a83f5c21d7b6" branch_labels: str | Sequence[str] | None = None depends_on: str | Sequence[str] | None = None #: (old, new) index names on the placement table. They embed the table name and #: the column name, so both renames have to reach them or the schema ends up #: with indexes named after tables that no longer exist. _INDEXES = ( ("ix_template_field_field_id", "ix_template_title_placement_title_id"), ("ix_template_field_template_sort", "ix_template_title_placement_template_sort"), ) #: Index names that already say the new thing, so a rerun leaves them alone. _NEW_INDEXES = {new for _, new in _INDEXES} def upgrade() -> None: """Rename in place, tolerating a database where part of it already ran. Each step is guarded by what the database actually holds, rather than assuming a clean start. That is not decoration: the first attempt at this revision renamed the two tables and then failed on the column, because Alembic's MySQL dialect wants an explicit type for ``alter_column`` and won't rename a column without one. A migration that re-runs is the only way to finish a database left in that state, and it costs three dict lookups to be able to. """ bind = op.get_bind() inspector = sa.inspect(bind) tables = set(inspector.get_table_names()) if "template_field_library" in tables: op.rename_table("template_field_library", "template_title") if "template_field" in tables: op.rename_table("template_field", "template_title_placement") columns = { column["name"] for column in inspector.get_columns("template_title_placement") } if "field_id" in columns: # Raw SQL rather than ``op.alter_column``: TiDB supports # ``RENAME COLUMN`` directly, and the Alembic spelling goes through # ``CHANGE COLUMN``, which demands the current type be repeated. op.execute( "ALTER TABLE template_title_placement RENAME COLUMN field_id TO title_id" ) indexes = {index["name"] for index in inspector.get_indexes("template_title_placement")} for old, new in _INDEXES: if old in indexes and new not in indexes: op.execute( f"ALTER TABLE template_title_placement RENAME INDEX {old} TO {new}" ) def downgrade() -> None: bind = op.get_bind() inspector = sa.inspect(bind) indexes = { index["name"] for index in inspector.get_indexes("template_title_placement") } for old, new in _INDEXES: if new in indexes and old not in indexes: op.execute( f"ALTER TABLE template_title_placement RENAME INDEX {new} TO {old}" ) columns = { column["name"] for column in inspector.get_columns("template_title_placement") } if "title_id" in columns: op.execute( "ALTER TABLE template_title_placement RENAME COLUMN title_id TO field_id" ) op.rename_table("template_title_placement", "template_field") op.rename_table("template_title", "template_field_library")