Python SQLAlchemy ORM 完整使用流程附实战代码图文说明前言SQLAlchemy 是 Python 中最常用的 ORM对象关系映射框架核心优势是将 Python 类与数据库表进行映射无需编写原生 SQL 语句就能完成数据库的增删改查操作大幅提升开发效率、降低代码冗余。本文将从安装到实战一步步讲解 SQLAlchemy ORM 的完整使用流程代码可直接复制运行新手也能快速上手。目录1. 环境准备安装 SQLAlchemy2. SQLAlchemy ORM 核心流程拆解3. 完整实战代码附详细注释4. 关键注意事项避坑指南5. 常见问题排查1. 环境准备安装 SQLAlchemy首先需要安装 SQLAlchemy 框架同时根据自己使用的数据库如 MySQL、SQLite、PostgreSQL安装对应的数据库驱动本文以 MySQL 和 SQLite 为例覆盖大部分开发场景。1.1 安装命令pip 方式# 安装 SQLAlchemy 核心框架pipinstallsqlalchemy# 若使用 MySQL需安装 pymysql 驱动本文实战用这个pipinstallpymysql# 若使用 SQLite无需额外安装驱动Python 自带# 若使用 PostgreSQL安装 psycopg2-binary# pip install psycopg2-binary1.2 导入核心模块安装完成后在代码中导入 SQLAlchemy ORM 所需的核心模块后续所有操作都基于这些模块展开# 导入数据库连接引擎、字段类型fromsqlalchemyimportcreate_engine,Column,Integer,String,DateTime# 导入 ORM 基类所有模型类必须继承fromsqlalchemy.ext.declarativeimportdeclarative_base# 导入会话工厂操作数据库的入口fromsqlalchemy.ormimportsessionmaker# 可选导入时间模块用于设置默认时间fromdatetimeimportdatetime2. SQLAlchemy ORM 核心流程拆解SQLAlchemy ORM 的使用流程非常固定核心分为 5 个步骤记住这个流程就能应对绝大多数数据库操作场景如下图所示配图建议用思维导图或流程图展示可参考下方文字流程绘制步骤1创建数据库连接引擎EngineEngine 是 SQLAlchemy 与数据库之间的连接核心负责管理数据库连接池、执行 SQL 语句底层自动处理无需我们手动管理连接。不同数据库的引擎连接格式不同本文给出最常用的 2 种MySQL 和 SQLite直接替换参数即可使用# 方式1MySQL 连接推荐实际开发常用# 格式mysqlpymysql://用户名:密码主机地址:端口号/数据库名?字符集enginecreate_engine(mysqlpymysql://root:123456localhost:3306/test_db?charsetutf8mb4,echoTrue,# echoTrue 表示打印底层执行的 SQL 语句便于调试生产环境可关闭pool_size5,# 连接池大小默认5可根据需求调整max_overflow10# 连接池最大溢出数超出pool_size的临时连接数)# 方式2SQLite 连接无需安装驱动适合本地测试、小型项目# 格式sqlite:///数据库文件路径相对路径/绝对路径# engine create_engine(sqlite:///test.db, echoTrue)注意MySQL 连接时需先确保本地 MySQL 服务已启动且已创建对应的数据库如上述的 test_db否则会报错。步骤2创建 ORM 基类Basedeclarative_base() 会创建一个基类所有需要映射到数据库表的 Python 类都必须继承这个基类。基类会自动管理所有子类模型后续的建表、查表等操作都依赖这个基类。# 创建 ORM 基类所有 ORM Model 继承此类classBase(DeclarativeBase):pass步骤3定义 ORM 模型映射数据库表这一步是 ORM 的核心将 Python 类与数据库表进行映射类名对应表名类的属性对应表的字段。模型类必须满足 2 个要求① 继承 Base 基类② 定义 __tablename__ 属性指定映射的数据库表名③ 至少定义一个主键字段primary_keyTrue。# 定义 User 模型映射数据库中的 users 表classUser(Base):# __tablename__指定映射的数据库表名必须有__tablename__users# 定义字段字段名 Column(字段类型, 约束条件)idColumn(Integer,primary_keyTrue,autoincrementTrue,comment用户ID主键自增)nameColumn(String(50),nullableFalse,comment用户名非空)ageColumn(Integer,nullableTrue,default18,comment用户年龄默认18)emailColumn(String(100),uniqueTrue,comment用户邮箱唯一)create_timeColumn(DateTime,defaultdatetime.now,comment创建时间默认当前时间)# 可根据需求定义多个模型如 Order、Product 等每个模型对应一张表classOrder(Base):__tablename__ordersorder_idColumn(Integer,primary_keyTrue,autoincrementTrue,comment订单ID)user_idColumn(Integer,comment关联用户ID与users表的id对应)order_nameColumn(String(100),nullableFalse,comment订单名称)步骤4创建数据库表通过 Base 基类的 metadata.create_all(engine) 方法会自动根据模型类在数据库中创建对应的表如果表已存在则不会重复创建避免覆盖数据。# 根据模型类自动创建数据库表若表已存在不重复创建Base.metadata.create_all(engine)执行这行代码后打开 MySQL 客户端如 Navicat、DBeaver就能看到 test_db 数据库中自动创建了 users 和 orders 两张表字段、约束、注释都与模型类一致。步骤5创建会话SessionSession 是 SQLAlchemy ORM 操作数据库的入口相当于一个“数据库操作会话”所有的增删改查操作都需要通过 Session 来完成同时 Session 负责管理事务提交、回滚。# 创建会话工厂绑定引擎Sessionsessionmaker(bindengine)# 创建一个会话实例每次操作数据库都需要创建会话sessionSession()步骤6通过 Session 执行增删改查操作会话创建完成后就可以通过 session 对象执行各种数据库操作无需编写原生 SQL全程用 Python 语法操作即可。6.1 新增数据insert# 方式1新增单条数据user1User(name张三,age22,emailzhangsan163.com)session.add(user1)# 将数据添加到会话# 方式2新增多条数据效率更高user2User(name李四,age25,emaillisi163.com)user3User(name王五,age20,emailwangwu163.com)session.add_all([user2,user3])# 批量添加# 注意此时数据还在会话中未写入数据库需要执行 commit() 提交事务session.commit()6.2 查询数据select查询是最常用的操作SQLAlchemy ORM 提供了丰富的查询方法以下是最常用的几种# 1. 查询所有数据返回列表元素是 User 对象all_userssession.query(User).all()foruserinall_users:print(f用户ID{user.id}用户名{user.name}邮箱{user.email})# 2. 查询单条数据返回第一个匹配的对象没有则返回 Noneusersession.query(User).filter(User.name张三).first()print(f查询到的用户{user.name}年龄{user.age})# 3. 条件查询多条件用 and_ / or_ 连接需导入fromsqlalchemyimportand_,or_ userssession.query(User).filter(and_(User.age20,User.name!张三)).all()# 4. 排序查询按 age 升序desc() 表示降序users_ordersession.query(User).order_by(User.age).all()# 升序# users_order session.query(User).order_by(User.age.desc()).all() # 降序# 5. 分页查询skip 跳过前2条limit 取3条适合分页场景users_pagesession.query(User).skip(2).limit(3).all()6.3 修改数据update修改数据的思路先查询到需要修改的对象再修改对象的属性最后提交事务。# 1. 先查询到需要修改的对象usersession.query(User).filter(User.name李四).first()ifuser:# 2. 修改对象的属性直接赋值即可user.age26user.emaillisi_new163.com# 3. 提交事务修改生效session.commit()print(修改成功)6.4 删除数据delete删除数据的思路先查询到需要删除的对象再通过 session.delete() 删除最后提交事务。# 1. 先查询到需要删除的对象usersession.query(User).filter(User.name王五).first()ifuser:# 2. 删除对象session.delete(user)# 3. 提交事务删除生效session.commit()print(删除成功)步骤7提交/回滚事务所有增删改操作都必须通过 session.commit() 提交事务才能真正写入数据库如果操作过程中出现错误可通过 session.rollback() 回滚事务恢复到操作前的状态。try:# 执行增删改操作userUser(name赵六,age28,emailzhaoliu163.com)session.add(user)# 提交事务session.commit()print(操作成功)exceptExceptionase:# 出现错误回滚事务session.rollback()print(f操作失败已回滚{str(e)})步骤8关闭会话数据库操作完成后必须关闭会话释放数据库连接避免连接泄露尤其是生产环境否则会导致数据库连接耗尽。# 关闭会话session.close()3. 完整实战代码附详细注释将上述所有步骤整合给出完整可运行的实战代码复制到 Python 文件中替换 MySQL 连接参数即可直接运行fromsqlalchemyimportcreate_engine,Column,Integer,String,DateTime,and_fromsqlalchemy.ext.declarativeimportdeclarative_basefromsqlalchemy.ormimportsessionmakerfromdatetimeimportdatetime# 1. 创建数据库引擎MySQL 连接替换为自己的数据库参数enginecreate_engine(mysqlpymysql://root:123456localhost:3306/test_db?charsetutf8mb4,echoTrue,pool_size5,max_overflow10)# 2. 创建 ORM 基类Basedeclarative_base()# 3. 定义模型类映射数据表classUser(Base):__tablename__usersidColumn(Integer,primary_keyTrue,autoincrementTrue,comment用户ID主键自增)nameColumn(String(50),nullableFalse,comment用户名非空)ageColumn(Integer,nullableTrue,default18,comment用户年龄默认18)emailColumn(String(100),uniqueTrue,comment用户邮箱唯一)create_timeColumn(DateTime,defaultdatetime.now,comment创建时间)# 4. 自动创建数据表若已存在则不创建Base.metadata.create_all(engine)# 5. 创建会话Sessionsessionmaker(bindengine)sessionSession()try:# 6. 增新增数据user1User(name张三,age22,emailzhangsan163.com)user2User(name李四,age25,emaillisi163.com)session.add_all([user1,user2])# 查查询数据all_userssession.query(User).all()print(所有用户)foruserinall_users:print(fID:{user.id}, 姓名:{user.name}, 邮箱:{user.email})# 改修改数据usersession.query(User).filter(User.name李四).first()ifuser:user.age26print(修改后李四的年龄,user.age)# 删删除数据注释掉避免误删需要时取消注释# user_del session.query(User).filter(User.name 张三).first()# if user_del:# session.delete(user_del)# print(删除成功)# 7. 提交事务session.commit()print(所有操作执行成功)exceptExceptionase:# 出错回滚session.rollback()print(f操作失败已回滚{str(e)})finally:# 8. 关闭会话无论成功失败都要关闭session.close()print(会话已关闭)4. 关键注意事项避坑指南⚠️ 会话管理每次操作数据库后必须关闭会话建议用 try-finally 确保关闭避免连接泄露。⚠️ 事务提交增删改操作必须执行 session.commit()否则数据不会写入数据库仅停留在会话中。⚠️ 模型约束定义模型时主键primary_key必须有unique唯一、nullable非空等约束要根据业务需求设置避免数据异常。⚠️ 数据库驱动使用 MySQL 必须安装 pymysql使用 PostgreSQL 必须安装 psycopg2-binary否则会报错“no module named xxx”。⚠️ echo 参数开发环境可设为 True打印 SQL便于调试生产环境建议设为 False避免日志冗余。5. 常见问题排查问题1连接 MySQL 时报错“Access denied for user #39;root#39;#39;localhost#39; (using password: YES)”解决方案检查 MySQL 用户名、密码是否正确检查 MySQL 服务是否已启动检查 root 用户是否有访问 test_db 数据库的权限。问题2创建表时报错“Table #39;users#39; already exists”解决方案Base.metadata.create_all(engine) 会自动判断表是否存在无需手动删除若确实需要重新建表可先删除原有表再执行建表语句生产环境慎用。问题3新增数据时报错“Duplicate entry #39;zhangsan163.com#39; for key #39;users.email#39;”解决方案email 字段设置了 uniqueTrue唯一约束避免重复插入相同邮箱可先查询邮箱是否已存在再执行新增操作。结尾以上就是 Python SQLAlchemy ORM 的完整使用流程从环境准备、引擎创建、模型定义到会话操作、增删改查覆盖了新手入门到实战的所有核心内容。掌握这个流程后就能轻松用 ORM 操作数据库摆脱原生 SQL 的繁琐。
Python SQLAlchemy ORM 完整使用流程（附代码+图文说明）
Python SQLAlchemy ORM 完整使用流程附实战代码图文说明前言SQLAlchemy 是 Python 中最常用的 ORM对象关系映射框架核心优势是将 Python 类与数据库表进行映射无需编写原生 SQL 语句就能完成数据库的增删改查操作大幅提升开发效率、降低代码冗余。本文将从安装到实战一步步讲解 SQLAlchemy ORM 的完整使用流程代码可直接复制运行新手也能快速上手。目录1. 环境准备安装 SQLAlchemy2. SQLAlchemy ORM 核心流程拆解3. 完整实战代码附详细注释4. 关键注意事项避坑指南5. 常见问题排查1. 环境准备安装 SQLAlchemy首先需要安装 SQLAlchemy 框架同时根据自己使用的数据库如 MySQL、SQLite、PostgreSQL安装对应的数据库驱动本文以 MySQL 和 SQLite 为例覆盖大部分开发场景。1.1 安装命令pip 方式# 安装 SQLAlchemy 核心框架pipinstallsqlalchemy# 若使用 MySQL需安装 pymysql 驱动本文实战用这个pipinstallpymysql# 若使用 SQLite无需额外安装驱动Python 自带# 若使用 PostgreSQL安装 psycopg2-binary# pip install psycopg2-binary1.2 导入核心模块安装完成后在代码中导入 SQLAlchemy ORM 所需的核心模块后续所有操作都基于这些模块展开# 导入数据库连接引擎、字段类型fromsqlalchemyimportcreate_engine,Column,Integer,String,DateTime# 导入 ORM 基类所有模型类必须继承fromsqlalchemy.ext.declarativeimportdeclarative_base# 导入会话工厂操作数据库的入口fromsqlalchemy.ormimportsessionmaker# 可选导入时间模块用于设置默认时间fromdatetimeimportdatetime2. SQLAlchemy ORM 核心流程拆解SQLAlchemy ORM 的使用流程非常固定核心分为 5 个步骤记住这个流程就能应对绝大多数数据库操作场景如下图所示配图建议用思维导图或流程图展示可参考下方文字流程绘制步骤1创建数据库连接引擎EngineEngine 是 SQLAlchemy 与数据库之间的连接核心负责管理数据库连接池、执行 SQL 语句底层自动处理无需我们手动管理连接。不同数据库的引擎连接格式不同本文给出最常用的 2 种MySQL 和 SQLite直接替换参数即可使用# 方式1MySQL 连接推荐实际开发常用# 格式mysqlpymysql://用户名:密码主机地址:端口号/数据库名?字符集enginecreate_engine(mysqlpymysql://root:123456localhost:3306/test_db?charsetutf8mb4,echoTrue,# echoTrue 表示打印底层执行的 SQL 语句便于调试生产环境可关闭pool_size5,# 连接池大小默认5可根据需求调整max_overflow10# 连接池最大溢出数超出pool_size的临时连接数)# 方式2SQLite 连接无需安装驱动适合本地测试、小型项目# 格式sqlite:///数据库文件路径相对路径/绝对路径# engine create_engine(sqlite:///test.db, echoTrue)注意MySQL 连接时需先确保本地 MySQL 服务已启动且已创建对应的数据库如上述的 test_db否则会报错。步骤2创建 ORM 基类Basedeclarative_base() 会创建一个基类所有需要映射到数据库表的 Python 类都必须继承这个基类。基类会自动管理所有子类模型后续的建表、查表等操作都依赖这个基类。# 创建 ORM 基类所有 ORM Model 继承此类classBase(DeclarativeBase):pass步骤3定义 ORM 模型映射数据库表这一步是 ORM 的核心将 Python 类与数据库表进行映射类名对应表名类的属性对应表的字段。模型类必须满足 2 个要求① 继承 Base 基类② 定义 __tablename__ 属性指定映射的数据库表名③ 至少定义一个主键字段primary_keyTrue。# 定义 User 模型映射数据库中的 users 表classUser(Base):# __tablename__指定映射的数据库表名必须有__tablename__users# 定义字段字段名 Column(字段类型, 约束条件)idColumn(Integer,primary_keyTrue,autoincrementTrue,comment用户ID主键自增)nameColumn(String(50),nullableFalse,comment用户名非空)ageColumn(Integer,nullableTrue,default18,comment用户年龄默认18)emailColumn(String(100),uniqueTrue,comment用户邮箱唯一)create_timeColumn(DateTime,defaultdatetime.now,comment创建时间默认当前时间)# 可根据需求定义多个模型如 Order、Product 等每个模型对应一张表classOrder(Base):__tablename__ordersorder_idColumn(Integer,primary_keyTrue,autoincrementTrue,comment订单ID)user_idColumn(Integer,comment关联用户ID与users表的id对应)order_nameColumn(String(100),nullableFalse,comment订单名称)步骤4创建数据库表通过 Base 基类的 metadata.create_all(engine) 方法会自动根据模型类在数据库中创建对应的表如果表已存在则不会重复创建避免覆盖数据。# 根据模型类自动创建数据库表若表已存在不重复创建Base.metadata.create_all(engine)执行这行代码后打开 MySQL 客户端如 Navicat、DBeaver就能看到 test_db 数据库中自动创建了 users 和 orders 两张表字段、约束、注释都与模型类一致。步骤5创建会话SessionSession 是 SQLAlchemy ORM 操作数据库的入口相当于一个“数据库操作会话”所有的增删改查操作都需要通过 Session 来完成同时 Session 负责管理事务提交、回滚。# 创建会话工厂绑定引擎Sessionsessionmaker(bindengine)# 创建一个会话实例每次操作数据库都需要创建会话sessionSession()步骤6通过 Session 执行增删改查操作会话创建完成后就可以通过 session 对象执行各种数据库操作无需编写原生 SQL全程用 Python 语法操作即可。6.1 新增数据insert# 方式1新增单条数据user1User(name张三,age22,emailzhangsan163.com)session.add(user1)# 将数据添加到会话# 方式2新增多条数据效率更高user2User(name李四,age25,emaillisi163.com)user3User(name王五,age20,emailwangwu163.com)session.add_all([user2,user3])# 批量添加# 注意此时数据还在会话中未写入数据库需要执行 commit() 提交事务session.commit()6.2 查询数据select查询是最常用的操作SQLAlchemy ORM 提供了丰富的查询方法以下是最常用的几种# 1. 查询所有数据返回列表元素是 User 对象all_userssession.query(User).all()foruserinall_users:print(f用户ID{user.id}用户名{user.name}邮箱{user.email})# 2. 查询单条数据返回第一个匹配的对象没有则返回 Noneusersession.query(User).filter(User.name张三).first()print(f查询到的用户{user.name}年龄{user.age})# 3. 条件查询多条件用 and_ / or_ 连接需导入fromsqlalchemyimportand_,or_ userssession.query(User).filter(and_(User.age20,User.name!张三)).all()# 4. 排序查询按 age 升序desc() 表示降序users_ordersession.query(User).order_by(User.age).all()# 升序# users_order session.query(User).order_by(User.age.desc()).all() # 降序# 5. 分页查询skip 跳过前2条limit 取3条适合分页场景users_pagesession.query(User).skip(2).limit(3).all()6.3 修改数据update修改数据的思路先查询到需要修改的对象再修改对象的属性最后提交事务。# 1. 先查询到需要修改的对象usersession.query(User).filter(User.name李四).first()ifuser:# 2. 修改对象的属性直接赋值即可user.age26user.emaillisi_new163.com# 3. 提交事务修改生效session.commit()print(修改成功)6.4 删除数据delete删除数据的思路先查询到需要删除的对象再通过 session.delete() 删除最后提交事务。# 1. 先查询到需要删除的对象usersession.query(User).filter(User.name王五).first()ifuser:# 2. 删除对象session.delete(user)# 3. 提交事务删除生效session.commit()print(删除成功)步骤7提交/回滚事务所有增删改操作都必须通过 session.commit() 提交事务才能真正写入数据库如果操作过程中出现错误可通过 session.rollback() 回滚事务恢复到操作前的状态。try:# 执行增删改操作userUser(name赵六,age28,emailzhaoliu163.com)session.add(user)# 提交事务session.commit()print(操作成功)exceptExceptionase:# 出现错误回滚事务session.rollback()print(f操作失败已回滚{str(e)})步骤8关闭会话数据库操作完成后必须关闭会话释放数据库连接避免连接泄露尤其是生产环境否则会导致数据库连接耗尽。# 关闭会话session.close()3. 完整实战代码附详细注释将上述所有步骤整合给出完整可运行的实战代码复制到 Python 文件中替换 MySQL 连接参数即可直接运行fromsqlalchemyimportcreate_engine,Column,Integer,String,DateTime,and_fromsqlalchemy.ext.declarativeimportdeclarative_basefromsqlalchemy.ormimportsessionmakerfromdatetimeimportdatetime# 1. 创建数据库引擎MySQL 连接替换为自己的数据库参数enginecreate_engine(mysqlpymysql://root:123456localhost:3306/test_db?charsetutf8mb4,echoTrue,pool_size5,max_overflow10)# 2. 创建 ORM 基类Basedeclarative_base()# 3. 定义模型类映射数据表classUser(Base):__tablename__usersidColumn(Integer,primary_keyTrue,autoincrementTrue,comment用户ID主键自增)nameColumn(String(50),nullableFalse,comment用户名非空)ageColumn(Integer,nullableTrue,default18,comment用户年龄默认18)emailColumn(String(100),uniqueTrue,comment用户邮箱唯一)create_timeColumn(DateTime,defaultdatetime.now,comment创建时间)# 4. 自动创建数据表若已存在则不创建Base.metadata.create_all(engine)# 5. 创建会话Sessionsessionmaker(bindengine)sessionSession()try:# 6. 增新增数据user1User(name张三,age22,emailzhangsan163.com)user2User(name李四,age25,emaillisi163.com)session.add_all([user1,user2])# 查查询数据all_userssession.query(User).all()print(所有用户)foruserinall_users:print(fID:{user.id}, 姓名:{user.name}, 邮箱:{user.email})# 改修改数据usersession.query(User).filter(User.name李四).first()ifuser:user.age26print(修改后李四的年龄,user.age)# 删删除数据注释掉避免误删需要时取消注释# user_del session.query(User).filter(User.name 张三).first()# if user_del:# session.delete(user_del)# print(删除成功)# 7. 提交事务session.commit()print(所有操作执行成功)exceptExceptionase:# 出错回滚session.rollback()print(f操作失败已回滚{str(e)})finally:# 8. 关闭会话无论成功失败都要关闭session.close()print(会话已关闭)4. 关键注意事项避坑指南⚠️ 会话管理每次操作数据库后必须关闭会话建议用 try-finally 确保关闭避免连接泄露。⚠️ 事务提交增删改操作必须执行 session.commit()否则数据不会写入数据库仅停留在会话中。⚠️ 模型约束定义模型时主键primary_key必须有unique唯一、nullable非空等约束要根据业务需求设置避免数据异常。⚠️ 数据库驱动使用 MySQL 必须安装 pymysql使用 PostgreSQL 必须安装 psycopg2-binary否则会报错“no module named xxx”。⚠️ echo 参数开发环境可设为 True打印 SQL便于调试生产环境建议设为 False避免日志冗余。5. 常见问题排查问题1连接 MySQL 时报错“Access denied for user #39;root#39;#39;localhost#39; (using password: YES)”解决方案检查 MySQL 用户名、密码是否正确检查 MySQL 服务是否已启动检查 root 用户是否有访问 test_db 数据库的权限。问题2创建表时报错“Table #39;users#39; already exists”解决方案Base.metadata.create_all(engine) 会自动判断表是否存在无需手动删除若确实需要重新建表可先删除原有表再执行建表语句生产环境慎用。问题3新增数据时报错“Duplicate entry #39;zhangsan163.com#39; for key #39;users.email#39;”解决方案email 字段设置了 uniqueTrue唯一约束避免重复插入相同邮箱可先查询邮箱是否已存在再执行新增操作。结尾以上就是 Python SQLAlchemy ORM 的完整使用流程从环境准备、引擎创建、模型定义到会话操作、增删改查覆盖了新手入门到实战的所有核心内容。掌握这个流程后就能轻松用 ORM 操作数据库摆脱原生 SQL 的繁琐。
