docs: ADR for alembic migrations

docs/decisions/0007_clickhouse_migrations.rst

@@ -0,0 +1,48 @@
+7. Alembic migrations for Aspects
+#################################
+
+Status
+******
+
+Accepted
+
+Context
+*******
+
+Alembic is a migration tool for SQLAlchemy. It is used to manage the clickhouse database
+schema for the Aspects project.
+
+Alembic has support for branching migrations and multiple databases, it creates a migrations
+table in the database to keep track of the migrations that have been applied.
+
+For more information about Alembic, see https://alembic.sqlalchemy.org/en/latest/
+
+Decisions
+*********
+
+#. There should be a single initial SQL executed at initialization time. This will
+   create the databases, users and permissions, and any other necessary setup before
+   running migrations.
+#. Migrations are executed with RAW SQL using the ``op.execute`` method. This allows
+   us to use ClickHouse-specific SQL syntax.
+#. Migrations should always define a downgrade step, even if it is a no-op.
+#. Migrations are generated using a Sequential ID. This allows us to easily identify
+   the order in which migrations were created and executed.
+#. Migrations cannot be modified once they are released to production. If a migration
+   needs to be modified, a new migration should be created with a new sequential ID.
+#. The alembic migrations table is highly couple with the xAPI database, for this the
+   migrations table is stored in the xAPI database.
+
+Consequences
+************
+
+* Users should not run migrations manually. They should be run automatically by Tutor
+  when the LMS is started.
+
+Rejected Alternatives
+*********************
+
+**Clickhouse SQL Alchemy Models**
+
+Model allows us to automagically create tables and columns in Clickhouse. However, it is
+not well supported and we didn't find any benefits over raw SQL migrations.