Add SQLAlchemy example and migration files for ClickHouse and PostgreSQL (#220)

Author: chinhnguyen-95

projects/sqlalchemy/README.md

@@ -0,0 +1,34 @@
+# SQLAlchemy example
+
+This folder contains a minimal SQLAlchemy example used with Atlas. The README lists quick setup steps and the Atlas commands commonly used for generating migration files for different dialects.
+
+Prerequisites
+- Python.
+- `atlas` CLI available on your PATH.
+
+Quick setup
+
+1. Create and activate a virtual environment inside the project:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+2. Install Python dependencies from the provided `requirements.txt`:
+
+```bash
+pip install -r requirements.txt
+```
+
+Running Atlas migrate diffs
+
+From this directory you can run Atlas to generate migration files for different dialects using the `atlas migrate diff` command. Examples:
+
+```bash
+# Migration for ClickHouse
+atlas migrate diff --env sqlalchemy --var dialect=clickhouse
+
+# Migration for PostgreSQL
+atlas migrate diff --env sqlalchemy --var dialect=postgresql
+```

projects/sqlalchemy/app/models.py

@@ -0,0 +1,29 @@
+from sqlalchemy import ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship, DeclarativeBase
+from clickhouse_sqlalchemy import engines
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "user_account"
+    __table_args__ = (engines.MergeTree(order_by="id"),)
+    
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(30))
+    fullname: Mapped[str | None] = mapped_column(String(30))
+    addresses: Mapped[list["Address"]] = relationship(
+        back_populates="user", cascade="all, delete-orphan"
+    )
+
+
+class Address(Base):
+    __tablename__ = "address"
+    __table_args__ = (engines.MergeTree(order_by="id"),)
+    
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email_address: Mapped[str] = mapped_column(String(30))
+    user_id: Mapped[int] = mapped_column(ForeignKey("user_account.id"))
+    user: Mapped["User"] = relationship(back_populates="addresses")

projects/sqlalchemy/atlas.hcl

@@ -0,0 +1,29 @@
+variable "dialect" {
+  type = string
+}
+
+locals {
+  dev_url = {
+    mysql = "docker://mysql/8/dev"
+    postgresql = "docker://postgres/15"
+    sqlite = "sqlite://?mode=memory&_fk=1"
+    mssql = "docker://sqlserver/2022-latest"
+    clickhouse = "docker://clickhouse/23.11/dev"
+  }[var.dialect]
+}
+
+data "external_schema" "sqlalchemy" {
+  program = [
+    "atlas-provider-sqlalchemy",
+    "--path", "app",
+    "--dialect", var.dialect,
+  ]
+}
+
+env "sqlalchemy" {
+  src = data.external_schema.sqlalchemy.url
+  dev = local.dev_url
+  migration {
+    dir = "file://migrations/${var.dialect}"
+  }
+}

projects/sqlalchemy/migrations/clickhouse/20251008091308.sql

@@ -0,0 +1,14 @@
+-- Create "address" table
+CREATE TABLE `address` (
+  `id` Int32,
+  `email_address` FixedString(30),
+  `user_id` Int32
+) ENGINE = MergeTree
+PRIMARY KEY (`id`) ORDER BY (`id`) SETTINGS index_granularity = 8192;
+-- Create "user_account" table
+CREATE TABLE `user_account` (
+  `id` Int32,
+  `name` FixedString(30),
+  `fullname` FixedString(30)
+) ENGINE = MergeTree
+PRIMARY KEY (`id`) ORDER BY (`id`) SETTINGS index_granularity = 8192;

projects/sqlalchemy/migrations/clickhouse/atlas.sum

@@ -0,0 +1,2 @@
+h1:YuQ5NkluwWB2JuhWWycm2nE57WQMei0kUJdR44wmZl8=
+20251008091308.sql h1:AqkDYUGT5nmGPSxCIT5W/+gE7itlYq/Rkop98gmzTD4=

projects/sqlalchemy/migrations/postgresql/20251008091314.sql

@@ -0,0 +1,15 @@
+-- Create "user_account" table
+CREATE TABLE "public"."user_account" (
+  "id" serial NOT NULL,
+  "name" character varying(30) NOT NULL,
+  "fullname" character varying(30) NULL,
+  PRIMARY KEY ("id")
+);
+-- Create "address" table
+CREATE TABLE "public"."address" (
+  "id" serial NOT NULL,
+  "email_address" character varying(30) NOT NULL,
+  "user_id" integer NOT NULL,
+  PRIMARY KEY ("id"),
+  CONSTRAINT "address_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "public"."user_account" ("id") ON UPDATE NO ACTION ON DELETE NO ACTION
+);

projects/sqlalchemy/migrations/postgresql/atlas.sum

@@ -0,0 +1,2 @@
+h1:9kuDGlVM39qg/yzzmxkvR5BqE+r2jJm9Yotsx3u6S6A=
+20251008091314.sql h1:4FGUQLXUkLg5NLUehNvPCNG9+EsLCNeqyqYtaNEi7UU=

projects/sqlalchemy/requirements.txt

@@ -0,0 +1,3 @@
+sqlalchemy>=2.0.43
+clickhouse_sqlalchemy>=0.3.2
+atlas-provider-sqlalchemy>=0.4.1