SQLAlchemy 是一个功能强大的 Python SQL 工具包和对象关系映射器，它为开发者提供了高级的抽象和 Pythonic 的方式来与数据库进行交互。

安装 SQLAlchemy

安装 SQLAlchemy 非常简单，通常使用 Python 的包管理工具 pip 即可。

基本安装

在您的终端或命令行中,运行以下命令：

pip install SQLAlchemy

推荐做法： 为了避免不同项目之间的依赖冲突,强烈建议在虚拟环境中进行安装。

# 1. 创建一个虚拟环境 (名为 venv)
python -m venv venv
# 2. 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
# 3. 在激活的虚拟环境中安装 SQLAlchemy
pip install SQLAlchemy

验证安装

安装完成后，您可以通过在 Python 解释器中导入它来验证是否安装成功。

>>> import sqlalchemy
>>> print(sqlalchemy.__version__)
# 如果安装成功，它会打印出版本号，'2.0.21'

核心概念简介

在开始使用之前，了解 SQLAlchemy 的两个核心组件非常重要：

1. Core (核心层):

   • 提供了与数据库无关的 SQL 表达式语言。
   • 允许您使用 Python 代码来构建 SQL 查询，而无需编写原始的 SQL 字符串。
   • 这是 SQLAlchemy 的基础,功能强大且灵活。

2. ORM (Object Relational Mapper / 对象关系映射层):

   • 构建在 Core 之上。
   • 允许您将数据库表映射为 Python 类（称为“模型”或“类”），将行映射为类的实例（对象）,将列映射为对象的属性。
   • 这使得您可以使用 Python 对象的方法和属性来操作数据库，而不是直接写 SQL,代码更易于理解和维护。

现代 SQLAlchemy (1.4+) 的推荐做法是使用 2.0 风格，它提供了更清晰、更一致的 API。

快速入门示例 (使用 ORM)

下面是一个完整的示例，演示如何使用 SQLAlchemy ORM 来完成以下操作：

1. 连接到一个 SQLite 数据库（SQLite 是一个轻量级的文件数据库，无需额外安装）。
2. 定义一个数据模型（一个 Python 类）。
3. 创建表。
4. 添加数据。
5. 查询数据。

定义模型和连接数据库

我们创建一个 Python 脚本（app.py），定义一个 User 模型并建立数据库连接。

# app.py
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import sessionmaker
from sqlalchemy.ext.declarative import declarative_base
# 1. 定义数据库的连接 URL
# 'sqlite:///users.db' 表示创建一个名为 users.db 的 SQLite 数据库文件
DATABASE_URL = "sqlite:///users.db"
# 2. 创建引擎
# 引擎是 SQLAlchemy 的核心，负责与数据库的连接和管理
engine = create_engine(DATABASE_URL, echo=True) # echo=True 会在控制台打印生成的 SQL 语句
# 3. 创建一个基类
# 我们的模型类将继承这个基类
Base = declarative_base()
# 4. 定义 User 模型
class User(Base):
    __tablename__ = 'users'  # 指定在数据库中对应的表名
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String, unique=True)
    def __repr__(self):
        return f"<User(name='{self.name}', email='{self.email}')>"
# 5. 创建所有在 Base 中定义的表（如果它们尚不存在）
# 这一步会在数据库中创建 'users' 表
Base.metadata.create_all(engine)
print("数据库和表 'users' 已准备就绪。")

运行这个脚本，您会在项目目录下看到一个新生成的 users.db 文件。

添加和查询数据

我们使用 Session 来与数据库进行交互。Session 是 ORM 的工作单元。

# 继续在 app.py 中添加以下代码，或者创建一个新的脚本
# ... (保留上面的代码) ...
# 6. 创建 Session
# Session 类用于管理数据库的会话
Session = sessionmaker(bind=engine)
session = Session()
# 7. 添加新用户 (创建和插入)
print("\n--- 添加用户 ---")
new_user = User(name='Alice', email='alice@example.com')
session.add(new_user)
# 一次性提交所有挂起的操作到数据库
session.commit()
print(f"已添加用户: {new_user}")
# 8. 查询用户
print("\n--- 查询所有用户 ---")
# 查询 User 表中的所有记录
all_users = session.query(User).all()
for user in all_users:
    print(user)
# 查询特定用户
print("\n--- 查询名为 'Alice' 的用户 ---")
alice = session.query(User).filter_by(name='Alice').first()
if alice:
    print(f"找到用户: {alice}")
    print(f"用户ID: {alice.id}")
# 9. 更新用户
print("\n--- 更新 Alice 的邮箱 ---")
if alice:
    alice.email = 'alice_new@example.com'
    session.commit() # 提交更改
    print(f"已更新 Alice 的邮箱为: {alice.email}")
# 10. 删除用户
print("\n--- 删除名为 'Alice' 的用户 ---")
if alice:
    session.delete(alice)
    session.commit()
    print("已删除 Alice。")
# 11. 再次查询以确认删除
print("\n--- 再次查询所有用户 (确认删除) ---")
remaining_users = session.query(User).all()
if not remaining_users:
    print("用户表中已没有数据。")
else:
    for user in remaining_users:
        print(user)
# 12. 关闭 Session
# 好习惯是使用 with 语句或在最后关闭 session
session.close()

如何运行

将以上代码保存为 app.py,然后在终端中运行：

python app.py

您将在终端中看到详细的输出，包括 SQLAlchemy 生成的 SQL 语句和 Python 代码的执行结果。

安装数据库驱动

SQLAlchemy 本身是一个“数据库无关”的层，它需要一个底层的 DB-API 驱动程序来与特定的数据库进行通信。

• SQLite: Python 标准库自带,无需额外安装。
• PostgreSQL: 需要安装 psycopg2-binary。

  pip install psycopg2-binary

• MySQL: 需要安装 mysqlclient 或 PyMySQL。

  pip install mysqlclient
  # 或者
  pip install PyMySQL

• Microsoft SQL Server: 需要安装 pyodbc。

  pip install pyodbc

当您连接到不同数据库时，只需修改 DATABASE_URL 即可：

# PostgreSQL 示例
DATABASE_URL = "postgresql://user:password@host:port/database_name"
# MySQL 示例 (使用 PyMySQL)
DATABASE_URL = "mysql+pymysql://user:password@host:port/database_name"
# SQL Server 示例
DATABASE_URL = "mssql+pyodbc://user:password@host:port/database_name?driver=ODBC+Driver+17+for+SQL+Server"

1. 安装: 使用 pip install SQLAlchemy 在虚拟环境中进行。
2. 核心组件: 理解 Core (SQL 表达式语言) 和 ORM (Python 对象映射) 的区别和联系。
3. 基本流程:
   • 使用 create_engine 定义数据库连接。
   • 使用 declarative_base 创建模型基类。
   • 定义模型类（继承基类），用 Column 定义列。
   • 使用 Base.metadata.create_all(engine) 创建表。
   • 使用 sessionmaker 创建 Session。
   • 通过 session 进行增、删、改、查操作。
   • session.commit() 提交事务，session.close() 关闭会话。

这份指南应该能帮助您顺利开始使用 SQLAlchemy，随着您对它的深入了解,您会发现它在处理复杂数据库应用时的巨大威力。