Skip to content

PostgreSQL安装与使用 ​

PostgreSQL ​

介绍 ​

PostgreSQL

  • 特点:功能强大、支持 JSON、地理空间数据、全文搜索等高级特性。
  • 适用场景:需要事务、强一致性、复杂查询的中大型项目。
  • 推荐组合:FastAPI + SQLAlchemy(异步) + PostgreSQL + asyncpg(异步驱动)

Docker安装PostgreSQL ​

安装准备工作

  • Windows 上安装 WSL2
  • WSL2 上安装 Ubuntu 22.04
  • Ubuntu 22.04 上安装Docker

下载镜像:2026年10月,首选 PostgreSQL 17.11,次选 PostgreSQL 16.15

bash
docker pull postgres:17.11

运行镜像

bash
# 建立数据目录
mkdir -p /opt/pgdata
cd /opt/pgdata

docker run -d --name postgres17 --restart unless-stopped \
  -e POSTGRES_DB=my-rag \
  -e POSTGRES_USER=root \
  -e POSTGRES_PASSWORD=123456Abcd \
  -p 5432:5432 \
  -v /opt/pgdata:/var/lib/postgresql/data \
  postgres:17.11

安装包安装PostgreSQL ​

安装包下载地址:双击默认安装

连接PostgreSQL ​

使用DBeaver工具,连接PostgreSQL

  • 主机:填写宿主机IP地址

image-20260205101913610

数据库结构的组织层次

  • 模式(Schema) 是PostgreSQL 中用于组织数据库对象(如表、视图、索引、函数等)的命名空间。
  • 默认情况下,每个新数据库都会自带一个名为 public 的 schema。
bash
服务器(Server)
 └── 数据库(Database)
      └── 模式(Schema)
           └── 表(Table)、视图(View)、函数(Function)等数据库对象

FastAPI集成 ​

安装与配置 ​

安装

bash
pip install asyncpg

配置

python
DB_USER: str = "root"
DB_PASSWORD: str = "your_password"
DB_HOST: str = "127.0.0.1"
DB_PORT: int = 5432
DB_NAME: str = "my-rag"

ASYNC_DATABASE_URL: str = f"postgresql+asyncpg://{self.DB_USER}:{self.DB_PASSWORD}@{self.DB_HOST}:{self.DB_PORT}/{self.DB_NAME}"

获取 DB Session

python
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, Session
from typing import AsyncGenerator, Generator

from .settings import settings


# 创建异步引擎
async_engine = create_async_engine(
    url=ASYNC_DATABASE_URL,
    echo=False,  # 是否打印执行的 SQL 语句
    pool_size=10,  # 连接池大小
    max_overflow=20,  # 最大溢出连接数
)


# 创建异步会话
async_session = async_sessionmaker(
    bind=async_engine,  # 绑定异步数据库引擎
    class_=AsyncSession,  # 使用异步会话
    expire_on_commit=False,  # 在事务提交后不会使对象过期
)


async def get_db() -> AsyncGenerator[AsyncSession, None]:
    """依赖项:获取数据库会话"""
    async with async_session() as session:
        try:
            yield session  # 返回数据库会话
            await session.commit()
        except Exception as e:
            await session.rollback()
            raise e
        finally:
            await session.close()

使用 ​

示例

python
from typing import List
from fastapi import APIRouter, File, UploadFile, Response, Depends, Query
from sqlalchemy.ext.asyncio import AsyncSession
from urllib.parse import quote

from app.config.db_config import get_db
from app.config.response_config import SuccessResponse
from app.config.exception_config import BusinessException
from .crud import (
    get_document_list_by_kb_id_crud,
    get_document_crud,
)
from .schema import DocumentResponseSchema, BatchUploadResponse
from .service import DocumentService

router = APIRouter(prefix="/document", tags=["文档管理"])

@router.get(
    "/{document_id}",
    summary="获取文档详情",
    response_model=SuccessResponse[DocumentResponseSchema],
)
async def get_document_detail(document_id: int, db: AsyncSession = Depends(get_db)):
    """
    根据document_id获取文档详情
    """
    document = await get_document_crud(db, document_id)
    if not document:
        raise BusinessException(code=404, msg="文档记录不存在")
    return SuccessResponse(msg="获取文档详情成功", data=document)