Guides: procedures written and read inside ShopDB

plugins/guides/migrations/env.py

@@ -0,0 +1,16 @@
+"""Alembic environment for the guides plugin migration chain.
+
+Delegates to the shared runner in shopdb.plugins.alembic_template, which filters
+the metadata to this plugin's tables and drives Alembic against the per-plugin
+version table alembic_version_guides. See ADR-008 for the ownership model.
+
+Like the backups plugin and unlike the cutover ones, guides is NEW: its 0001
+baseline really CREATES its tables, because the core chain never built them.
+"""
+import os
+
+os.environ['PLUGIN_NAME'] = 'guides'
+
+from shopdb.plugins.alembic_template import run_migrations  # noqa: E402
+
+run_migrations()

plugins/guides/migrations/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade():
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade():
+    ${downgrades if downgrades else "pass"}

plugins/guides/migrations/versions/0001_guides_baseline.py

@@ -0,0 +1,114 @@
+"""guides plugin baseline: guides, guiderevisions, guideimages.
+
+A new plugin, so this builds its tables rather than stamping an anchor over
+core-owned ones (contrast the cutover plugins, whose 0001 is a no-op).
+
+Idempotent: each table is created only if it is not already there, so a database
+where an earlier run half-succeeded can be upgraded again without hand-editing
+alembic_version_guides.
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy import inspect
+
+
+revision = 'guides0001baseline'
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def _tables():
+    return set(inspect(op.get_bind()).get_table_names())
+
+
+def upgrade():
+    existing = _tables()
+
+    if 'guides' not in existing:
+        op.create_table(
+            'guides',
+            sa.Column('guideid', sa.Integer(), nullable=False),
+            sa.Column('title', sa.String(length=300), nullable=False),
+            # 191 because this is UNIQUE-indexed and MySQL caps an index key at
+            # 767 bytes; utf8mb4 is 4 bytes per character.
+            sa.Column('slug', sa.String(length=191), nullable=False),
+            sa.Column('summary', sa.String(length=1000)),
+            sa.Column('tags', sa.String(length=500)),
+            sa.Column('status', sa.String(length=20), nullable=False,
+                      server_default='draft'),
+            sa.Column('blocksjson', sa.dialects.mysql.MEDIUMTEXT()
+                      if op.get_bind().dialect.name == 'mysql' else sa.Text(),
+                      nullable=False),
+            sa.Column('publishedrevisionid', sa.Integer()),
+            sa.Column('createdby', sa.Integer()),
+            sa.Column('updatedby', sa.Integer()),
+            sa.Column('publishedat', sa.DateTime()),
+            # BaseModel contributes these to every model in the app; a plugin
+            # migration has to spell them out or the table is missing columns
+            # the ORM selects on every query.
+            sa.Column('createddate', sa.DateTime(), nullable=False),
+            sa.Column('modifieddate', sa.DateTime(), nullable=False),
+            sa.Column('isactive', sa.Boolean(), nullable=False),
+            sa.Column('revision', sa.Integer(), nullable=False, server_default='1'),
+            sa.PrimaryKeyConstraint('guideid'),
+            sa.UniqueConstraint('slug', name='uq_guides_slug'),
+        )
+        op.create_index('idx_guides_status', 'guides', ['status'])
+
+    if 'guiderevisions' not in existing:
+        op.create_table(
+            'guiderevisions',
+            sa.Column('guiderevisionid', sa.Integer(), nullable=False),
+            sa.Column('guideid', sa.Integer(), nullable=False),
+            sa.Column('revision', sa.Integer(), nullable=False),
+            sa.Column('title', sa.String(length=300), nullable=False),
+            sa.Column('summary', sa.String(length=1000)),
+            sa.Column('tags', sa.String(length=500)),
+            sa.Column('blocksjson', sa.dialects.mysql.MEDIUMTEXT()
+                      if op.get_bind().dialect.name == 'mysql' else sa.Text(),
+                      nullable=False),
+            sa.Column('contenthash', sa.String(length=64), nullable=False),
+            sa.Column('note', sa.String(length=500)),
+            sa.Column('createdby', sa.Integer()),
+            # BaseModel contributes these to every model in the app; a plugin
+            # migration has to spell them out or the table is missing columns
+            # the ORM selects on every query.
+            sa.Column('createddate', sa.DateTime(), nullable=False),
+            sa.Column('modifieddate', sa.DateTime(), nullable=False),
+            sa.Column('isactive', sa.Boolean(), nullable=False),
+            sa.PrimaryKeyConstraint('guiderevisionid'),
+            sa.ForeignKeyConstraint(['guideid'], ['guides.guideid'],
+                                    ondelete='CASCADE'),
+        )
+        op.create_index('idx_guiderevisions_guide', 'guiderevisions', ['guideid'])
+        op.create_index('idx_guiderevisions_hash', 'guiderevisions', ['contenthash'])
+
+    if 'guideimages' not in existing:
+        op.create_table(
+            'guideimages',
+            sa.Column('guideimageid', sa.Integer(), nullable=False),
+            sa.Column('guideid', sa.Integer()),
+            sa.Column('filename', sa.String(length=255)),
+            sa.Column('mimetype', sa.String(length=100), nullable=False),
+            sa.Column('bytesize', sa.Integer(), nullable=False),
+            sa.Column('data', sa.dialects.mysql.MEDIUMBLOB()
+                      if op.get_bind().dialect.name == 'mysql' else sa.LargeBinary(),
+                      nullable=False),
+            sa.Column('uploadedby', sa.Integer()),
+            # BaseModel contributes these to every model in the app; a plugin
+            # migration has to spell them out or the table is missing columns
+            # the ORM selects on every query.
+            sa.Column('createddate', sa.DateTime(), nullable=False),
+            sa.Column('modifieddate', sa.DateTime(), nullable=False),
+            sa.Column('isactive', sa.Boolean(), nullable=False),
+            sa.PrimaryKeyConstraint('guideimageid'),
+            sa.ForeignKeyConstraint(['guideid'], ['guides.guideid'],
+                                    ondelete='CASCADE'),
+        )
+        op.create_index('idx_guideimages_guide', 'guideimages', ['guideid'])
+
+
+def downgrade():
+    for table in ('guideimages', 'guiderevisions', 'guides'):
+        op.drop_table(table)