SQLModel 教程：使用 Python 类型注解定义数据模型与数据库操作

SQLModel 教程：使用 Python 类型注解定义数据模型与数据库操作

sqlmodel SQL databases in Python, designed for simplicity, compatibility, and robustness. 项目地址: https://gitcode.com/gh_mirrors/sq/sqlmodel

SQLModel 是一个基于 Python 类型注解的 ORM 工具，它结合了 SQLAlchemy 和 Pydantic 的优点，让开发者能够用简洁的 Python 代码定义数据模型并执行数据库操作。本文将详细解析一个使用 SQLModel 的完整示例，帮助开发者快速上手这个强大的工具。

数据模型定义

在 SQLModel 中，我们通过继承 SQLModel 类并添加 table=True 参数来定义数据模型。以下是一个英雄(Hero)模型的示例：

class Hero(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str = Field(index=True)
    secret_name: str
    age: Optional[int] = Field(default=None, index=True)

这个模型定义了几个关键点：

1. id 字段被标记为主键(primary_key)，类型为可选的整数
2. name 字段是必填的字符串类型，并创建了数据库索引(index=True)
3. secret_name 是必填的字符串类型，但没有索引
4. age 是可选的整数类型，也创建了索引

数据库连接配置

SQLModel 使用 SQLAlchemy 的引擎(Engine)来管理数据库连接。以下代码配置了一个 SQLite 数据库：

sqlite_file_name = "database.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"
engine = create_engine(sqlite_url, echo=True)

echo=True 参数会在控制台输出执行的 SQL 语句，这在开发阶段非常有用。

数据库表创建

使用 SQLModel 的元数据可以轻松创建数据库表：

def create_db_and_tables():
    SQLModel.metadata.create_all(engine)

这个方法会检查所有继承自 SQLModel 且设置了 table=True 的模型，并在数据库中创建对应的表结构。

数据操作

插入数据

创建英雄记录非常简单，只需实例化 Hero 类然后通过会话(Session)添加到数据库：

def create_heroes():
    hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
    # 其他英雄实例...
    
    with Session(engine) as session:
        session.add(hero_1)
        # 添加其他英雄...
        session.commit()

使用上下文管理器(with语句)可以确保会话正确关闭，commit() 方法将更改永久保存到数据库。

查询数据

SQLModel 提供了直观的查询接口，以下示例查询年龄不超过35岁的英雄：

def select_heroes():
    with Session(engine) as session:
        statement = select(Hero).where(Hero.age <= 35)
        results = session.exec(statement)
        hero = results.one()
        print("Hero:", hero)

select() 函数构建查询语句，where() 方法添加过滤条件，exec() 执行查询，one() 确保只返回一条记录(如果有多条会抛出异常)。

主程序流程

完整的示例程序遵循以下流程：

1. 创建数据库和表结构
2. 插入示例数据
3. 执行查询并输出结果

def main():
    create_db_and_tables()
    create_heroes()
    select_heroes()

总结

通过这个示例，我们可以看到 SQLModel 的几个显著优势：

1. 类型安全：利用 Python 类型注解，在编码阶段就能发现类型错误
2. 简洁直观：模型定义和数据库操作都非常直观易懂
3. 强大灵活：结合了 SQLAlchemy 的数据库能力和 Pydantic 的数据验证
4. 开发友好：自动生成的 SQL 语句和清晰的错误信息加速开发过程

SQLModel 特别适合需要快速开发且重视代码质量的 Python 项目，它减少了样板代码，让开发者能更专注于业务逻辑的实现。

sqlmodel SQL databases in Python, designed for simplicity, compatibility, and robustness. 项目地址: https://gitcode.com/gh_mirrors/sq/sqlmodel