FastAPI连接Oracle数据库教程

本教程详细阐述了如何使用FastAPI和SQLAlchemy连接并查询Oracle数据库中已存在的表。文章首先澄清了`Base.metadata.create_all()`在处理现有表时的默认行为，随后重点介绍了通过SQLAlchemy的反射机制，以声明式映射方式优雅地将Python模型与现有数据库表进行关联，并提供了完整的FastAPI接口示例，确保开发者能够高效、准确地操作现有数据库资产。

在现代Web应用开发中，特别是在构建微服务架构时，经常需要与已有的数据库进行交互。FastAPI因其高性能、易用性和自动文档生成能力，成为构建API的流行选择。而SQLAlchemy作为Python中最强大、最灵活的ORM（对象关系映射）工具之一，能有效管理数据库交互。本文将聚焦于一个常见但可能令人困惑的场景：如何使用FastAPI和SQLAlchemy连接并查询Oracle数据库中已存在的表，并解决开发者可能遇到的关于Base.metadata.create_all()的疑问。

理解 Base.metadata.create_all() 的默认行为

许多开发者在使用SQLAlchemy时，习惯于在定义模型后调用Base.metadata.create_all(bind=engine)来创建数据库表。然而，当数据库中表已存在时，会担心此操作是否会引发错误或重新创建表。

实际上，Base.metadata.create_all() 方法有一个关键参数 checkfirst，其默认值为 True。这意味着在尝试创建任何表之前，SQLAlchemy会首先检查该表是否已存在于数据库中。如果表已存在，它将跳过创建操作，从而避免了重复创建表可能导致的错误。因此，对于一个已存在的表，即使调用create_all，通常也不会导致问题。

以下是原始代码片段，它在处理现有表时并不会出错：

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, Session
import cx_Oracle

from fastapi import Depends, FastAPI
from sqlalchemy import Column, Integer, String

# 初始化Oracle客户端 (路径需根据实际情况配置)
# cx_Oracle.init_oracle_client(lib_dir=r"E:\instantclient-basic-windows.x64-12.1.0.2.0\instantclient_12_1")

# 数据库连接字符串
my_database_connection = "oracle+cx_oracle://super:password@localhost:1521/db" # 请替换为您的实际连接信息

engine = create_engine(my_database_connection)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

class table1(Base):
    __tablename__ = "table1"
    # 假设CN是主键，或者有唯一约束
    CN = Column(String(length=256), primary_key=True) # 假设CN是主键
    NAME = Column(String(length=40))
    EMAIL = Column(String(length=20))

# 即使table1已存在，此行也不会重新创建它，因为checkfirst=True是默认行为
Base.metadata.create_all(bind=engine) 

app = FastAPI()

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

@app.get("/table_api/")
def read_users(db:Session = Depends(get_db)):
    cninformation = db.query(table1).all()
    return cninformation

尽管上述代码在功能上是正确的，但对于处理现有数据库表，SQLAlchemy提供了更明确和专业的“反射”机制。

声明式映射与现有表的反射机制

当数据库结构已由DBA管理或由其他系统生成时，我们通常不希望ORM去创建或修改表结构。此时，SQLAlchemy的反射机制允许我们“映射”到已存在的数据库表，而不是通过Python模型来定义它们。

以下是使用反射机制来连接和查询现有Oracle表的详细步骤及示例代码：

1. 初始化Oracle客户端与数据库连接

确保cx_Oracle库已安装，并且Oracle Instant Client已配置。cx_Oracle.init_oracle_client函数用于指定Instant Client的路径。

import cx_Oracle
# 请根据您的Oracle Instant Client实际安装路径进行配置
# cx_Oracle.init_oracle_client(lib_dir=r"E:\instantclient-basic-windows.x64-12.1.0.2.0\instantclient_12_1")

然后，配置数据库连接字符串并创建SQLAlchemy的引擎和会话工厂。

from sqlalchemy import create_engine, Column, String, Table, MetaData
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, Session
from fastapi import Depends, FastAPI

# 数据库连接配置
# 格式: oracle+cx_oracle://user:password@host:port/service_name
# 或者 oracle+cx_oracle://user:password@tnsname
my_database_connection = "oracle+cx_oracle://super:password@localhost:1521/db" # 替换为您的实际连接信息
engine = create_engine(my_database_connection)

# 创建数据库会话工厂
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# 创建声明式基类
Base = declarative_base()

# 创建MetaData对象，用于管理数据库元数据和反射表结构
metadata = MetaData() 

2. 定义反射模型

与直接声明模型不同，反射模型通过Table对象来映射现有表。我们使用Table('your_table_name', metadata, autoload_with=engine)来指示SQLAlchemy从数据库中加载指定表的结构。

class Table1(Base):
    __tablename__ = "table1" # 数据库中的实际表名

    # 关键：通过反射机制加载表结构
    # autoload_with=engine 会指示SQLAlchemy连接到数据库并加载'table1'的列信息
    __table__ = Table(__tablename__, metadata, autoload_with=engine) 

    # 如果需要，可以在这里定义额外的Python属性或方法
    # 例如，定义一个 __repr__ 方法方便调试
    def __repr__(self):
        # 假设CN是表中的一个列，通过反射获得
        return f""

说明：

• __tablename__ 仍然用于指定数据库中的表名。
• __table__ = Table(__tablename__, metadata, autoload_with=engine) 是反射的关键。它告诉SQLAlchemy，这个Python类Table1应该映射到数据库中名为table1的表，并且其列结构应该通过engine从数据库中自动加载。
• 一旦__table__被反射，您就不需要在Python类中手动定义所有列（如CN = Column(...)），因为这些信息将自动从数据库中获取。

3. 构建FastAPI应用与查询接口

现在，我们可以将反射模型集成到FastAPI应用中，并定义API接口来查询数据。

app = FastAPI()

# 数据库会话依赖函数
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

# 定义API接口
@app.get("/table_api/")
def read_table_data(db: Session = Depends(get_db)):
    """
    查询table1表的所有数据。
    """
    # 使用反射模型Table1进行查询
    data = db.query(Table1).all()
    return data

# 运行FastAPI应用
# 可以通过命令行运行：uvicorn your_script_name:app --reload
# 假设您的脚本名为 main.py，则运行：uvicorn main:app --reload

完整示例代码

将上述所有部分整合，形成一个完整的FastAPI应用，用于查询Oracle数据库中的现有表：

from sqlalchemy import create_engine, Table, MetaData
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, Session
import cx_Oracle
from fastapi import Depends, FastAPI

# --- 1. 初始化Oracle客户端 (根据您的实际环境配置) ---
# cx_Oracle.init_oracle_client(lib_dir=r"E:\instantclient-basic-windows.x64-12.1.0.2.0\instantclient_12_1")

# --- 2. 数据库连接配置 ---
# 请替换为您的实际Oracle数据库连接信息
my_database_connection = "oracle+cx_oracle://super:password@localhost:1521/db" 
engine = create_engine(my_database_connection)

# 创建数据库会话工厂
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# 创建声明式基类和MetaData对象
Base = declarative_base()
metadata = MetaData() 

# --- 3. 定义反射模型 ---
class Table1(Base):
    __tablename__ = "table1" # 数据库中的实际表名
    # 通过反射机制加载表结构
    __table__ = Table(__tablename__, metadata, autoload_with=engine) 

    def __repr__(self):
        # 假设CN, NAME, EMAIL是表中的列，通过反射获得
        return f""

# --- 4. FastAPI应用初始化 ---
app = FastAPI()

# --- 5. 数据库会话依赖函数 ---
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

# --- 6. 定义API接口 ---
@app.get("/table_api/")
def read_table_data(db: Session = Depends(get_db)):
    """
    查询table1表的所有数据。
    """
    data = db.query(Table1).all()
    return data

# --- 7. 运行FastAPI应用 (通过命令行) ---
# 将此代码保存为例如 main.py
# 在命令行中运行：uvicorn main:app --reload
# 然后访问 http://127.0.0.1:8000/table_api/ 查看结果

注意事项与最佳实践

1. cx_Oracle客户端路径: 确保cx_Oracle.init_oracle_client中的lib_dir指向正确的Oracle Instant Client路径。在生产环境中，可能需要确保环境变量（如LD_LIBRARY_PATH或PATH）已正确配置，以便系统能找到Oracle客户端库。
2. 数据库连接字符串安全: 数据库密码等敏感信息绝不应硬编码在代码中。应通过环境变量、配置文件（如.env文件配合python-dotenv）或密钥管理服务来安全地管理这些凭据。
3. 模型命名规范: Python类名通常使用驼峰命名法（如Table1），而数据库表名通常是小写或下划线命名（如table1）。保持这种约定有助于代码的可读性。
4. 反射的优势: 当数据库结构由DBA管理或可能频繁变更时，反射机制能让ORM模型自动适应这些变化，减少手动维护模型定义的开销，提高系统的健壮性。
5. 错误处理: 在实际应用中，应添加更完善的错误处理机制，例如数据库连接失败、查询无结果、权限不足等情况，以提供友好的用户体验和更稳定的服务。
6. 多表反射: 如果有多个表需要反射，可以为每个表创建相应的反射模型类，遵循相同的模式。
7. 主键和索引: 虽然反射会自动加载列信息，但SQLAlchemy通常需要知道表的主键才能执行某些ORM操作（如按ID查询）。反射通常会正确识别主键。如果反射未正确识别，您可能需要在模型中显式指定。

总结

本文详细介绍了在FastAPI应用中，如何利用SQLAlchemy连接并查询Oracle数据库中已存在的表。我们首先澄清了Base.metadata.create_all()在处理现有表时的默认行为，即其checkfirst=True的默认设置会避免重复创建表。随后，我们重点讲解了通过声明式映射结合反射机制来优雅地处理现有数据库表，这种方式更符合操作现有数据库的专业实践。通过掌握这些方法，开发者可以避免重复定义已有的表结构，使代码更加健壮和易于维护，从而更高效地开发与现有数据库集成的FastAPI应用。