Expand integration coverage and GaussDB reflection

Author: jarrenL

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+
+      - name: Run unit tests
+        run: pytest -m "not integration"
+
+      - name: Build wheel
+        run: |
+          python -m pip install build
+          python -m build --wheel

README.md

@@ -48,6 +48,13 @@ python -m pip install gaussdb_sqlalchemy_driver-0.1.0-py3-none-any.whl
 
 如果导入时报错 `no pq wrapper available`，通常说明 Python 已经能找到 `gaussdb` 包，但还没有找到可用的 GaussDB 原生客户端库。
 
+可以使用环境检查脚本确认 Python 包和真实连接是否可用：
+
+```powershell
+python scripts\check_windows_env.py
+python scripts\check_windows_env.py --url "gaussdb+gaussdb://user:password@host:port/postgres"
+```
+
 ## SQLAlchemy 使用示例
 
 ```python
@@ -130,9 +137,11 @@ pytest
 
 ```bash
 export GAUSSDB_TEST_URL='gaussdb+gaussdb://user:password@host:port/postgres'
-pytest
+pytest -m integration
 ```
 
+集成测试覆盖 SQLAlchemy Core、事务回滚、批量插入、ORM CRUD、元数据反射和连接池基础复用。
+
 ## 打包
 
 ```bash
@@ -153,7 +162,6 @@ dist/gaussdb_sqlalchemy_driver-0.1.0.tar.gz
 
 后续可以继续补充：
 
-- 真实 GaussDB 环境集成测试
 - SQLAlchemy 方言兼容性测试套件
 - GaussDB 特有 SQL、数据类型和系统表反射适配
 - Windows 离线安装包和部署脚本

docs/常见问题.md

@@ -0,0 +1,79 @@
+# 常见问题
+
+## 1. 这个项目是不是从零实现 GaussDB 协议？
+
+不是。
+
+本项目定位是 GaussDB SQLAlchemy 方言和适配层。底层连接能力复用华为 `gaussdb` Python DB-API 包，项目重点解决 SQLAlchemy 连接串、方言注册、版本识别、连接参数、事务、ORM 和反射等应用侧接入问题。
+
+## 2. 为什么安装了 gaussdb 仍然报 no pq wrapper available？
+
+这表示 Python 已经能找到 `gaussdb` 包，但没有找到可用的 GaussDB/libpq native client 实现。
+
+Windows 上通常需要：
+
+- 安装 GaussDB 客户端包
+- 将客户端 `bin` 目录加入 `PATH`
+- 重新打开终端或重启应用进程
+- 确认 Python 位数和客户端库位数一致
+
+可以运行：
+
+```powershell
+python scripts\check_windows_env.py
+```
+
+## 3. 为什么方言默认设置 client_encoding=UTF8？
+
+部分 GaussDB 环境默认 `client_encoding` 为 `SQL_ASCII`。在这种情况下，底层 `gaussdb` DB-API 会把文本字段返回为 `bytes`。
+
+本项目默认传入：
+
+```text
+client_encoding=UTF8
+```
+
+这样 SQLAlchemy 用户默认拿到 Python `str`。如果确实需要其他编码，可以在连接串中覆盖：
+
+```text
+gaussdb+gaussdb://user:password@host:port/postgres?client_encoding=LATIN1
+```
+
+## 4. 如何跑真实数据库集成测试？
+
+设置环境变量：
+
+```bash
+export GAUSSDB_TEST_URL='gaussdb+gaussdb://user:password@host:port/postgres'
+pytest -m integration
+```
+
+Windows PowerShell：
+
+```powershell
+$env:GAUSSDB_TEST_URL = 'gaussdb+gaussdb://user:password@host:port/postgres'
+pytest -m integration
+```
+
+集成测试会创建并删除 `codex_*_ut` 前缀的临时表。
+
+## 5. 当前已验证哪些 SQLAlchemy 能力？
+
+当前集成测试覆盖：
+
+- SQLAlchemy Core 基础 DDL、DML、查询
+- 事务回滚
+- 批量插入
+- ORM CRUD
+- 元数据反射
+- 连接池基础复用
+
+真实环境中，GaussDB 内核版本会保存在 `dialect.gaussdb_server_version_info`；`dialect.server_version_info` 使用保守的 PostgreSQL 兼容版本，避免 SQLAlchemy 误用 PostgreSQL 新版本系统表字段。
+
+仍需继续验证：
+
+- Windows 实机连接
+- GaussDB 505.1 专项环境
+- SSL 连接
+- Alembic 迁移
+- GaussDB 特有数据类型和系统表差异

docs/验证记录.md

@@ -89,18 +89,40 @@ SQLAlchemy 提示 driver 方言类未显式设置 `supports_statement_cache`。
 supports_statement_cache = True
 ```
 
+### 5. PostgreSQL 新版本系统表字段不兼容
+
+现象：
+
+SQLAlchemy PostgreSQL 方言会根据 `server_version_info` 选择反射查询。GaussDB 返回 `GaussDB Kernel 507.0.0`，如果直接把该版本号作为 PostgreSQL 版本号，SQLAlchemy 会访问当前 GaussDB 不存在或不兼容的系统表字段，例如：
+
+- `pg_attribute.attgenerated`
+- `pg_attribute.attidentity`
+- 与 `pg_type.typcollation` 相关的相关子查询
+
+修复：
+
+- 将 `gaussdb_server_version_info` 保留为真实 GaussDB 内核版本
+- 将 `server_version_info` 映射为保守的 PostgreSQL 兼容版本 `(9, 2)`
+- 覆盖 `get_columns()` 和 `get_multi_columns()`，使用更保守的 GaussDB 兼容系统表查询支持基础列反射
+
 ## 验证结果
 
 真实环境 SQLAlchemy 验证通过：
 
 - 方言 `gaussdb.gaussdb` 可加载
-- `server_version_info` 可识别为 `(507, 0, 0)`
+- `gaussdb_server_version_info` 可识别为 `(507, 0, 0)`
+- `server_version_info` 使用保守的 PostgreSQL 兼容版本，避免 SQLAlchemy 访问当前 GaussDB 不存在的新版本系统表列
 - 默认 schema 可识别为字符串
 - `show client_encoding` 返回 `UTF8`
 - `select 1` 成功
 - 建表成功
 - 插入成功
 - 查询成功
+- 事务回滚成功
+- 批量插入成功
+- SQLAlchemy ORM CRUD 成功
+- SQLAlchemy 元数据反射成功
+- 连接池基础复用成功
 - 文本字段返回 `str`
 - 清理测试表成功
 

scripts/check_windows_env.py

@@ -0,0 +1,84 @@
+"""Check whether the local Python environment can load the GaussDB driver."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import os
+import sys
+from urllib.parse import urlsplit
+from urllib.parse import urlunsplit
+
+
+def _mask_url(url: str) -> str:
+    parts = urlsplit(url)
+    if not parts.password:
+        return url
+    username = parts.username or ""
+    host = parts.hostname or ""
+    port = f":{parts.port}" if parts.port else ""
+    netloc = f"{username}:***@{host}{port}"
+    return urlunsplit((parts.scheme, netloc, parts.path, parts.query, parts.fragment))
+
+
+def _check_import(module_name: str) -> object | None:
+    try:
+        module = importlib.import_module(module_name)
+    except Exception as exc:
+        print(f"[FAIL] import {module_name}: {type(exc).__name__}: {exc}")
+        return None
+
+    version = getattr(module, "__version__", "unknown")
+    print(f"[ OK ] import {module_name}: {version}")
+    return module
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Check GaussDB Python and SQLAlchemy driver availability."
+    )
+    parser.add_argument(
+        "--url",
+        default=os.environ.get("GAUSSDB_TEST_URL"),
+        help="Optional SQLAlchemy URL used for a live select 1 check.",
+    )
+    args = parser.parse_args()
+
+    print(f"Python: {sys.version.split()[0]}")
+    print(f"Executable: {sys.executable}")
+    print(f"PATH: {os.environ.get('PATH', '')}")
+
+    gaussdb = _check_import("gaussdb")
+    sqlalchemy = _check_import("sqlalchemy")
+    dialect = _check_import("gaussdb_sqlalchemy")
+
+    if not all((gaussdb, sqlalchemy, dialect)):
+        print()
+        print("请确认已安装 gaussdb、SQLAlchemy 和本项目 wheel。")
+        print("Windows 上还需要将 GaussDB 客户端 bin 目录加入 PATH。")
+        return 1
+
+    if not args.url:
+        print("[SKIP] 未提供 --url 或 GAUSSDB_TEST_URL，跳过真实连接检查。")
+        return 0
+
+    from sqlalchemy import create_engine
+    from sqlalchemy import text
+
+    print(f"Connecting: {_mask_url(args.url)}")
+    try:
+        engine = create_engine(args.url, pool_pre_ping=True)
+        with engine.connect() as conn:
+            value = conn.execute(text("select 1")).scalar_one()
+            encoding = conn.execute(text("show client_encoding")).scalar_one()
+    except Exception as exc:
+        print(f"[FAIL] live connection: {type(exc).__name__}: {exc}")
+        return 2
+
+    print(f"[ OK ] live connection: select 1 -> {value}")
+    print(f"[ OK ] client_encoding: {encoding}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())