SQLModel 两行核心代码完整解读python运行from sqlmodel import SQLModel, create_engine # 1. 创建数据库引擎 engine create_engine(sqlite:///demo.db) # 2. 根据模型元数据自动创建数据库表 SQLModel.metadata.create_all(engine)依赖pip install sqlmodelSQLModel 底层封装 SQLAlchemySQLModel.metadata就是 SQLAlchemy 的 MetaData 对象。①engine create_engine(数据库连接串)python运行engine create_engine(sqlite:///demo.db)作用创建数据库引擎对象它是应用和数据库之间的连接入口并不立刻连接数据库只是保存连接配置惰性连接真正执行 SQL 时才建立连接。常见数据库连接字符串python运行# SQLite 文件数据库本地文件无需服务 engine create_engine(sqlite:///demo.db) # MySQL engine create_engine(mysqlpymysql://user:password127.0.0.1:3306/dbname) # PostgreSQL engine create_engine(postgresql://user:password127.0.0.1:5432/dbname)create_engine 常用参数python运行engine create_engine( sqlite:///demo.db, echoTrue, # echoTrue打印所有执行的SQL语句调试用生产关闭 pool_size5, # 连接池大小同时保持多少个数据库连接 max_overflow10, # 连接池满了最多额外新增连接 )echoTrue开发调试神器可以看到 ORM 底层生成的原始 SQL。engine 本身不代表一个连接是连接池管理器session 从 engine 拿连接。②SQLModel.metadata.create_all(engine)python运行SQLModel.metadata.create_all(engine)核心功能扫描所有继承自SQLModel的表模型自动在数据库里创建数据表。只建表不会删表不会更新表结构拆解名词SQLModel.metadataMetadata 是元数据容器所有继承SQLModel的数据库模型带tableTrue会自动把表结构信息注册到这个 metadata 对象中。示例模型python运行class Hero(SQLModel, tableTrue): # tableTrue 代表这是数据库表模型 id: int | None Field(defaultNone, primary_keyTrue) name: str age: int只要定义了tableTrue的模型表结构就会存入SQLModel.metadata。.create_all(engine)接收 engine使用引擎去连接数据库读取 metadata 里面全部表定义判断表是否已经存在已经存在就跳过不会覆盖不会修改字段⚠️重要限制 ✅ 新增表可以自动创建 ❗不会做迁移如果你修改模型字段加字段、改字段类型再次执行create_all()什么都不会做不会自动更新已有表。表变更要用 Alembic 做数据库迁移工具。执行时机一般放在程序启动时运行一次只执行建表不插入任何数据不会删除旧表是安全的重复调用不会报错。对应反向操作删除所有表测试环境慎用python运行SQLModel.metadata.drop_all(engine)会删除 metadata 中注册的全部数据表生产环境绝对禁止。完整可运行最小示例python运行from sqlmodel import SQLModel, create_engine, Field # 1. 定义数据库模型tableTrue 标记为数据库表 class User(SQLModel, tableTrue): id: int | None Field(defaultNone, primary_keyTrue) username: str password: str # 2. 创建数据库引擎 engine create_engine(sqlite:///test.db, echoTrue) # 3. 自动创建所有数据表 SQLModel.metadata.create_all(engine) print(数据表创建完成)运行后项目目录会生成test.dbsqlite 数据库文件里面生成user表。高频踩坑点坑 1模型没有被加载表不会创建如果你的模型写在别的 py 文件没有 import 导入到当前脚本SQLModel.metadata看不到模型create_all执行后不会生成表。必须 import 所有tableTrue的模型让类执行注册到 metadata。坑 2修改字段后create_all 不会更新表python运行# 原来 class User(SQLModel, tableTrue): id: int|NoneField(None, primary_keyTrue) username: str # 修改后新增 age 字段再次运行 create_all()数据库不会新增age列 class User(SQLModel, tableTrue): id: int|NoneField(None, primary_keyTrue) username: str age: int | None解决方案生产用Alembic迁移工具开发阶段可以删库重建。坑 3create_all只是 DDL 建表不开启会话建表完成后增删改查依然需要创建Sessionpython运行from sqlmodel import Session with Session(engine) as session: u User(usernamezhangsan, password123456) session.add(u) session.commit()整体流程总结create_engine()创建数据库连接管理器引擎配置连接参数。定义XXX(SQLModel, tableTrue)把表结构注册到SQLModel.metadata。SQLModel.metadata.create_all(engine)连接数据库把 metadata 里所有不存在的表执行 CREATE TABLE SQL。后续业务用Session(engine)做 CRUD。和 SQLAlchemy 对照SQLModel 是对 SQLAlchemy 的封装SQLModel.metadata≈DeclarativeBase.metadataSQLModel.metadata.create_all(engine)≈ SQLAlchemy 原生Base.metadata.create_all(engine)
