FastAPI 项目的数据库配置总是在折腾？这才是更优雅的解决方案！

在之前的文章里，我们已经聊了如何搭建一个“工业级”的 FastAPI 项目结构，以及如何用 uv 将 Python 环境和依赖“关进笼子”，保持主机的绝对清爽。

有了这些准备，启动一个后端项目似乎轻而易举。但多数时候，一个真正的噩梦才刚刚开始——数据库的安装与配置。

你是否也经历过在本地安装 PostgreSQL 的折磨？为了一次小练习，去官网下载几百兆的安装包，小心翼翼地配置用户、密码、端口，结果却因为版本冲突、防火墙、或是神秘的环境变量问题，在终端里看到一串串刺眼的红色错误。

这种把时间浪费在“环境内耗”上的感觉，足以浇灭所有开发热情。

今天，我们就来终结这场噩梦。

😫 本地安装 PostgreSQL，新手的“九九八十一难”

如果你觉得上面的吐槽过于夸张，不妨看看新手在本地安装 PostgreSQL 时，通常会踩哪些坑：

• • 环境配置复杂：
  • • 不同操作系统（Windows/macOS/Linux）的安装命令和依赖库天差地别，环境变量配错一个字母就前功尽弃。
  • • PostgreSQL 版本与 Python 驱动 psycopg2 的兼容性问题，常常导致连接失败。
• • 安装配置困难：
  • • 安装过程中的用户、密码、端口设置，对新手极不友好。
  • • 默认配置可能并不适合开发，比如性能和安全设置都需要额外调整。
• • 连接问题频发：
  • • 连接字符串 postgresql://user:password@localhost:5432/dbname 格式写错是家常便饭。
  • • 5432 端口被其他程序占用，或者本地防火墙拦截，排查起来非常头疼。
• • 调试如大海捞针：
  • • PostgreSQL 的错误日志（如权限问题、连接超时）对新手来说如读天书，调试极其耗时。
  • • 在本地运行的数据库实例会持续占用大量系统资源，让你的开发机不堪重负。

如果说 uv 是为了解决 Python 环境的混乱，那么 Docker 就是为了解决 服务环境 的混乱。我们的核心理念一脉相承：把一切都关进独立的“笼子”，让你的开发机永远保持干净。

🆚 本地安装 vs Docker：一张图看懂差距

既然本地能装，为什么还要多学一个 Docker？因为它不是在做重复的事，而是在降维打击。

简单总结：

• • 本地安装：像是学开手动挡，需要你对车（数据库）的机械原理有深入了解，适合需要高度定制的专家。
• • Docker Compose：像是开自动挡，你只需踩油门（up）和刹车（down），它负责处理所有复杂的底层操作，极度适合新手和追求效率的开发者。

🚀 一行命令，启动你的专属数据库

说了这么多，用 Docker 部署到底有多简单？

两步走：创建配置文件 -> 运行命令。

1. 1. 在你项目的根目录（或者任何你喜欢的地方）创建一个 docker-compose.yml 文件。
2. 2. 把下面的内容复制进去：

# docker-compose.yml

# 定义项目名称，方便在 Docker Desktop 中识别
name: my-fastapi-services

services:
  # 定义一个名为 'db' 的服务
  db:
    # 使用 Bitnami 优化过的 PostgreSQL 最新版镜像
    image: bitnami/postgresql:latest
    # 给容器取一个好记的名字
    container_name: my_postgres_db
    # 端口映射: 将本机的 5432 端口映射到容器的 5432 端口
    # 这样我们的 FastAPI 应用就能通过 localhost:5432 连接到它
    ports:
      - "5432:5432"
    # 环境变量: 用于初始化数据库
    environment:
      - POSTGRES_USER=myuser         # 设置用户名
      - POSTGRES_PASSWORD=mypassword # 设置密码
      - POSTGRES_DB=mydatabase       # 设置要创建的数据库名
    # 数据卷: 将容器内的数据持久化到本地
    # 即使容器被删除，数据也不会丢失
    volumes:
      - postgres_data:/bitnami/postgresql
    # 重启策略: 除非手动停止，否则容器总会自动重启
    restart: unless-stopped

# 定义数据卷
volumes:
  postgres_data:
    driver: local

1. 3. 在终端里，进入 docker-compose.yml 文件所在的目录，然后运行：

docker compose up -d

-d 的意思是 detached，即在后台运行。

好了，收工。一个配置齐全、性能稳定的 PostgreSQL 数据库已经在后台为你 24 小时待命了。你可以在 Docker Desktop 里看到它。

🔗 如何在 FastAPI 中连接它？

光说不练假把式。让我们用代码来验证一下。

1. 安装必要的库：
我们不仅需要 fastapi，还需要 SQLAlchemy (ORM) 和 psycopg2-binary (PG 驱动)。

# 使用我们上一篇文章学到的 uv
uv add "fastapi[standard]" sqlalchemy psycopg2-binary

2. 编写测试代码 main.py:

# main.py
from fastapi import FastAPI
from sqlalchemy import create_engine, text
from sqlalchemy.exc import OperationalError

app = FastAPI()

# 数据库连接信息
DATABASE_URL = "postgresql://myuser:mypassword@localhost:5432/mydatabase"

engine = create_engine(DATABASE_URL)

@app.get("/")
def check_db_connection():
    try:
        # 尝试建立连接
        with engine.connect() as connection:
            # 执行一个简单的查询
            result = connection.execute(text("SELECT 1"))
            if result.scalar() == 1:
                return {"message": "✅ 数据库连接成功！"}
    except OperationalError as e:
        return {"message": f"❌ 数据库连接失败: {e}"}

3. 运行 FastAPI 应用：

uv run uvicorn main:app --reload

现在访问 http://127.0.0.1:8000，如果看到 {"message":"✅ 数据库连接成功！"}，恭喜你，已经打通了整个流程！

⚙️ Docker 常用管理命令

管理这个数据库，你只需要记住下面几个命令：

• • 启动服务：docker compose up -d
• • 停止服务：docker compose down (容器停止，但数据卷还在)
• • 彻底删除服务和数据：docker compose down -v (-v 代表删除 volumes)
• • 查看日志：docker compose logs db (db 是我们服务名)
• • 升级版本：想升级到最新版？只需两步：

1. 1. docker compose pull (拉取镜像的最新版)
2. 2. docker compose up -d (用新镜像重建容器)

Pro Tip: 我建议你建立一个名为 dev-services 的文件夹，专门用来存放各种服务的 docker-compose.yml 文件（比如 postgres/、redis/ 等）。需要哪个服务，就进入对应文件夹执行 up，用完执行 down，极度清爽。

总结：你的现代化开发工作流

至此，我们已经集齐了现代化 FastAPI 开发的三颗“龙珠”：

1. 1. 项目结构：清晰的代码组织。
2. 2. uv：干净的 Python 环境。
3. 3. Docker：独立的服务环境。

你不再需要在自己的电脑上安装任何与项目直接相关的软件。一个新项目开始，你只需要 uv init、写好 docker-compose.yml，然后就可以把 100% 的精力投入到最有价值的业务逻辑开发中。

现在，去创造吧！