ormate 0.1.0__tar.gz

ormate-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage

ormate-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

ormate-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+- 提供同步和异步 SQLAlchemy 会话作用域。
+- 提供基于 `StorageAdapter` 的统一 `ModelRepository`。
+- 提供 `SQLAlchemyAdapter`，SQLAlchemy 与 SQLModel 表模型共享同一套接口。
+- 提供直接继承 `SQLAlchemyAdapter` 的 `SQLModelAdapter` 语义入口，不干预业务模型的基础字段定义。
+- 通过 Adapter 的 `storage_name()` 统一解析 SQL 表名与 Elasticsearch 索引名。
+- 提供可选 `ElasticsearchAdapter` 与 `ElasticsearchDocument`，支持原生 Query DSL、全文检索入口和聚合。
+- 支持独立 Create、Update、Read 模型、批量主键操作、复合主键、计数和存在性检查。
+- 提供并发安全的会话作用域、ASGI 中间件和数据库驱动 extras。

ormate-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 zhangzhanqi
+
+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.
+

ormate-0.1.0/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: ormate
+Version: 0.1.0
+Summary: Async repositories with separate read/write models and pluggable storage adapters
+Author: zhangzhanqi
+License: MIT License
+        
+        Copyright (c) 2026 zhangzhanqi
+        
+        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.
+        
+License-File: LICENSE
+Keywords: asyncio,database,elasticsearch,repository,sqlalchemy,sqlmodel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: sqlalchemy<3,>=2.0.36
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: elasticsearch[async]<10,>=8.17; extra == 'dev'
+Requires-Dist: httpx>=0.28; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pydantic>=2.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: sqlmodel>=0.0.22; extra == 'dev'
+Requires-Dist: starlette>=0.41; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Provides-Extra: elasticsearch
+Requires-Dist: elasticsearch[async]<10,>=8.17; extra == 'elasticsearch'
+Requires-Dist: pydantic>=2.10; extra == 'elasticsearch'
+Provides-Extra: mysql
+Requires-Dist: aiomysql>=0.2; extra == 'mysql'
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
+Provides-Extra: postgresql
+Requires-Dist: asyncpg>=0.30; extra == 'postgresql'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgresql'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.20; extra == 'sqlite'
+Provides-Extra: sqlmodel
+Requires-Dist: sqlmodel>=0.0.22; extra == 'sqlmodel'
+Provides-Extra: web
+Requires-Dist: starlette>=0.41; extra == 'web'
+Description-Content-Type: text/markdown
+
+# ormate
+
+ormate 是一个异步 Repository 工具包，用同一套 CRUD 接口访问 SQLAlchemy、SQLModel 和 Elasticsearch。Repository 负责输入输出模型转换，Adapter 负责具体的存储操作和查询语法。
+
+项目目前处于 `0.1.0` 阶段，API 在 `1.0` 前仍可能调整。
+
+## 安装
+
+需要 Python 3.13 或更高版本。核心包只依赖 SQLAlchemy：
+
+```bash
+pip install ormate
+```
+
+其他依赖按需安装：
+
+```bash
+pip install "ormate[sqlite]"
+pip install "ormate[sqlmodel]"
+pip install "ormate[postgresql]"
+pip install "ormate[mysql]"
+pip install "ormate[elasticsearch]"
+pip install "ormate[web]"
+```
+
+## SQLAlchemy
+
+```python
+from pydantic import BaseModel
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from ormate import AsyncDatabase, ModelRepository, SQLAlchemyAdapter
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str]
+
+
+class UserCreate(BaseModel):
+    id: int
+    name: str
+
+
+class UserRead(BaseModel):
+    id: int
+    name: str
+
+
+db = AsyncDatabase.create("sqlite+aiosqlite:///app.db")
+repository = ModelRepository(SQLAlchemyAdapter(db), User, UserRead)
+
+async with db.engine.begin() as connection:
+    await connection.run_sync(Base.metadata.create_all)
+
+created = await repository.create_item(UserCreate(id=1, name="Ada"))
+loaded = await repository.read_item_by_primary_key(1)
+updated = await repository.update_item_by_primary_key(1, {"name": "Grace"})
+deleted = await repository.delete_item_by_primary_key(1)
+```
+
+Create 和 Update 参数可以是字典，也可以是实现了 `model_dump(exclude_unset=True)` 的 Pydantic/SQLModel 对象。传入 ReadModel 时，该模型需要提供 `model_validate()`；不传则返回存储模型。
+
+SQLAlchemy 条件查询直接使用 SQLAlchemy 表达式：
+
+```python
+users = await repository.read_items(User.name.contains("Ada"), limit=20)
+total = await repository.count(User.name.contains("Ada"))
+```
+
+## SQLModel 与事务
+
+`SQLModelAdapter` 继承 `SQLAlchemyAdapter`，两者使用相同的 Session 和事务实现。绑定到同一个 `Database` 后，SQLAlchemy 和 SQLModel 的操作可以放在同一个事务中：
+
+```python
+audit_logs = ModelRepository(SQLAlchemyAdapter(db), AuditLog)
+tasks = ModelRepository(SQLModelAdapter(db), Task)
+
+async with db:
+    await audit_logs.create_item({"id": 1, "message": "task created"})
+    await tasks.create_item({"title": "publish package"})
+```
+
+作用域正常退出时提交，发生异常时回滚。同步代码可以使用 `Database` 和 `with db:`。
+
+相关示例：
+
+- `examples/async_sqlalchemy.py`
+- `examples/sync_sqlalchemy.py`
+- `examples/async_sqlmodel.py`
+- `examples/shared_transaction.py`
+
+## Elasticsearch
+
+Elasticsearch 使用 Pydantic 文档模型，查询参数保持原生 Query DSL：
+
+```python
+from ormate import ModelRepository
+from ormate.elasticsearch import ElasticsearchAdapter, ElasticsearchDocument
+
+
+class ArticleDocument(ElasticsearchDocument):
+    index_name = "articles"
+
+    title: str
+    content: str
+
+
+adapter = ElasticsearchAdapter(client, refresh="wait_for")
+articles = ModelRepository(adapter, ArticleDocument)
+
+created = await articles.create_item(
+    {"id": "quickstart", "title": "ormate", "content": "pluggable adapters"}
+)
+matched = await articles.read_items({"match": {"content": "adapters"}}, limit=10)
+updated = await articles.update_item_by_primary_key("quickstart", {"title": "ormate 0.1"})
+deleted = await articles.delete_item_by_primary_key("quickstart")
+```
+
+完整的索引初始化、CRUD、计数、聚合和客户端关闭示例在 `examples/elasticsearch.py`：
+
+```bash
+ELASTICSEARCH_URL=http://localhost:9200 uv run python examples/elasticsearch.py
+```
+
+全文检索和聚合等 ES 专属操作直接通过 `ElasticsearchAdapter` 调用。Elasticsearch 不参与 SQL 事务；SQL 与 ES 双写需要使用 outbox、消息队列或补偿机制。
+
+## Repository 和 Adapter
+
+`ModelRepository` 提供以下通用操作：
+
+- 单项和批量创建
+- 条件查询、主键查询和批量主键查询
+- 条件更新和删除
+- `count`、`exists`、`limit`、`offset`
+- 后端原生命令执行
+
+SQLAlchemy/SQLModel 额外支持复合主键。后端特有的能力不放进通用协议，例如 SQL JOIN 和 ES 聚合分别留在对应 Adapter 中。
+
+实现 `StorageAdapter` 协议可以接入其他存储：
+
+```python
+repository = ModelRepository(custom_adapter, CustomModel, CustomRead)
+```
+
+Adapter 负责持久化、查询、主键条件和存储名称。Repository 负责输入转换、`encode_for_storage()`、`decode_from_storage()` 和 ReadModel 构造。
+
+ormate 不定义 `id`、`created_at`、`updated_at` 等业务字段。SQLAlchemy/SQLModel 继续使用 `__tablename__`，Elasticsearch 使用 `index_name`，统一名称可以从 Repository 获取：
+
+```python
+repository.storage_name
+```
+
+`ElasticsearchDocument.id` 只用于映射 Elasticsearch `_id`。
+
+## Web 中间件
+
+```python
+from ormate.web import DBSessionMiddleware
+
+app.add_middleware(
+    DBSessionMiddleware,
+    db=db,
+    rollback_on_http_error=True,
+)
+```
+
+中间件接受 `AsyncDatabase` 或 `AsyncEngine`，为每个 HTTP/WebSocket 请求建立独立会话作用域。
+
+## 当前限制
+
+- PostgreSQL、MySQL 和真实 Elasticsearch 集群尚未加入自动化集成测试。
+- Elasticsearch 条件批量更新和删除受 `default_size` 限制，默认最多处理 1000 个匹配文档。
+- ES mapping 迁移、bulk、PIT/search_after 和乐观并发控制尚未实现。
+- 不提供 SQL 与 Elasticsearch 之间的分布式事务。
+
+## 路线图
+
+`0.1.x` 用于完成首次 PyPI 发布，当前还需要经过 TestPyPI 安装验证。
+
+`0.2` 主要完善 Elasticsearch：bulk 写入、PIT/search_after、索引 mapping 管理、并发冲突处理和真实集群测试。
+
+`0.3` 主要完善关系型数据库：PostgreSQL/MySQL 测试矩阵、分页结果类型、显式 savepoint API 和批量性能优化。
+
+后续会补充 Adapter 契约测试工具，并评估 MongoDB、RedisJSON 以及 SQL 到 ES 的 outbox 示例。到 `1.0` 前会冻结公共 API，补齐迁移指南和性能基准。
+
+路线图只表示开发方向，不承诺具体发布日期。
+
+## 开发
+
+```bash
+uv sync --all-extras
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+uv run twine check dist/*
+```
+
+发布步骤见 `docs/publishing.md`。
+
+## License
+
+[MIT License](LICENSE)
+

ormate-0.1.0/README.md

@@ -0,0 +1,211 @@
+# ormate
+
+ormate 是一个异步 Repository 工具包，用同一套 CRUD 接口访问 SQLAlchemy、SQLModel 和 Elasticsearch。Repository 负责输入输出模型转换，Adapter 负责具体的存储操作和查询语法。
+
+项目目前处于 `0.1.0` 阶段，API 在 `1.0` 前仍可能调整。
+
+## 安装
+
+需要 Python 3.13 或更高版本。核心包只依赖 SQLAlchemy：
+
+```bash
+pip install ormate
+```
+
+其他依赖按需安装：
+
+```bash
+pip install "ormate[sqlite]"
+pip install "ormate[sqlmodel]"
+pip install "ormate[postgresql]"
+pip install "ormate[mysql]"
+pip install "ormate[elasticsearch]"
+pip install "ormate[web]"
+```
+
+## SQLAlchemy
+
+```python
+from pydantic import BaseModel
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from ormate import AsyncDatabase, ModelRepository, SQLAlchemyAdapter
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str]
+
+
+class UserCreate(BaseModel):
+    id: int
+    name: str
+
+
+class UserRead(BaseModel):
+    id: int
+    name: str
+
+
+db = AsyncDatabase.create("sqlite+aiosqlite:///app.db")
+repository = ModelRepository(SQLAlchemyAdapter(db), User, UserRead)
+
+async with db.engine.begin() as connection:
+    await connection.run_sync(Base.metadata.create_all)
+
+created = await repository.create_item(UserCreate(id=1, name="Ada"))
+loaded = await repository.read_item_by_primary_key(1)
+updated = await repository.update_item_by_primary_key(1, {"name": "Grace"})
+deleted = await repository.delete_item_by_primary_key(1)
+```
+
+Create 和 Update 参数可以是字典，也可以是实现了 `model_dump(exclude_unset=True)` 的 Pydantic/SQLModel 对象。传入 ReadModel 时，该模型需要提供 `model_validate()`；不传则返回存储模型。
+
+SQLAlchemy 条件查询直接使用 SQLAlchemy 表达式：
+
+```python
+users = await repository.read_items(User.name.contains("Ada"), limit=20)
+total = await repository.count(User.name.contains("Ada"))
+```
+
+## SQLModel 与事务
+
+`SQLModelAdapter` 继承 `SQLAlchemyAdapter`，两者使用相同的 Session 和事务实现。绑定到同一个 `Database` 后，SQLAlchemy 和 SQLModel 的操作可以放在同一个事务中：
+
+```python
+audit_logs = ModelRepository(SQLAlchemyAdapter(db), AuditLog)
+tasks = ModelRepository(SQLModelAdapter(db), Task)
+
+async with db:
+    await audit_logs.create_item({"id": 1, "message": "task created"})
+    await tasks.create_item({"title": "publish package"})
+```
+
+作用域正常退出时提交，发生异常时回滚。同步代码可以使用 `Database` 和 `with db:`。
+
+相关示例：
+
+- `examples/async_sqlalchemy.py`
+- `examples/sync_sqlalchemy.py`
+- `examples/async_sqlmodel.py`
+- `examples/shared_transaction.py`
+
+## Elasticsearch
+
+Elasticsearch 使用 Pydantic 文档模型，查询参数保持原生 Query DSL：
+
+```python
+from ormate import ModelRepository
+from ormate.elasticsearch import ElasticsearchAdapter, ElasticsearchDocument
+
+
+class ArticleDocument(ElasticsearchDocument):
+    index_name = "articles"
+
+    title: str
+    content: str
+
+
+adapter = ElasticsearchAdapter(client, refresh="wait_for")
+articles = ModelRepository(adapter, ArticleDocument)
+
+created = await articles.create_item(
+    {"id": "quickstart", "title": "ormate", "content": "pluggable adapters"}
+)
+matched = await articles.read_items({"match": {"content": "adapters"}}, limit=10)
+updated = await articles.update_item_by_primary_key("quickstart", {"title": "ormate 0.1"})
+deleted = await articles.delete_item_by_primary_key("quickstart")
+```
+
+完整的索引初始化、CRUD、计数、聚合和客户端关闭示例在 `examples/elasticsearch.py`：
+
+```bash
+ELASTICSEARCH_URL=http://localhost:9200 uv run python examples/elasticsearch.py
+```
+
+全文检索和聚合等 ES 专属操作直接通过 `ElasticsearchAdapter` 调用。Elasticsearch 不参与 SQL 事务；SQL 与 ES 双写需要使用 outbox、消息队列或补偿机制。
+
+## Repository 和 Adapter
+
+`ModelRepository` 提供以下通用操作：
+
+- 单项和批量创建
+- 条件查询、主键查询和批量主键查询
+- 条件更新和删除
+- `count`、`exists`、`limit`、`offset`
+- 后端原生命令执行
+
+SQLAlchemy/SQLModel 额外支持复合主键。后端特有的能力不放进通用协议，例如 SQL JOIN 和 ES 聚合分别留在对应 Adapter 中。
+
+实现 `StorageAdapter` 协议可以接入其他存储：
+
+```python
+repository = ModelRepository(custom_adapter, CustomModel, CustomRead)
+```
+
+Adapter 负责持久化、查询、主键条件和存储名称。Repository 负责输入转换、`encode_for_storage()`、`decode_from_storage()` 和 ReadModel 构造。
+
+ormate 不定义 `id`、`created_at`、`updated_at` 等业务字段。SQLAlchemy/SQLModel 继续使用 `__tablename__`，Elasticsearch 使用 `index_name`，统一名称可以从 Repository 获取：
+
+```python
+repository.storage_name
+```
+
+`ElasticsearchDocument.id` 只用于映射 Elasticsearch `_id`。
+
+## Web 中间件
+
+```python
+from ormate.web import DBSessionMiddleware
+
+app.add_middleware(
+    DBSessionMiddleware,
+    db=db,
+    rollback_on_http_error=True,
+)
+```
+
+中间件接受 `AsyncDatabase` 或 `AsyncEngine`，为每个 HTTP/WebSocket 请求建立独立会话作用域。
+
+## 当前限制
+
+- PostgreSQL、MySQL 和真实 Elasticsearch 集群尚未加入自动化集成测试。
+- Elasticsearch 条件批量更新和删除受 `default_size` 限制，默认最多处理 1000 个匹配文档。
+- ES mapping 迁移、bulk、PIT/search_after 和乐观并发控制尚未实现。
+- 不提供 SQL 与 Elasticsearch 之间的分布式事务。
+
+## 路线图
+
+`0.1.x` 用于完成首次 PyPI 发布，当前还需要经过 TestPyPI 安装验证。
+
+`0.2` 主要完善 Elasticsearch：bulk 写入、PIT/search_after、索引 mapping 管理、并发冲突处理和真实集群测试。
+
+`0.3` 主要完善关系型数据库：PostgreSQL/MySQL 测试矩阵、分页结果类型、显式 savepoint API 和批量性能优化。
+
+后续会补充 Adapter 契约测试工具，并评估 MongoDB、RedisJSON 以及 SQL 到 ES 的 outbox 示例。到 `1.0` 前会冻结公共 API，补齐迁移指南和性能基准。
+
+路线图只表示开发方向，不承诺具体发布日期。
+
+## 开发
+
+```bash
+uv sync --all-extras
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+uv run twine check dist/*
+```
+
+发布步骤见 `docs/publishing.md`。
+
+## License
+
+[MIT License](LICENSE)
+

ormate-0.1.0/docs/publishing.md

@@ -0,0 +1,33 @@
+# 发布 ormate
+
+## 发布前检查
+
+```bash
+uv sync --all-extras
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv build
+uv run twine check dist/*
+```
+
+版本号必须同时更新 `pyproject.toml` 和 `CHANGELOG.md`。发布前确认 PyPI 上发行名仍可用。
+
+## TestPyPI 验证
+
+不要把令牌写入仓库。令牌通过环境变量或交互式提示提供。
+
+```bash
+uv publish --publish-url https://test.pypi.org/legacy/ dist/*
+uv run --isolated --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --with ormate python -c "import ormate; print(ormate.__all__)"
+```
+
+## PyPI 发布
+
+TestPyPI 安装和冒烟验证通过后执行：
+
+```bash
+uv publish dist/*
+```
+
+长期维护建议在代码托管平台配置 PyPI Trusted Publishing，避免持久化 API Token。

ormate-0.1.0/examples/async_sqlalchemy.py

@@ -0,0 +1,41 @@
+import asyncio
+
+from pydantic import BaseModel
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from ormate import AsyncDatabase, ModelRepository, SQLAlchemyAdapter
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Note(Base):
+    __tablename__ = "notes"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    text: Mapped[str]
+
+
+class NoteRead(BaseModel):
+    id: int
+    text: str
+
+
+async def main() -> None:
+    db = AsyncDatabase.create("sqlite+aiosqlite:///notes.db")
+    async with db.engine.begin() as connection:
+        await connection.run_sync(Base.metadata.create_all)
+
+    notes = ModelRepository(SQLAlchemyAdapter(db), Note, NoteRead)
+    async with db:
+        await notes.create_item({"id": 1, "text": "first"})
+        await notes.create_item({"id": 2, "text": "second"})
+
+    print(await notes.read_items())
+    await db.dispose()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+

ormate-0.1.0/examples/async_sqlmodel.py

@@ -0,0 +1,36 @@
+import asyncio
+
+from sqlmodel import Field, SQLModel
+
+from ormate import AsyncDatabase, ModelRepository, SQLModelAdapter
+
+
+class NoteRead(SQLModel):
+    id: int
+    text: str
+
+
+class Note(SQLModel, table=True):
+    __tablename__ = "notes"
+
+    id: int | None = Field(default=None, primary_key=True)
+    text: str
+
+
+async def main() -> None:
+    db = AsyncDatabase.create("sqlite+aiosqlite:///notes.db")
+    async with db.engine.begin() as connection:
+        await connection.run_sync(SQLModel.metadata.create_all)
+    adapter = SQLModelAdapter(db)
+    notes = ModelRepository(adapter, Note, NoteRead)
+
+    async with db:
+        await notes.create_item({"text": "first"})
+        await notes.create_item({"text": "second"})
+
+    print(await notes.read_items())
+    await db.dispose()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())