使用 SQLAlchemy 连接数据库

《使用 SQLAlchemy 连接数据库》指南，适合 FastAPI / Python 项目直接使用。

🚀 使用 SQLAlchemy 连接数据库

SQLAlchemy 是 Python 最成熟的 ORM（对象关系映射）框架，同时提供：

Core 层（底层 SQL 构建）
ORM 层（面向对象的数据模型封装）

以下内容将带你从基础连接到生产级最佳实践。

1️⃣ 安装 SQLAlchemy

bash 复制代码

pip install sqlalchemy
# 如果你使用 PostgreSQL
pip install psycopg2-binary
# 如果你使用 MySQL
pip install pymysql

2️⃣ 连接数据库（基础版）

使用 create_engine() 创建数据库连接引擎：

python 复制代码

from sqlalchemy import create_engine

DATABASE_URL = "sqlite:///./test.db"  # SQLite 示例

engine = create_engine(
    DATABASE_URL,
    echo=True,            # 是否打印 SQL
    future=True           # 推荐开启新 API 行为
)

如果是 MySQL 或 PostgreSQL：

python 复制代码

# PostgreSQL
DATABASE_URL = "postgresql+psycopg2://user:password@localhost:5432/mydb"

# MySQL
DATABASE_URL = "mysql+pymysql://user:password@localhost:3306/mydb"

3️⃣ 创建一个 Session（基础版）

Session 用于管理数据库会话：

python 复制代码

from sqlalchemy.orm import sessionmaker

SessionLocal = sessionmaker(
    bind=engine,
    autoflush=False,
    autocommit=False
)

4️⃣ 定义 ORM 模型（基础）

首先创建基类：

python 复制代码

from sqlalchemy.orm import declarative_base

Base = declarative_base()

定义一个模型：

python 复制代码

from sqlalchemy import Column, Integer, String

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(50))
    email = Column(String(120), unique=True, index=True)

5️⃣ 自动创建表

python 复制代码

Base.metadata.create_all(bind=engine)

6️⃣ 操作数据库（基础 CRUD）

1）插入数据

python 复制代码

db = SessionLocal()

new_user = User(name="Alice", email="alice@example.com")
db.add(new_user)
db.commit()
db.refresh(new_user)

db.close()

2）查询数据

python 复制代码

db = SessionLocal()
users = db.query(User).all()
db.close()

⚡ 7️⃣ 在 FastAPI 中使用 SQLAlchemy（推荐结构）

FastAPI 推荐一个依赖注入风格的 session：

创建 `get_db()` 依赖

python 复制代码

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

路由中使用

python 复制代码

from fastapi import Depends, APIRouter
router = APIRouter()

@router.get("/users")
def list_users(db=Depends(get_db)):
    return db.query(User).all()

@router.post("/users")
def create_user(user: UserCreate, db=Depends(get_db)):
    db_user = User(**user.dict())
    db.add(db_user)
    db.commit()
    db.refresh(db_user)
    return db_user

（这里 UserCreate 为 Pydantic 模型）

🔥 8️⃣ 最佳实践（生产环境）

✅ 1. 使用连接池

默认启用，但你可以调优：

python 复制代码

engine = create_engine(
    DATABASE_URL,
    pool_size=10,            # 常驻连接数量
    max_overflow=20,         # 最大临时连接
    pool_timeout=30,
    pool_pre_ping=True,      # 防止 MySQL 断开连接
)

✅ 2. 避免 "Session 不关闭" 问题

FastAPI 使用 Depends(get_db) 本身会自动关闭。

如果你自己创建 session，务必 try...finally...close()：

python 复制代码

db = SessionLocal()
try:
    ...
finally:
    db.close()

✅ 3. 使用 `scoped_session`（如 Celery 多线程环境）

如果是多线程环境：

python 复制代码

from sqlalchemy.orm import scoped_session

db_session = scoped_session(sessionmaker(bind=engine))

FastAPI 通常不需要。

✅ 4. 使用 Alembic 管理数据库迁移（强烈推荐）

bash 复制代码

pip install alembic
alembic init alembic

配置 alembic.ini 并跑迁移。

✅ 5. DTO 使用 Pydantic（隔离 ORM 模型）

确保接口输入输出不直接暴露 SQLAlchemy 对象。

🎯 9️⃣ 完整项目结构（实战推荐）

复制代码

app/
  ├── database.py
  ├── models/
  │     └── user.py
  ├── schemas/
  │     └── user_schema.py
  ├── routers/
  │     └── user_router.py
  └── main.py

database.py

python 复制代码

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

DATABASE_URL = "mysql+pymysql://root:123456@localhost:3306/demo"

engine = create_engine(
    DATABASE_URL,
    pool_pre_ping=True,
)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

🎉 总结

内容	是否掌握
如何创建 engine	✅
如何创建 Session	✅
如何定义 ORM 模型	✅
如何在 FastAPI 中集成	✅
如何使用连接池与最佳实践	✅
如何构建生产级结构	✅

👇🏻下面是完整可运行的 FastAPI + SQLAlchemy 项目模板

下面给你一个可直接运行、结构清晰、包含 CRUD 示例 的

📦 FastAPI + SQLAlchemy + Pydantic 完整项目模板。

复制后立即 uvicorn main:app --reload 就能跑起来。

🚀 FastAPI + SQLAlchemy 项目模板（可直接运行）

📁 项目结构

复制代码

app/
├── main.py
├── database.py
├── models/
│   └── user.py
├── schemas/
│   └── user.py
├── crud/
│   └── user.py
└── routers/
    └── user.py

接下来给你所有文件的完整内容👇

你直接复制即可使用。

1️⃣ app/database.py

python 复制代码

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

# 修改为你的数据库配置
DATABASE_URL = "sqlite:///./test.db"
# 如果 MySQL:
# DATABASE_URL = "mysql+pymysql://root:123456@localhost:3306/demo"
# 如果 PostgreSQL:
# DATABASE_URL = "postgresql://user:password@localhost:5432/demo"

engine = create_engine(
    DATABASE_URL,
    connect_args={"check_same_thread": False} if DATABASE_URL.startswith("sqlite") else {},
    pool_pre_ping=True,           
)

SessionLocal = sessionmaker(
    autocommit=False,
    autoflush=False,
    bind=engine
)

Base = declarative_base()


# 依赖注入
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

2️⃣ app/models/user.py

python 复制代码

from sqlalchemy import Column, Integer, String
from app.database import Base

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(50), nullable=False)
    email = Column(String(120), unique=True, index=True, nullable=False)

3️⃣ app/schemas/user.py （Pydantic 模型）

python 复制代码

from pydantic import BaseModel, EmailStr

class UserBase(BaseModel):
    name: str
    email: EmailStr

class UserCreate(UserBase):
    pass

class UserResponse(UserBase):
    id: int

    class Config:
        orm_mode = True

4️⃣ app/crud/user.py

python 复制代码

from sqlalchemy.orm import Session
from app.models.user import User
from app.schemas.user import UserCreate

def get_users(db: Session):
    return db.query(User).all()

def get_user(db: Session, user_id: int):
    return db.query(User).filter(User.id == user_id).first()

def create_user(db: Session, user: UserCreate):
    db_user = User(name=user.name, email=user.email)
    db.add(db_user)
    db.commit()
    db.refresh(db_user)
    return db_user

5️⃣ app/routers/user.py（路由层）

python 复制代码

from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session
from app.database import get_db
from app.crud.user import get_users, get_user, create_user
from app.schemas.user import UserCreate, UserResponse
from typing import List

router = APIRouter(prefix="/users", tags=["Users"])

@router.get("/", response_model=List[UserResponse])
def list_users(db: Session = Depends(get_db)):
    return get_users(db)

@router.get("/{user_id}", response_model=UserResponse)
def read_user(user_id: int, db: Session = Depends(get_db)):
    return get_user(db, user_id)

@router.post("/", response_model=UserResponse)
def create_new_user(user: UserCreate, db: Session = Depends(get_db)):
    return create_user(db, user)

6️⃣ app/main.py（入口文件）

python 复制代码

from fastapi import FastAPI
from app.database import Base, engine
from app.routers import user as user_router

# 创建数据库表
Base.metadata.create_all(bind=engine)

app = FastAPI(title="FastAPI + SQLAlchemy Example")

# 注册路由
app.include_router(user_router.router)

@app.get("/")
def root():
    return {"message": "FastAPI + SQLAlchemy 项目已启动！"}

▶️ 如何运行

目录结构：

your_project/
└── app/
安装依赖：

bash 复制代码

pip install fastapi sqlalchemy uvicorn pydantic email-validator pymysql psycopg2-binary

（按需安装对应数据库驱动）

启动项目：

bash 复制代码

uvicorn app.main:app --reload

打开浏览器访问：

API 文档（自动生成）：
➤ http://127.0.0.1:8000/docs
Root：
➤ http://127.0.0.1:8000/

使用 SQLAlchemy 连接数据库