mizzle 0.1.0__tar.gz

mizzle-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.pyc
+.venv/
+.coverage
+htmlcov/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Studio UI: local dev build, and the release manifest (written by release.yml)
+src/mizzle/studio/static/
+src/mizzle/studio/ui.json
+
+# Local secrets (database URLs, passwords)
+.env
+
+# Local AI-assistant working notes (design specs, plans)
+docs/superpowers/

mizzle-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mizzle contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mizzle-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: mizzle
+Version: 0.1.0
+Summary: Fully typed async ORM for PostgreSQL: SQL-like queries, schema-driven migrations and a data studio
+Project-URL: Homepage, https://github.com/mizzlehq/mizzle
+Project-URL: Repository, https://github.com/mizzlehq/mizzle
+Project-URL: Issues, https://github.com/mizzlehq/mizzle/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,asyncpg,migrations,orm,postgresql,query-builder,sql,typed
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: asyncpg>=0.30
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.7; extra == 'pydantic'
+Provides-Extra: studio
+Requires-Dist: starlette>=0.40; extra == 'studio'
+Requires-Dist: uvicorn>=0.30; extra == 'studio'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <img alt="mizzle" src="assets/logo.svg" width="320">
+  </picture>
+</p>
+
+# mizzle
+
+A fully typed, async ORM for Python and PostgreSQL: write queries that read like SQL,
+get typed rows back, and evolve your schema with generated migrations. If you know
+[Drizzle](https://orm.drizzle.team) from TypeScript, mizzle will feel familiar.
+
+- **Schema in Python classes.** Result rows are typed for pyright and mypy, with no code
+  generation.
+- **Two query styles:** a SQL-like builder (`select`, `insert`, `update`, `delete`, joins,
+  CTEs, upserts) and relational queries that load nested data in one SQL statement.
+- **Migration kit:** `generate`, `migrate`, `push`, `pull`, `check`, `drop`, `typegen`.
+- **Studio:** browse and edit data in your browser (`mizzle studio`).
+- **Safe by default:** values are always bind parameters, `update`/`delete` refuse to run
+  without `.where()`, migrations are locked, transactional and tamper-checked, and errors
+  never include row values.
+
+Built for PostgreSQL first; other SQL databases plug in through the dialect layer
+(`src/mizzle/dialects/`).
+
+A complete example app (FastAPI, migrations, seed data, tests) lives in
+[`examples/social`](examples/social).
+
+## Install
+
+```bash
+pip install mizzle            # ORM + migration CLI
+pip install "mizzle[studio]"  # + Studio (its UI downloads into your venv on first run, ~250 KB)
+```
+
+## Schema
+
+```python
+# app/db/schema.py
+import enum
+from typing import final, override
+
+from mizzle import Table, index, many, one, sql
+from mizzle.pg import integer, pg_enum, serial, text, timestamp, varchar
+
+
+class Role(enum.StrEnum):
+    ADMIN = "admin"
+    USER = "user"
+
+
+@final
+class Users(Table, name="users"):
+    id = serial().primary_key()  # Column[int]
+    email = varchar(255).not_null().unique()  # Column[str]
+    bio = text()  # Column[str | None]
+    role = pg_enum(Role).not_null().default(Role.USER)  # Column[Role]
+    created_at = timestamp(tz=True).not_null().default(sql("now()"))
+
+    posts = many(lambda: Posts)
+
+
+@final
+class Posts(Table, name="posts"):
+    id = serial().primary_key()
+    author_id = integer().not_null().references(lambda: Users.id, on_delete="cascade")
+    title = text().not_null()
+
+    author = one(lambda: Users, fields=lambda: [Posts.author_id], references=lambda: [Users.id])
+
+    @classmethod
+    @override
+    def config(cls):
+        return [index("posts_author_idx").on(cls.author_id)]
+```
+
+## Queries
+
+```python
+from mizzle import Database, desc, eq
+
+async with await Database.connect("postgresql://...", schema=[Users, Posts]) as db:
+    [ann] = await db.insert(Users).values(email="ann@x.io").returning()  # Users
+    admins = await db.select().from_(Users).where(eq(Users.role, Role.ADMIN))  # list[Users]
+    pairs = await (
+        db.select(Users, Posts).from_(Users).left_join(Posts, eq(Posts.author_id, Users.id))
+    )  # list[tuple[Users, Posts | None]]
+
+    # Relational: one SQL statement, typed nested results.
+    users = await db.query(Users).find_many(
+        with_={"posts": {"order_by": desc(Posts.id), "limit": 5}},
+    )
+    users[0].posts[0].title  # str
+
+    async with db.transaction() as tx:
+        await tx.update(Users).set(bio="hi").where(eq(Users.id, ann.id))
+```
+
+Raw SQL: `sql(t"select * from users where id = {user_id}")` (Python 3.14+) or
+`sql("... where id = {}", user_id)`. Values become bind parameters. **Never build the text
+passed to `sql()` from user input** (for example with an f-string).
+
+## Migrations
+
+`mizzle init` creates `mizzle.toml`, a starter schema module and the migrations folder
+(`--pyproject` puts the settings in `[tool.mizzle]` of `pyproject.toml` instead):
+
+```toml
+schema = "app.db.schema"   # module(s) with your tables
+out = "migrations"         # commit this folder
+url_env = "DATABASE_URL"   # the URL is read from the environment
+```
+
+```bash
+mizzle init                # set up mizzle.toml, db/schema.py and migrations/
+mizzle generate            # write migrations/0001_.../migration.sql + snapshot.json
+mizzle migrate             # apply pending migrations (safe with many app servers)
+mizzle push                # dev: sync schema straight to the database
+mizzle pull                # existing database -> your schema module (or pulled_schema.py next to it)
+mizzle check               # find broken or clashing migrations
+mizzle drop                # delete the latest, unapplied migration
+mizzle typegen             # TypedDicts for insert/update values
+mizzle studio              # open Studio
+```
+
+Renames: on a terminal, `generate` asks whether a new column is a rename. In CI pass
+`--rename users.name=full_name`. Changes that can lose data need confirmation or
+`--allow-data-loss`. From code: `await mizzle.kit.migrate(db, "migrations")`.
+
+## Development
+
+```bash
+docker compose up -d
+export MIZZLE_TEST_URL=postgresql://mizzle:mizzle@localhost:54329/mizzle
+uv run pytest            # integration tests skip when MIZZLE_TEST_URL is unset
+uv run pyright && uv run mypy
+uv run ruff check && uv run ruff format --check
+
+cd studio-ui && pnpm install && pnpm build   # builds the UI into src/mizzle/studio/static
+pnpm dev                                     # UI dev server; proxies /api to `mizzle studio`
+pnpm check                                   # Biome: format, lint, sort imports (--write)
+```
+
+Releases: push a `v*` tag. `.github/workflows/release.yml` builds the UI, packages it into
+the wheel, and publishes to PyPI with trusted publishing.

mizzle-0.1.0/README.md

@@ -0,0 +1,146 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <img alt="mizzle" src="assets/logo.svg" width="320">
+  </picture>
+</p>
+
+# mizzle
+
+A fully typed, async ORM for Python and PostgreSQL: write queries that read like SQL,
+get typed rows back, and evolve your schema with generated migrations. If you know
+[Drizzle](https://orm.drizzle.team) from TypeScript, mizzle will feel familiar.
+
+- **Schema in Python classes.** Result rows are typed for pyright and mypy, with no code
+  generation.
+- **Two query styles:** a SQL-like builder (`select`, `insert`, `update`, `delete`, joins,
+  CTEs, upserts) and relational queries that load nested data in one SQL statement.
+- **Migration kit:** `generate`, `migrate`, `push`, `pull`, `check`, `drop`, `typegen`.
+- **Studio:** browse and edit data in your browser (`mizzle studio`).
+- **Safe by default:** values are always bind parameters, `update`/`delete` refuse to run
+  without `.where()`, migrations are locked, transactional and tamper-checked, and errors
+  never include row values.
+
+Built for PostgreSQL first; other SQL databases plug in through the dialect layer
+(`src/mizzle/dialects/`).
+
+A complete example app (FastAPI, migrations, seed data, tests) lives in
+[`examples/social`](examples/social).
+
+## Install
+
+```bash
+pip install mizzle            # ORM + migration CLI
+pip install "mizzle[studio]"  # + Studio (its UI downloads into your venv on first run, ~250 KB)
+```
+
+## Schema
+
+```python
+# app/db/schema.py
+import enum
+from typing import final, override
+
+from mizzle import Table, index, many, one, sql
+from mizzle.pg import integer, pg_enum, serial, text, timestamp, varchar
+
+
+class Role(enum.StrEnum):
+    ADMIN = "admin"
+    USER = "user"
+
+
+@final
+class Users(Table, name="users"):
+    id = serial().primary_key()  # Column[int]
+    email = varchar(255).not_null().unique()  # Column[str]
+    bio = text()  # Column[str | None]
+    role = pg_enum(Role).not_null().default(Role.USER)  # Column[Role]
+    created_at = timestamp(tz=True).not_null().default(sql("now()"))
+
+    posts = many(lambda: Posts)
+
+
+@final
+class Posts(Table, name="posts"):
+    id = serial().primary_key()
+    author_id = integer().not_null().references(lambda: Users.id, on_delete="cascade")
+    title = text().not_null()
+
+    author = one(lambda: Users, fields=lambda: [Posts.author_id], references=lambda: [Users.id])
+
+    @classmethod
+    @override
+    def config(cls):
+        return [index("posts_author_idx").on(cls.author_id)]
+```
+
+## Queries
+
+```python
+from mizzle import Database, desc, eq
+
+async with await Database.connect("postgresql://...", schema=[Users, Posts]) as db:
+    [ann] = await db.insert(Users).values(email="ann@x.io").returning()  # Users
+    admins = await db.select().from_(Users).where(eq(Users.role, Role.ADMIN))  # list[Users]
+    pairs = await (
+        db.select(Users, Posts).from_(Users).left_join(Posts, eq(Posts.author_id, Users.id))
+    )  # list[tuple[Users, Posts | None]]
+
+    # Relational: one SQL statement, typed nested results.
+    users = await db.query(Users).find_many(
+        with_={"posts": {"order_by": desc(Posts.id), "limit": 5}},
+    )
+    users[0].posts[0].title  # str
+
+    async with db.transaction() as tx:
+        await tx.update(Users).set(bio="hi").where(eq(Users.id, ann.id))
+```
+
+Raw SQL: `sql(t"select * from users where id = {user_id}")` (Python 3.14+) or
+`sql("... where id = {}", user_id)`. Values become bind parameters. **Never build the text
+passed to `sql()` from user input** (for example with an f-string).
+
+## Migrations
+
+`mizzle init` creates `mizzle.toml`, a starter schema module and the migrations folder
+(`--pyproject` puts the settings in `[tool.mizzle]` of `pyproject.toml` instead):
+
+```toml
+schema = "app.db.schema"   # module(s) with your tables
+out = "migrations"         # commit this folder
+url_env = "DATABASE_URL"   # the URL is read from the environment
+```
+
+```bash
+mizzle init                # set up mizzle.toml, db/schema.py and migrations/
+mizzle generate            # write migrations/0001_.../migration.sql + snapshot.json
+mizzle migrate             # apply pending migrations (safe with many app servers)
+mizzle push                # dev: sync schema straight to the database
+mizzle pull                # existing database -> your schema module (or pulled_schema.py next to it)
+mizzle check               # find broken or clashing migrations
+mizzle drop                # delete the latest, unapplied migration
+mizzle typegen             # TypedDicts for insert/update values
+mizzle studio              # open Studio
+```
+
+Renames: on a terminal, `generate` asks whether a new column is a rename. In CI pass
+`--rename users.name=full_name`. Changes that can lose data need confirmation or
+`--allow-data-loss`. From code: `await mizzle.kit.migrate(db, "migrations")`.
+
+## Development
+
+```bash
+docker compose up -d
+export MIZZLE_TEST_URL=postgresql://mizzle:mizzle@localhost:54329/mizzle
+uv run pytest            # integration tests skip when MIZZLE_TEST_URL is unset
+uv run pyright && uv run mypy
+uv run ruff check && uv run ruff format --check
+
+cd studio-ui && pnpm install && pnpm build   # builds the UI into src/mizzle/studio/static
+pnpm dev                                     # UI dev server; proxies /api to `mizzle studio`
+pnpm check                                   # Biome: format, lint, sort imports (--write)
+```
+
+Releases: push a `v*` tag. `.github/workflows/release.yml` builds the UI, packages it into
+the wheel, and publishes to PyPI with trusted publishing.

mizzle-0.1.0/assets/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" rx="14" fill="#0B1020"/><g stroke-width="5" stroke-linecap="round" transform="translate(6.4 6.4) scale(0.8)"><path d="M14.0 20.0H50.0" stroke="#93B4FF"/><path d="M22.0 32.0H54.0" stroke="#5F86EE"/><path d="M10.0 44.0H38.0" stroke="#3A5BB8"/></g></svg>

mizzle-0.1.0/assets/logo-dark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 186 64" role="img" aria-label="mizzle"><g stroke-width="6" stroke-linecap="round"><path d="M12 20.0H48" stroke="#93B4FF"/><path d="M20 32.0H52" stroke="#5F86EE"/><path d="M8 44.0H36" stroke="#3A5BB8"/></g><!-- "mizzle" set in Geist (SIL Open Font License), converted to outlines --><path transform="translate(64 43)" fill="#F8FAFC" d="M2.584 0.0V-20.33H7.353L7.524 -15.389999999999999L7.03 -15.618Q7.41 -17.252 8.265 -18.4015Q9.12 -19.551 10.3455 -20.168499999999998Q11.571 -20.785999999999998 13.033999999999999 -20.785999999999998Q15.599 -20.785999999999998 17.185499999999998 -19.313499999999998Q18.772 -17.841 19.209 -15.314L18.525 -15.295Q18.867 -17.081 19.7125 -18.296999999999997Q20.558 -19.512999999999998 21.8215 -20.149499999999996Q23.085 -20.785999999999998 24.662 -20.785999999999998Q26.771 -20.785999999999998 28.291 -19.902499999999996Q29.811 -19.019 30.6375 -17.2995Q31.464 -15.58 31.464 -13.072V0.0H26.182V-11.647Q26.182 -14.097999999999999 25.3935 -15.3235Q24.605 -16.549 22.913999999999998 -16.549Q21.812 -16.549 21.033 -15.96Q20.253999999999998 -15.371 19.836 -14.25Q19.418 -13.129 19.418 -11.533V0.0H14.591999999999999V-11.533Q14.591999999999999 -13.965 13.87 -15.257Q13.148 -16.549 11.381 -16.549Q10.279 -16.549 9.5 -15.96Q8.721 -15.371 8.2935 -14.2405Q7.866 -13.11 7.866 -11.533V0.0ZM35.872 0.0V-20.33H41.153999999999996V0.0ZM35.777 -22.933V-27.378999999999998H41.248999999999995V-22.933ZM44.878 0.0V-4.256L56.354 -16.320999999999998H45.334V-20.33H62.643V-16.073999999999998L51.015 -4.009H62.928V0.0ZM65.968 0.0V-4.256L77.444 -16.320999999999998H66.42399999999999V-20.33H83.733V-16.073999999999998L72.10499999999999 -4.009H84.018V0.0ZM92.834 0.0Q90.47800000000001 0.0 89.11000000000001 -1.197Q87.742 -2.394 87.742 -5.054V-26.98H93.024V-5.6049999999999995Q93.024 -4.769 93.4325 -4.389Q93.84100000000001 -4.009 94.601 -4.009H96.026V0.0ZM107.53999999999999 0.45599999999999996Q104.462 0.45599999999999996 102.19149999999999 -0.855Q99.92099999999999 -2.166 98.6765 -4.56Q97.432 -6.954 97.432 -10.165Q97.432 -13.376 98.6765 -15.751000000000001Q99.92099999999999 -18.126 102.1725 -19.456Q104.424 -20.785999999999998 107.464 -20.785999999999998Q110.428 -20.785999999999998 112.64150000000001 -19.474999999999998Q114.855 -18.163999999999998 116.0615 -15.713Q117.268 -13.262 117.268 -9.842V-8.721H102.904Q103.037 -6.175 104.291 -4.9115Q105.545 -3.6479999999999997 107.616 -3.6479999999999997Q109.155 -3.6479999999999997 110.181 -4.3225Q111.207 -4.997 111.625 -6.289L116.983 -5.966Q116.166 -2.964 113.6485 -1.254Q111.131 0.45599999999999996 107.53999999999999 0.45599999999999996ZM102.904 -12.103H111.834Q111.701 -14.459 110.5135 -15.6085Q109.326 -16.758 107.464 -16.758Q105.602 -16.758 104.386 -15.551499999999999Q103.17 -14.344999999999999 102.904 -12.103Z"/></svg>

mizzle-0.1.0/assets/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 186 64" role="img" aria-label="mizzle"><g stroke-width="6" stroke-linecap="round"><path d="M12 20.0H48" stroke="#1D4ED8"/><path d="M20 32.0H52" stroke="#5B7FE3"/><path d="M8 44.0H36" stroke="#A3B8F1"/></g><!-- "mizzle" set in Geist (SIL Open Font License), converted to outlines --><path transform="translate(64 43)" fill="#0F172A" d="M2.584 0.0V-20.33H7.353L7.524 -15.389999999999999L7.03 -15.618Q7.41 -17.252 8.265 -18.4015Q9.12 -19.551 10.3455 -20.168499999999998Q11.571 -20.785999999999998 13.033999999999999 -20.785999999999998Q15.599 -20.785999999999998 17.185499999999998 -19.313499999999998Q18.772 -17.841 19.209 -15.314L18.525 -15.295Q18.867 -17.081 19.7125 -18.296999999999997Q20.558 -19.512999999999998 21.8215 -20.149499999999996Q23.085 -20.785999999999998 24.662 -20.785999999999998Q26.771 -20.785999999999998 28.291 -19.902499999999996Q29.811 -19.019 30.6375 -17.2995Q31.464 -15.58 31.464 -13.072V0.0H26.182V-11.647Q26.182 -14.097999999999999 25.3935 -15.3235Q24.605 -16.549 22.913999999999998 -16.549Q21.812 -16.549 21.033 -15.96Q20.253999999999998 -15.371 19.836 -14.25Q19.418 -13.129 19.418 -11.533V0.0H14.591999999999999V-11.533Q14.591999999999999 -13.965 13.87 -15.257Q13.148 -16.549 11.381 -16.549Q10.279 -16.549 9.5 -15.96Q8.721 -15.371 8.2935 -14.2405Q7.866 -13.11 7.866 -11.533V0.0ZM35.872 0.0V-20.33H41.153999999999996V0.0ZM35.777 -22.933V-27.378999999999998H41.248999999999995V-22.933ZM44.878 0.0V-4.256L56.354 -16.320999999999998H45.334V-20.33H62.643V-16.073999999999998L51.015 -4.009H62.928V0.0ZM65.968 0.0V-4.256L77.444 -16.320999999999998H66.42399999999999V-20.33H83.733V-16.073999999999998L72.10499999999999 -4.009H84.018V0.0ZM92.834 0.0Q90.47800000000001 0.0 89.11000000000001 -1.197Q87.742 -2.394 87.742 -5.054V-26.98H93.024V-5.6049999999999995Q93.024 -4.769 93.4325 -4.389Q93.84100000000001 -4.009 94.601 -4.009H96.026V0.0ZM107.53999999999999 0.45599999999999996Q104.462 0.45599999999999996 102.19149999999999 -0.855Q99.92099999999999 -2.166 98.6765 -4.56Q97.432 -6.954 97.432 -10.165Q97.432 -13.376 98.6765 -15.751000000000001Q99.92099999999999 -18.126 102.1725 -19.456Q104.424 -20.785999999999998 107.464 -20.785999999999998Q110.428 -20.785999999999998 112.64150000000001 -19.474999999999998Q114.855 -18.163999999999998 116.0615 -15.713Q117.268 -13.262 117.268 -9.842V-8.721H102.904Q103.037 -6.175 104.291 -4.9115Q105.545 -3.6479999999999997 107.616 -3.6479999999999997Q109.155 -3.6479999999999997 110.181 -4.3225Q111.207 -4.997 111.625 -6.289L116.983 -5.966Q116.166 -2.964 113.6485 -1.254Q111.131 0.45599999999999996 107.53999999999999 0.45599999999999996ZM102.904 -12.103H111.834Q111.701 -14.459 110.5135 -15.6085Q109.326 -16.758 107.464 -16.758Q105.602 -16.758 104.386 -15.551499999999999Q103.17 -14.344999999999999 102.904 -12.103Z"/></svg>

mizzle-0.1.0/assets/mark-dark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="mizzle"><g stroke-width="6" stroke-linecap="round"><path d="M14.0 20.0H50.0" stroke="#93B4FF"/><path d="M22.0 32.0H54.0" stroke="#5F86EE"/><path d="M10.0 44.0H38.0" stroke="#3A5BB8"/></g></svg>

mizzle-0.1.0/assets/mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="mizzle"><g stroke-width="6" stroke-linecap="round"><path d="M14.0 20.0H50.0" stroke="#1D4ED8"/><path d="M22.0 32.0H54.0" stroke="#5B7FE3"/><path d="M10.0 44.0H38.0" stroke="#A3B8F1"/></g></svg>

mizzle-0.1.0/examples/social/.env.example

@@ -0,0 +1,4 @@
+# Copy to .env. The Docker Postgres from the repo's docker-compose.yml:
+DATABASE_URL=postgresql://mizzle:mizzle@localhost:54329/mizzle_dev
+# Apply pending migrations when the API starts (safe with many processes).
+MIGRATE_ON_START=1

mizzle-0.1.0/examples/social/README.md

@@ -0,0 +1,49 @@
+# mizzle example: a small social network API
+
+FastAPI + mizzle: profiles, follows, posts with visibility (public / followers / private),
+comments, likes and bookmarks. It shows the patterns a real app needs:
+
+- **Schema** in `social/schema.py` (`@final` tables, enums, composite keys, checks, indexes,
+  relations) and its **migration history** in `migrations/`.
+- **Request models with allowlists** (`social/models.py`): clients can only send the listed
+  fields, so they cannot set ids, authors or timestamps.
+- **Relational queries** for nested data (a post with its comments and their authors) and
+  typed `select` queries for counts.
+- **Upserts** for idempotent likes, follows and bookmarks.
+- **Migrations at startup** (`MIGRATE_ON_START=1`), safe with many workers (advisory lock).
+- **Database errors as HTTP**: unique → 409, check constraint → 422, missing reference → 404.
+- **End-to-end tests** against a fresh database (`tests/test_api.py`).
+
+## Run it
+
+```bash
+docker compose -f ../../docker-compose.yml up -d    # Postgres on localhost:54329
+cp .env.example .env
+uv sync
+uv run mizzle migrate                                # or rely on MIGRATE_ON_START=1
+uv run python -m social.seed                         # optional demo data
+uv run uvicorn social.app:create_app --factory --reload
+```
+
+Open http://127.0.0.1:8000/docs. Authentication is out of scope: send `X-User-Id: <id>`
+to act as a user (the seed creates ids 1-24).
+
+```bash
+curl -s localhost:8000/feed -H 'X-User-Id: 1' | python -m json.tool | head -40
+uv run mizzle studio                                 # browse the data
+```
+
+## Change the schema
+
+Edit `social/schema.py`, then:
+
+```bash
+uv run mizzle generate --name what_changed
+uv run mizzle migrate
+```
+
+## Test
+
+```bash
+MIZZLE_TEST_URL=postgresql://mizzle:mizzle@localhost:54329/mizzle uv run pytest
+```

mizzle-0.1.0/examples/social/migrations/0001_social_schema/migration.sql

@@ -0,0 +1,88 @@
+-- create enum visibility
+-- create table users
+-- create table follows
+-- create table posts
+-- create table comments
+-- create table likes
+-- create index follows_followee_idx
+-- create index posts_author_created_idx
+-- create index comments_post_idx
+-- create index likes_post_idx
+-- add foreign key follows_follower_id_fkey
+-- add foreign key follows_followee_id_fkey
+-- add foreign key posts_author_id_fkey
+-- add foreign key comments_post_id_fkey
+-- add foreign key comments_author_id_fkey
+-- add foreign key likes_user_id_fkey
+-- add foreign key likes_post_id_fkey
+CREATE TYPE "visibility" AS ENUM ('public', 'followers', 'private');
+-- mizzle:breakpoint
+CREATE TABLE "users" (
+    "id" serial NOT NULL,
+    "username" character varying(32) NOT NULL,
+    "email" character varying(255) NOT NULL,
+    "display_name" text NOT NULL,
+    "bio" text,
+    "created_at" timestamp with time zone NOT NULL DEFAULT now(),
+    CONSTRAINT "users_pkey" PRIMARY KEY ("id"),
+    CONSTRAINT "users_username_key" UNIQUE ("username"),
+    CONSTRAINT "users_email_key" UNIQUE ("email"),
+    CONSTRAINT "users_username_format" CHECK (username ~ '^[a-z0-9_]{3,32}$')
+);
+-- mizzle:breakpoint
+CREATE TABLE "follows" (
+    "follower_id" integer NOT NULL,
+    "followee_id" integer NOT NULL,
+    "created_at" timestamp with time zone NOT NULL DEFAULT now(),
+    CONSTRAINT "follows_pkey" PRIMARY KEY ("follower_id", "followee_id"),
+    CONSTRAINT "follows_not_self" CHECK (follower_id <> followee_id)
+);
+-- mizzle:breakpoint
+CREATE TABLE "posts" (
+    "id" serial NOT NULL,
+    "author_id" integer NOT NULL,
+    "body" text NOT NULL,
+    "visibility" visibility NOT NULL DEFAULT 'public',
+    "meta" jsonb,
+    "created_at" timestamp with time zone NOT NULL DEFAULT now(),
+    CONSTRAINT "posts_pkey" PRIMARY KEY ("id"),
+    CONSTRAINT "posts_body_not_empty" CHECK (length(body) > 0)
+);
+-- mizzle:breakpoint
+CREATE TABLE "comments" (
+    "id" serial NOT NULL,
+    "post_id" integer NOT NULL,
+    "author_id" integer NOT NULL,
+    "body" text NOT NULL,
+    "created_at" timestamp with time zone NOT NULL DEFAULT now(),
+    CONSTRAINT "comments_pkey" PRIMARY KEY ("id")
+);
+-- mizzle:breakpoint
+CREATE TABLE "likes" (
+    "user_id" integer NOT NULL,
+    "post_id" integer NOT NULL,
+    "created_at" timestamp with time zone NOT NULL DEFAULT now(),
+    CONSTRAINT "likes_pkey" PRIMARY KEY ("user_id", "post_id")
+);
+-- mizzle:breakpoint
+CREATE INDEX "follows_followee_idx" ON "follows" ("followee_id");
+-- mizzle:breakpoint
+CREATE INDEX "posts_author_created_idx" ON "posts" ("author_id", "created_at");
+-- mizzle:breakpoint
+CREATE INDEX "comments_post_idx" ON "comments" ("post_id");
+-- mizzle:breakpoint
+CREATE INDEX "likes_post_idx" ON "likes" ("post_id");
+-- mizzle:breakpoint
+ALTER TABLE "follows" ADD CONSTRAINT "follows_follower_id_fkey" FOREIGN KEY ("follower_id") REFERENCES "users" ("id") ON DELETE CASCADE;
+-- mizzle:breakpoint
+ALTER TABLE "follows" ADD CONSTRAINT "follows_followee_id_fkey" FOREIGN KEY ("followee_id") REFERENCES "users" ("id") ON DELETE CASCADE;
+-- mizzle:breakpoint
+ALTER TABLE "posts" ADD CONSTRAINT "posts_author_id_fkey" FOREIGN KEY ("author_id") REFERENCES "users" ("id") ON DELETE CASCADE;
+-- mizzle:breakpoint
+ALTER TABLE "comments" ADD CONSTRAINT "comments_post_id_fkey" FOREIGN KEY ("post_id") REFERENCES "posts" ("id") ON DELETE CASCADE;
+-- mizzle:breakpoint
+ALTER TABLE "comments" ADD CONSTRAINT "comments_author_id_fkey" FOREIGN KEY ("author_id") REFERENCES "users" ("id") ON DELETE CASCADE;
+-- mizzle:breakpoint
+ALTER TABLE "likes" ADD CONSTRAINT "likes_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users" ("id") ON DELETE CASCADE;
+-- mizzle:breakpoint
+ALTER TABLE "likes" ADD CONSTRAINT "likes_post_id_fkey" FOREIGN KEY ("post_id") REFERENCES "posts" ("id") ON DELETE CASCADE;