基于 SQLAlchemy 2.x，面向 MySQL 数据库的从入门到精通实战教程（2）基于 SQLAlchemy 2.x，面向 MySQL 数据库的从入门到精通实战教程（3）文章目录第1章 SQLAlchemy 简介1.1 什么是 SQLAlchemy1.2 ORM 与 Core 双架构1.3 为什么选择 SQLAlchemy + MySQL第2章 安装与环境准备（MySQL 环境）2.1 安装 SQLAlchemy2.2 MySQL 驱动选择2.3 验证安装第3章 核心概念3.1 Engine（引擎）3.2 Connection（连接）3.3 Session（会话）3.4 Declarative Base（声明式基类）3.5 Model 与 Column第4章 连接 MySQL 数据库4.1 MySQL 连接字符串格式4.2 创建 Engine（MySQL 优化配置）4.3 MySQL 连接池深度配置第5章 定义数据模型5.1 Declarative Base 与模型类5.2 MySQL 常用列类型5.3 列约束与索引5.4 SQLAlchemy 2.0 类型注解风格基于 SQLAlchemy 2.x，面向 MySQL 数据库的从入门到精通实战教程第1章 SQLAlchemy 简介1.1 什么是 SQLAlchemySQLAlchemy 是 Python 生态中最流行、功能最强大的关系型数据库工具库。它提供了一套完整的企业级持久化框架，将关系数据库表的结构与 Python 对象进行映射，使开发者可以用面向对象的方式操作 MySQL 等关系型数据库，而无需手写大量原生 SQL。SQLAlchemy 由 Michael Bayer 于 2006 年首次发布，经过近二十年的发展，已成为 Python 数据库领域的事实标准，被广泛应用于 Flask、FastAPI 等各类 Web 框架中。1.2 ORM 与 Core 双架构SQLAlchemy 最鲜明的特点是其分层双架构设计：ORM（Object Relational Mapper，对象关系映射）：建立在 Core 之上，提供面向对象的数据库操作方式。开发者定义 Python 类（模型），ORM 自动将类属性映射到 MySQL 表的列，将对象映射到表中的行。Core（SQL 表达式语言）：SQLAlchemy 的底层核心，提供了一套 Pythonic 的 SQL 构建工具。它比原生 SQL 更安全、更可组合，但仍保持对 SQL 的精确控制，适合需要精细调优或执行复杂查询的场景。这种分层设计的优势在于：简单 CRUD 用 ORM 提高开发效率，复杂查询或性能敏感场景用 Core 精确控制，两者可以无缝混合使用。1.3 为什么选择 SQLAlchemy + MySQL优势说明MySQL 深度适配完整支持 MySQL 数据类型、索引、事务、存储引擎等特性数据库无关性代码层面与数据库解耦，未来从 MySQL 迁移到 PostgreSQL 只需改连接字符串强大的 ORM 映射支持一对多、多对多、多态继承、复合主键等复杂关系映射SQL 表达式语言Core 层提供可编程的 SQL 构建器，兼顾灵活性与安全性成熟的连接池内置高效连接池，针对 MySQL 的wait_timeout断连问题有完善的应对方案事务管理完善的事务支持，与 MySQL 的 InnoDB 引擎深度配合生态丰富Alembic 迁移工具、Flask-SQLAlchemy、SQLModel 等周边生态完善异步支持2.0 起原生支持 asyncio，可配合asyncmy驱动实现异步 MySQL 操作第2章 安装与环境准备（MySQL 环境）2.1 安装 SQLAlchemy传统安装方式：pipinstallsqlalchemy使用 uv（推荐的现代 Python 包管理器）：uvaddsqlalchemy安装指定版本：pipinstall'sqlalchemy=2.0,3.0'2.2 MySQL 驱动选择SQLAlchemy 本身不包含数据库驱动，连接 MySQL 需要单独安装 DBAPI 驱动。以下是 MySQL 的主流驱动对比：驱动安装命令特点推荐场景PyMySQLpip install pymysql纯 Python 实现，无需编译，安装简单开发环境、快速原型、跨平台mysqlclientpip install mysqlclientC 扩展，性能最好，但需要系统依赖生产环境、性能敏感asyncmypip install asyncmy异步驱动，基于 mysqlclient 的 C 库异步项目（FastAPI async）aiomysqlpip install aiomysql纯 Python 异步驱动异步项目、无需编译推荐组合：开发环境用 PyMySQL（零依赖安装），生产环境用 mysqlclient（性能更优）。异步项目用 asyncmy。mysqlclient 安装前置依赖（Ubuntu/Debian）：sudoapt-getinstallpython3-dev default-libmysqlclient-dev build-essential pkg-configmacOS：brewinstallmysql-client pkg-configexportPKG_CONFIG_PATH="$(brew--prefix)/opt/mysql-client/lib/pkgconfig"pipinstallmysqlclient2.3 验证安装importsqlalchemyprint(sqlalchemy.__version__)# 输出示例: 2.0.x# 验证 MySQL 驱动importpymysqlprint(pymysql.__version__)第3章 核心概念在深入使用 SQLAlchemy 之前，理解其核心概念至关重要。3.1 Engine（引擎）Engine 是 SQLAlchemy 的入口点，它负责管理数据库连接池和 SQL 方言（针对 MySQL 的方言实现）。一个 Engine 对象代表了一个到 MySQL 的连接源，通常在应用启动时创建一次，全局复用。Engine 本身不持有数据库连接，而是从连接池中获取连接。它通过create_engine()函数创建。3.2 Connection（连接）Connection 代表一个实际的 MySQL 数据库连接，从 Engine 的连接池中获取。使用完毕后应归还连接池。在 ORM 模式下，通常不直接操作 Connection，而是通过 Session 间接使用。3.3 Session（会话）Session 是 ORM 模式下的核心工作单元，它管理着一组与 MySQL 交互的对象，跟踪对象的状态变化，并在适当的时候将变化同步到数据库。重要：Session 不是线程安全的，每个线程或请求应使用独立的 Session 实例。Session 的主要职责：持有 MySQL 连接（在需要时从连接池获取）管理事务（begin / commit / rollback）跟踪 ORM 对象的状态（transient / pending / persistent / detached）提供查询接口3.4 Declarative Base（声明式基类）Declarative Base 是所有 ORM 模型类的基类。通过继承它，你可以用 Python 类的方式定义 MySQL 表结构。SQLAlchemy 2.0 推荐使用DeclarativeBase类。3.5 Model 与 ColumnModel（模型）是继承自 Declarative Base 的 Python 类，每个模型类对应 MySQL 中的一张表。类属性通过mapped_column（2.0 风格）定义，对应表中的列。第4章 连接 MySQL 数据库4.1 MySQL 连接字符串格式SQLAlchemy 使用 URL 格式的连接字符串来指定 MySQL 连接信息：mysql+driver://username:password@host:port/database?params各部分说明：mysql：数据库类型固定为 mysqldriver：驱动名，如pymysql、mysqlclient（mysqlclient 驱动名直接写mysql即可，即mysql://）username:password：MySQL 用户名和密码（含特殊字符时需 URL 编码）host:port：MySQL 主机地址和端口（默认 3306）database：要连接的数据库名（需提前在 MySQL 中CREATE DATABASE）params：查询参数，如字符集、SSL 等常用连接字符串示例：# PyMySQL 驱动（推荐开发环境）"mysql+pymysql://root:password@localhost:3306/mydb?charset=utf8mb4"# mysqlclient 驱动（推荐生产环境，驱动名省略）"mysql://root:password@localhost:3306/mydb?charset=utf8mb4"# 带密码特殊字符（需 URL 编码，如 p@ss - p%40ss）"mysql+pymysql://root:p%40ss@localhost:3306/mydb?charset=utf8mb4" 基于 SQLAlchemy 2.x，面向 MySQL 数据库的从入门到精通实战教程（1）
基于 SQLAlchemy 2.x，面向 MySQL 数据库的从入门到精通实战教程（2）基于 SQLAlchemy 2.x，面向 MySQL 数据库的从入门到精通实战教程（3）文章目录第1章 SQLAlchemy 简介1.1 什么是 SQLAlchemy1.2 ORM 与 Core 双架构1.3 为什么选择 SQLAlchemy + MySQL第2章 安装与环境准备（MySQL 环境）2.1 安装 SQLAlchemy2.2 MySQL 驱动选择2.3 验证安装第3章 核心概念3.1 Engine（引擎）3.2 Connection（连接）3.3 Session（会话）3.4 Declarative Base（声明式基类）3.5 Model 与 Column第4章 连接 MySQL 数据库4.1 MySQL 连接字符串格式4.2 创建 Engine（MySQL 优化配置）4.3 MySQL 连接池深度配置第5章 定义数据模型5.1 Declarative Base 与模型类5.2 MySQL 常用列类型5.3 列约束与索引5.4 SQLAlchemy 2.0 类型注解风格基于 SQLAlchemy 2.x，面向 MySQL 数据库的从入门到精通实战教程第1章 SQLAlchemy 简介1.1 什么是 SQLAlchemySQLAlchemy 是 Python 生态中最流行、功能最强大的关系型数据库工具库。它提供了一套完整的企业级持久化框架，将关系数据库表的结构与 Python 对象进行映射，使开发者可以用面向对象的方式操作 MySQL 等关系型数据库，而无需手写大量原生 SQL。SQLAlchemy 由 Michael Bayer 于 2006 年首次发布，经过近二十年的发展，已成为 Python 数据库领域的事实标准，被广泛应用于 Flask、FastAPI 等各类 Web 框架中。1.2 ORM 与 Core 双架构SQLAlchemy 最鲜明的特点是其分层双架构设计：ORM（Object Relational Mapper，对象关系映射）：建立在 Core 之上，提供面向对象的数据库操作方式。开发者定义 Python 类（模型），ORM 自动将类属性映射到 MySQL 表的列，将对象映射到表中的行。Core（SQL 表达式语言）：SQLAlchemy 的底层核心，提供了一套 Pythonic 的 SQL 构建工具。它比原生 SQL 更安全、更可组合，但仍保持对 SQL 的精确控制，适合需要精细调优或执行复杂查询的场景。这种分层设计的优势在于：简单 CRUD 用 ORM 提高开发效率，复杂查询或性能敏感场景用 Core 精确控制，两者可以无缝混合使用。1.3 为什么选择 SQLAlchemy + MySQL优势说明MySQL 深度适配完整支持 MySQL 数据类型、索引、事务、存储引擎等特性数据库无关性代码层面与数据库解耦，未来从 MySQL 迁移到 PostgreSQL 只需改连接字符串强大的 ORM 映射支持一对多、多对多、多态继承、复合主键等复杂关系映射SQL 表达式语言Core 层提供可编程的 SQL 构建器，兼顾灵活性与安全性成熟的连接池内置高效连接池，针对 MySQL 的wait_timeout断连问题有完善的应对方案事务管理完善的事务支持，与 MySQL 的 InnoDB 引擎深度配合生态丰富Alembic 迁移工具、Flask-SQLAlchemy、SQLModel 等周边生态完善异步支持2.0 起原生支持 asyncio，可配合asyncmy驱动实现异步 MySQL 操作第2章 安装与环境准备（MySQL 环境）2.1 安装 SQLAlchemy传统安装方式：pipinstallsqlalchemy使用 uv（推荐的现代 Python 包管理器）：uvaddsqlalchemy安装指定版本：pipinstall'sqlalchemy=2.0,3.0'2.2 MySQL 驱动选择SQLAlchemy 本身不包含数据库驱动，连接 MySQL 需要单独安装 DBAPI 驱动。以下是 MySQL 的主流驱动对比：驱动安装命令特点推荐场景PyMySQLpip install pymysql纯 Python 实现，无需编译，安装简单开发环境、快速原型、跨平台mysqlclientpip install mysqlclientC 扩展，性能最好，但需要系统依赖生产环境、性能敏感asyncmypip install asyncmy异步驱动，基于 mysqlclient 的 C 库异步项目（FastAPI async）aiomysqlpip install aiomysql纯 Python 异步驱动异步项目、无需编译推荐组合：开发环境用 PyMySQL（零依赖安装），生产环境用 mysqlclient（性能更优）。异步项目用 asyncmy。mysqlclient 安装前置依赖（Ubuntu/Debian）：sudoapt-getinstallpython3-dev default-libmysqlclient-dev build-essential pkg-configmacOS：brewinstallmysql-client pkg-configexportPKG_CONFIG_PATH="$(brew--prefix)/opt/mysql-client/lib/pkgconfig"pipinstallmysqlclient2.3 验证安装importsqlalchemyprint(sqlalchemy.__version__)# 输出示例: 2.0.x# 验证 MySQL 驱动importpymysqlprint(pymysql.__version__)第3章 核心概念在深入使用 SQLAlchemy 之前，理解其核心概念至关重要。3.1 Engine（引擎）Engine 是 SQLAlchemy 的入口点，它负责管理数据库连接池和 SQL 方言（针对 MySQL 的方言实现）。一个 Engine 对象代表了一个到 MySQL 的连接源，通常在应用启动时创建一次，全局复用。Engine 本身不持有数据库连接，而是从连接池中获取连接。它通过create_engine()函数创建。3.2 Connection（连接）Connection 代表一个实际的 MySQL 数据库连接，从 Engine 的连接池中获取。使用完毕后应归还连接池。在 ORM 模式下，通常不直接操作 Connection，而是通过 Session 间接使用。3.3 Session（会话）Session 是 ORM 模式下的核心工作单元，它管理着一组与 MySQL 交互的对象，跟踪对象的状态变化，并在适当的时候将变化同步到数据库。重要：Session 不是线程安全的，每个线程或请求应使用独立的 Session 实例。Session 的主要职责：持有 MySQL 连接（在需要时从连接池获取）管理事务（begin / commit / rollback）跟踪 ORM 对象的状态（transient / pending / persistent / detached）提供查询接口3.4 Declarative Base（声明式基类）Declarative Base 是所有 ORM 模型类的基类。通过继承它，你可以用 Python 类的方式定义 MySQL 表结构。SQLAlchemy 2.0 推荐使用DeclarativeBase类。3.5 Model 与 ColumnModel（模型）是继承自 Declarative Base 的 Python 类，每个模型类对应 MySQL 中的一张表。类属性通过mapped_column（2.0 风格）定义，对应表中的列。第4章 连接 MySQL 数据库4.1 MySQL 连接字符串格式SQLAlchemy 使用 URL 格式的连接字符串来指定 MySQL 连接信息：mysql+driver://username:password@host:port/database?params各部分说明：mysql：数据库类型固定为 mysqldriver：驱动名，如pymysql、mysqlclient（mysqlclient 驱动名直接写mysql即可，即mysql://）username:password：MySQL 用户名和密码（含特殊字符时需 URL 编码）host:port：MySQL 主机地址和端口（默认 3306）database：要连接的数据库名（需提前在 MySQL 中CREATE DATABASE）params：查询参数，如字符集、SSL 等常用连接字符串示例：# PyMySQL 驱动（推荐开发环境）"mysql+pymysql://root:password@localhost:3306/mydb?charset=utf8mb4"# mysqlclient 驱动（推荐生产环境，驱动名省略）"mysql://root:password@localhost:3306/mydb?charset=utf8mb4"# 带密码特殊字符（需 URL 编码，如 p@ss - p%40ss）"mysql+pymysql://root:p%40ss@localhost:3306/mydb?charset=utf8mb4"