Ormar 入门指南：快速掌握异步 Python ORM 的终极教程

尤迅兰Livia

854人浏览 · 2026-05-19 08:59:49

尤迅兰Livia · 2026-05-19 08:59:49 发布

Ormar 入门指南：快速掌握异步 Python ORM 的终极教程

【免费下载链接】ormar python async orm with fastapi in mind and pydantic validation 项目地址: https://gitcode.com/gh_mirrors/or/ormar

Ormar 是一款专为异步 Python 应用设计的强大 ORM（对象关系映射）工具，特别针对 FastAPI 框架优化，并深度集成 Pydantic 验证功能。作为一款轻量级但功能全面的异步 ORM，Ormar 让开发者能够轻松处理数据库操作，同时保持代码的简洁性和高性能。无论是构建 RESTful API 还是开发数据驱动的应用，Ormar 都能提供直观且高效的数据库交互体验。

为什么选择 Ormar？异步 ORM 的核心优势

在现代 Python 开发中，异步编程已成为提升应用性能的关键技术。Ormar 作为异步 ORM 的佼佼者，具备以下核心优势：

原生异步支持：完全基于 async/await 语法设计，完美适配异步 Web 框架如 FastAPI
Pydantic 深度集成：自带强大的数据验证功能，减少重复代码
简洁直观的 API：提供类 SQL 的查询语法，降低学习曲线
自动表生成：通过模型定义自动创建数据库表结构，加速开发流程
灵活的关系管理：轻松处理一对一、一对多和多对多关系

这些特性使 Ormar 成为快速开发高性能异步应用的理想选择，尤其适合需要处理大量并发请求的 Web 服务。

快速开始：Ormar 的安装与环境配置

要开始使用 Ormar，首先需要安装必要的依赖。Ormar 支持多种数据库后端，包括 PostgreSQL、MySQL 和 SQLite。以下是基本安装步骤：

安装 Ormar：通过 pip 或 poetry 安装核心包

pip install ormar
# 或使用 poetry
poetry add ormar

安装数据库驱动：根据您选择的数据库安装相应驱动

# PostgreSQL
pip install asyncpg
# MySQL
pip install aiomysql
# SQLite
pip install aiosqlite

配置数据库连接：在应用初始化时设置数据库连接参数

import ormar
from databases import Database

database = Database("sqlite:///test.db")
metadata = ormar.MetaData(database=database)

完整的安装指南可参考项目文档 docs/install.md，其中包含更多高级配置选项和环境设置建议。

核心概念：Ormar 模型定义与数据库表创建

Ormar 的核心是数据模型，它映射到数据库中的表。模型定义同时兼顾了数据结构和验证规则，这得益于 Pydantic 的强大支持。

基本模型定义

以下是一个简单的用户模型示例：

import ormar
from datetime import datetime

class User(ormar.Model):
    class Meta:
        tablename = "users"
        metadata = metadata  # 引用之前定义的 metadata

    id: int = ormar.Integer(primary_key=True)
    username: str = ormar.String(max_length=100, unique=True)
    email: str = ormar.String(max_length=255, unique=True)
    created_at: datetime = ormar.DateTime(default=datetime.utcnow)

在模型定义中，Meta 类包含数据库相关配置，而类属性则定义表字段。每个字段类型（如 Integer、String）都对应特定的数据库类型和验证规则。

表创建

定义模型后，可以通过以下方式创建数据库表：

# 创建所有模型对应的表
await User.metadata.create_all()

# 或创建单个模型的表
await User.ormar_config.table.create()

注意：表创建操作通常只需要执行一次，可以在应用初始化或专用的迁移脚本中完成。详细的迁移策略请参考 docs/models/migrations.md。

数据库操作：轻松实现 CRUD 功能

Ormar 提供了直观的 API 来执行常见的数据库操作，所有操作均支持异步调用。

创建记录

# 创建新用户
user = await User(username="johndoe", email="john@example.com").save()

查询记录

# 获取单个用户
user = await User.objects.get(username="johndoe")

# 过滤查询
admins = await User.objects.filter(is_admin=True).all()

# 排序和分页
recent_users = await User.objects.order_by("-created_at").limit(10).offset(20).all()

更新记录

# 更新用户信息
user.email = "new_email@example.com"
await user.save()

# 批量更新
await User.objects.filter(is_active=False).update(is_deleted=True)

删除记录

# 删除单个用户
await user.delete()

# 批量删除
await User.objects.filter(created_at__lt=datetime(2023, 1, 1)).delete()

更多查询操作和高级过滤技巧可以在 docs/queries/filter-and-sort.md 中找到详细说明。

关系管理：处理表之间的关联

Ormar 简化了数据库表之间关系的定义和操作，支持常见的关系类型：

一对多关系

class Post(ormar.Model):
    class Meta:
        tablename = "posts"
        metadata = metadata

    id: int = ormar.Integer(primary_key=True)
    title: str = ormar.String(max_length=200)
    content: str = ormar.Text()
    author: User = ormar.ForeignKey(User, related_name="posts")

# 查询用户及其所有文章
user_with_posts = await User.objects.select_related("posts").get(id=1)
for post in user_with_posts.posts:
    print(post.title)

多对多关系

class Tag(ormar.Model):
    class Meta:
        tablename = "tags"
        metadata = metadata

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=50)

class Post(ormar.Model):
    # ... 其他字段 ...
    tags: list[Tag] = ormar.ManyToMany(Tag, related_name="posts")

# 添加标签到文章
tag = await Tag(name="python").save()
post = await Post.objects.get(id=1)
await post.tags.add(tag)

关系管理的完整指南和高级用法请参考 docs/relations/index.md。

与 FastAPI 集成：构建高性能 API

Ormar 与 FastAPI 的结合堪称完美，两者都基于 Pydantic，提供无缝的数据验证和类型提示。

创建 FastAPI 端点

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class UserCreate(BaseModel):
    username: str
    email: str

@app.post("/users/")
async def create_user(user: UserCreate):
    db_user = await User(**user.dict()).save()
    return db_user

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    return await User.objects.get(id=user_id)

这种集成不仅简化了代码，还自动生成了带有类型提示的 API 文档。更多 FastAPI 集成示例可以在 docs/fastapi/index.md 中找到。