SQLModel 入门教程：创建模型与数据库操作

SQLModel 入门教程：创建模型与数据库操作

还在为Python中繁琐的SQL数据库操作而烦恼？SQLModel让你用Python类轻松操作数据库，告别重复代码！本文将带你从零开始掌握SQLModel的核心用法，让你在10分钟内就能创建数据模型并进行数据库操作。

什么是SQLModel？

SQLModel是一个基于Python类型注解的SQL数据库交互库，它结合了Pydantic的数据验证能力和SQLAlchemy的数据库操作功能。通过简单的Python类定义，你就能自动生成数据库表结构，实现对象关系映射（ORM，Object-Relational Mapping）。

核心优势

• 极简代码：一个类定义同时完成数据验证和表结构定义
• 类型安全：完整的Python类型注解支持，编辑器智能提示
• 无缝兼容：与FastAPI、Pydantic、SQLAlchemy完美集成
• 零重复：避免在Pydantic模型和SQLAlchemy模型间重复定义

环境准备

在开始之前，确保你已经安装了Python 3.8+版本，然后创建虚拟环境并安装SQLModel：

python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows
pip install sqlmodel

创建第一个数据模型

让我们从一个简单的英雄（Hero）数据模型开始，这个模型将对应数据库中的hero表：

from sqlmodel import Field, SQLModel

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

模型结构解析

让我们用表格来分析这个模型的各个部分：

字段类型详解

1. 主键字段 (Primary Key)

id: int | None = Field(default=None, primary_key=True)

• int | None：表示字段可以是整数或None
• Field()：SQLModel的字段配置函数
• primary_key=True：标记该字段为主键
• default=None：默认值为None，由数据库自动生成

2. 必填字段 (Required Fields)

name: str
secret_name: str

这些字段没有默认值，在创建实例时必须提供，对应数据库中的NOT NULL约束。

3. 可选字段 (Optional Fields)

age: int | None = None

• int | None：可以是整数或None
• = None：默认值为None，创建实例时可省略

数据库连接配置

创建好模型后，我们需要配置数据库连接：

from sqlmodel import create_engine

# SQLite数据库配置
sqlite_file_name = "database.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"

# 创建数据库引擎
engine = create_engine(sqlite_url, echo=True)

支持的数据库类型

SQLModel支持多种数据库，以下是常见的连接URL格式：

引擎配置参数

engine = create_engine(
    sqlite_url,
    echo=True,        # 打印执行的SQL语句
    pool_size=5,      # 连接池大小
    max_overflow=10,  # 最大溢出连接数
    pool_timeout=30,  # 连接超时时间(秒)
)

创建数据库表

有了模型和引擎，现在可以创建数据库表了：

from sqlmodel import SQLModel

# 创建所有已定义模型对应的表
SQLModel.metadata.create_all(engine)

这个过程可以用以下流程图表示：

表创建过程详解

1. 模型注册：每个带有table=True的SQLModel类都会自动注册到SQLModel.metadata中
2. SQL生成：根据模型定义生成对应的CREATE TABLE语句
3. 语句执行：通过引擎执行生成的SQL语句
4. 表结构验证：确保生成的表结构符合模型定义

完整示例代码

让我们来看一个完整的示例，包含模型定义、数据库连接和表创建：

from sqlmodel import Field, SQLModel, create_engine

# 1. 定义数据模型
class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: int | None = None

# 2. 配置数据库连接
sqlite_file_name = "database.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"
engine = create_engine(sqlite_url, echo=True)

# 3. 创建数据库表
def create_db_and_tables():
    SQLModel.metadata.create_all(engine)

# 4. 主程序入口
if __name__ == "__main__":
    create_db_and_tables()
    print("数据库表创建完成！")

模型的高级特性

1. 字段约束配置

SQLModel支持丰富的字段约束配置：

from sqlmodel import Field
from typing import Optional
import datetime

class User(SQLModel, table=True):
    id: int = Field(default=None, primary_key=True)
    username: str = Field(max_length=50, unique=True)
    email: str = Field(max_length=100, unique=True, index=True)
    password: str = Field(min_length=6)
    created_at: datetime.datetime = Field(default_factory=datetime.datetime.now)
    is_active: bool = Field(default=True)
    score: float = Field(ge=0, le=100)  # 0-100之间的分数

2. 关系定义

SQLModel支持定义表之间的关系：

from sqlmodel import Field, Relationship
from typing import List, Optional

class Team(SQLModel, table=True):
    id: int = Field(default=None, primary_key=True)
    name: str = Field(index=True)
    heroes: List["Hero"] = Relationship(back_populates="team")

class Hero(SQLModel, table=True):
    id: int = Field(default=None, primary_key=True)
    name: str = Field(index=True)
    team_id: Optional[int] = Field(default=None, foreign_key="team.id")
    team: Optional[Team] = Relationship(back_populates="heroes")

最佳实践建议

1. 项目结构组织

推荐的项目结构：

my_project/
├── models/          # 数据模型定义
│   ├── __init__.py
│   ├── user.py
│   ├── hero.py
│   └── team.py
├── database.py      # 数据库配置
├── main.py          # 主程序
└── requirements.txt

2. 数据库配置分离

将数据库配置单独放在一个文件中：

# database.py
from sqlmodel import SQLModel, create_engine
from .models import Hero, User, Team  # 导入所有模型

DATABASE_URL = "sqlite:///database.db"
engine = create_engine(DATABASE_URL, echo=True)

def init_db():
    """初始化数据库"""
    SQLModel.metadata.create_all(engine)

3. 错误处理

添加适当的错误处理机制：

from sqlalchemy.exc import SQLAlchemyError

def safe_create_tables():
    try:
        SQLModel.metadata.create_all(engine)
        print("表创建成功")
    except SQLAlchemyError as e:
        print(f"表创建失败: {e}")
    except Exception as e:
        print(f"未知错误: {e}")

常见问题解答

Q: 如何修改已有表结构？

A: SQLModel的create_all()方法只会创建不存在的表，不会修改已有表。对于表结构修改，需要使用数据库迁移工具如Alembic。

Q: 支持哪些数据库类型？

A: SQLModel支持所有SQLAlchemy支持的数据库，包括SQLite、PostgreSQL、MySQL、Oracle、SQL Server等。

Q: 如何设置字符串字段的最大长度？

A: 使用Field(max_length=100)来限制字符串字段的最大长度。

Q: 能否使用自定义的列名？

A: 可以，使用Field(sa_column=Column("custom_name", String))来指定自定义列名。

总结

通过本教程，你已经掌握了SQLModel的核心概念和基本用法：

1. 模型定义：使用Python类定义数据库表结构
2. 字段配置：通过Field函数配置字段属性和约束
3. 数据库连接：使用create_engine创建数据库引擎
4. 表创建：通过metadata.create_all自动创建表

SQLModel的强大之处在于它的简洁性和兼容性，让你能够用最少的代码实现完整的数据库操作。无论是简单的CRUD操作还是复杂的关系映射，SQLModel都能提供优雅的解决方案。

在接下来的教程中，我们将深入探讨数据操作、查询、关系管理以及如何与FastAPI集成等内容。现在就开始使用SQLModel，让你的数据库操作变得更加Pythonic吧！

提示：在实际项目中，建议结合使用Alembic进行数据库迁移管理，以确保表结构变更的可控性和可追溯性。