统一项目名为 gaussdb-sqlalchemy-python-driver

- pyproject.toml: name 改为 gaussdb-sqlalchemy-python-driver
- GitHub URL 更新为 GaussDB-SQLAlchemy-Python-Driver
- 内置 JDBC 驱动 jar 到 whl 包，无需单独下载
- jdbc_driver_path 未指定时自动使用包内 jar
- README 重写：更新兼容模式说明(A=Oracle, B/M=MySQL)
- requires-python 改为 >=3.8
- 修复 BUG 16/18/21/22 (M兼容 TIMESTAMP/concat/lastrowid/LargeBinary)
- 修复测试脚本问题 (edge_cases5-12 全部通过)
- 打包产物加入 dist/

Author: jarrenL

.gitignore

@@ -7,10 +7,6 @@ __pycache__/
 .venv/
 .idea/
 build/
-dist/
 release/
 *.egg-info/
 _local/
-tests/test_edge_cases.py
-tests/test_edge_cases2.py
-tests/test_edge_cases3.py

README.md

@@ -1,187 +1,179 @@
 # GaussDB SQLAlchemy Python 驱动
 
-这是一个面向华为 GaussDB 轻量化集中式 505.1 的 Python SQLAlchemy 方言项目，当前客户目标兼容模式为 A 兼容、B 兼容和 M 兼容。
+面向华为 GaussDB 轻量化集中式的 Python SQLAlchemy 方言驱动。通过 JayDeBeApi/JPype 调用 GaussDB JDBC Driver，接入 SQLAlchemy 的 ORM、连接池、事务、SQL 编译和反射能力。支持 A 兼容（Oracle 风格）、B 兼容（MySQL 风格）和 M 兼容（MySQL 风格）三种模式。
 
-项目采用 JDBC 后端：Python 通过 JayDeBeApi/JPype 调用 GaussDB JDBC Driver，再接入 SQLAlchemy 的 ORM、连接池、事务、SQL 编译和反射能力。该方案面向 Windows 免数据库客户端 DLL 的交付场景。
+JDBC 驱动 jar 已内置在 whl 包中，Windows 上不需要额外安装数据库客户端 DLL，也不需要单独下载 JDBC 驱动。
 
-## 功能特性
+## 前置条件
 
-- 支持 SQLAlchemy 2.x
-- 支持 `gaussdb://...` 连接串
-- 支持 `gaussdb+jdbc://...` 连接串
-- 底层使用 JayDeBeApi、JPype1 和 GaussDB JDBC Driver
-- Windows 不需要额外安装数据库客户端 DLL
-- 面向 GaussDB 轻量化集中式 505.1 的 A 兼容、B 兼容和 M 兼容场景
-- 默认关闭 HSTORE 等 PostgreSQL 扩展假设，适合轻量化集中式部署
+- Python 3.8 及以上
+- JRE 或 JDK 8 及以上（Java 运行环境）
 
 ## 安装
 
-### Windows
-
-```powershell
-py -3.11 -m venv .venv
-.\.venv\Scripts\Activate.ps1
-python -m pip install --upgrade pip
-python -m pip install gaussdb_sqlalchemy_driver-0.1.0-py3-none-any.whl
-```
-
-还需要准备：
-
-- Java Runtime，建议 JDK/JRE 8 或 11 及以上
-- GaussDB JDBC Driver jar，例如 `gsjdbc4.jar`
-
-### Linux 或 macOS
-
 ```bash
-python3 -m venv .venv
-. .venv/bin/activate
-python -m pip install --upgrade pip
-python -m pip install gaussdb_sqlalchemy_driver-0.1.0-py3-none-any.whl
+pip install gaussdb_sqlalchemy_driver-0.1.0-py3-none-any.whl
 ```
 
-## SQLAlchemy 使用示例
+安装后自动拉取 SQLAlchemy、JayDeBeApi、JPype1 三个依赖。JDBC 驱动 jar 已内置，无需额外下载。
+
+## 快速开始
 
 ```python
 from sqlalchemy import create_engine, text
 
+# 不需要指定 jar 路径，driver 自动使用包内置的 JDBC 驱动
 engine = create_engine(
-    "gaussdb+jdbc://user:password@127.0.0.1:8000/postgres"
-    "?jdbc_driver_path=C:/GaussDB/jdbc/gsjdbc4.jar",
+    "gaussdb+jdbc://sqlbuilder1:huawei%40123@127.0.0.1:8000/postgres?sslmode=disable",
     pool_pre_ping=True,
 )
 
-with engine.begin() as conn:
+with engine.connect() as conn:
     print(conn.execute(text("select 1")).scalar_one())
 ```
 
-默认 JDBC 驱动类名为：
-
-```text
-com.huawei.gaussdb.jdbc.Driver
-```
+密码中如包含 `@` 等特殊字符，需要 URL 编码。例如 `password@123` 应写为 `password%40123`。
 
-当前华为 GaussDB JDBC jar 使用该驱动类名。如果实际 jar 使用其他驱动类名，可以显式指定：
+## 连接串格式
 
 ```text
-gaussdb+jdbc://user:password@127.0.0.1:8000/postgres?jdbc_driver_class=com.huawei.gaussdb.jdbc.Driver&jdbc_driver_path=C:/GaussDB/jdbc/gaussdbjdbc-506.0.0.b058-jdk7.jar
+gaussdb+jdbc://用户名:密码@主机:端口/数据库名?sslmode=disable
 ```
 
-也可以完全覆盖 JDBC URL：
+也支持短格式：
 
 ```text
-gaussdb+jdbc://user:password@placeholder/postgres?jdbc_url=jdbc:gaussdb://127.0.0.1:8000/postgres&jdbc_driver_path=C:/GaussDB/jdbc/gaussdbjdbc-506.0.0.b058-jdk7.jar
+gaussdb://用户名:密码@主机:端口/数据库名?sslmode=disable
 ```
 
-## 连接串格式
-
-推荐格式：
+如果需要使用自己的 JDBC 驱动（比如不同版本），可以通过 `jdbc_driver_path` 覆盖内置驱动：
 
 ```text
-gaussdb+jdbc://用户名:密码@主机:端口/数据库名?jdbc_driver_path=JDBC驱动jar路径
+gaussdb+jdbc://用户名:密码@主机:端口/数据库名?jdbc_driver_path=/path/to/your/gsjdbc4.jar&sslmode=disable
 ```
 
-短格式 `gaussdb://...` 也会使用 JDBC 方言：
+其他可选参数：
 
-```text
-gaussdb://用户名:密码@主机:端口/数据库名?jdbc_driver_path=JDBC驱动jar路径
-```
+- `jdbc_driver_class` — 指定 JDBC 驱动类名，默认 `com.huawei.gaussdb.jdbc.Driver`
+- `jdbc_url` — 完全覆盖底层 JDBC URL
 
-密码中如包含 `@` 等特殊字符，需要 URL 编码。例如 `password@123` 应写为 `password%40123`。
+## ORM 用法
 
-## 开发和测试
+```python
+from sqlalchemy import create_engine, Column, Integer, String, DateTime
+from sqlalchemy.orm import Session, declarative_base
+from datetime import datetime
 
-```bash
-python3 -m venv .venv
-. .venv/bin/activate
-python -m pip install --upgrade pip
-python -m pip install -e ".[test]"
-pytest
-```
+engine = create_engine(
+    "gaussdb+jdbc://sqlbuilder1:huawei%40123@127.0.0.1:8000/testm?sslmode=disable",
+    pool_pre_ping=True,
+)
 
-如果要连接真实 GaussDB 环境执行集成测试，可以设置：
+Base = declarative_base()
 
-```bash
-export GAUSSDB_TEST_URL='gaussdb+jdbc://user:password@host:port/postgres?jdbc_driver_path=/path/to/gsjdbc4.jar'
-pytest -m integration
-```
+class User(Base):
+    __tablename__ = "users"
+    id = Column(Integer, primary_key=True)
+    name = Column(String(50))
+    created = Column(DateTime)
 
-如果要一次性验证 A/B/M 三种兼容库，可以分别设置：
+Base.metadata.create_all(engine)
 
-```bash
-export GAUSSDB_TEST_URL_A='gaussdb+jdbc://user:password@host:port/a_database?jdbc_driver_path=/path/to/gaussdbjdbc.jar'
-export GAUSSDB_TEST_URL_B='gaussdb+jdbc://user:password@host:port/b_database?jdbc_driver_path=/path/to/gaussdbjdbc.jar'
-export GAUSSDB_TEST_URL_M='gaussdb+jdbc://user:password@host:port/m_database?jdbc_driver_path=/path/to/gaussdbjdbc.jar'
-pytest tests/test_compatibility_scenarios.py -m integration
+with Session(engine) as session:
+    session.add(User(name="张三", created=datetime.now()))
+    session.commit()
+    users = session.query(User).all()
+    for u in users:
+        print(u.id, u.name, u.created)
 ```
 
-也可以使用逗号分隔的 `GAUSSDB_TEST_URLS` 批量传入多个真实库连接串。
-
-没有安装 pytest 的数据库主机也可以运行轻量探针：
-
-```bash
-GAUSSDB_TEST_URL='gaussdb+jdbc://user:password@host:port/postgres?jdbc_driver_path=/path/to/gsjdbc4.jar' \
-python scripts/run_integration_probe.py
-```
+## 兼容模式支持
 
-如果要快速判断当前库对 PostgreSQL、Oracle 风格、MySQL 风格 SQL 的接受情况，可以运行：
+驱动自动检测数据库的兼容模式（A/B/M）并适配 SQL 方言差异：
 
-```bash
-GAUSSDB_TEST_URL='gaussdb+jdbc://user:password@host:port/postgres?jdbc_driver_path=/path/to/gsjdbc4.jar' \
-python scripts/run_syntax_probe.py
-```
+| 特性 | A 兼容 (Oracle) | B 兼容 (MySQL) | M 兼容 (MySQL) |
+|------|----------------|----------------|----------------|
+| 标识符引号 | 双引号 | 双引号/反引号 | 反引号 |
+| 自增主键 | serial | serial/AUTO_INCREMENT | AUTO_INCREMENT |
+| ORM INSERT 获取自增 ID | RETURNING | RETURNING | LAST_INSERT_ID() |
+| 字符串拼接 | \|\| | \|\| | CONCAT() |
+| TIMESTAMP 精度 | 默认无 | 默认无 | TIMESTAMP(6) |
+| Oracle 语法 (DUAL/NVL/SYSDATE) | 支持 | 支持 | 不支持 |
+| 隔离级别 | 全部支持 | 全部支持 | REPEATABLE READ（SERIALIZABLE 不支持） |
 
-Windows 实机测试步骤、前置条件、测试场景和真实数据库地址配置方式见 [docs/Windows测试指导手册.md](docs/Windows测试指导手册.md)。
+驱动还支持 Alembic 迁移工具，包括 batch_alter_table 和 autogenerate。
 
-## 验证覆盖
+## 功能特性
 
-集成测试覆盖：
+- SQLAlchemy 2.x Core + ORM 完整支持
+- 连接池、事务、保存点
+- 表/列/索引/约束/视图/注释反射
+- Alembic 迁移集成（batch mode + autogenerate）
+- 全部标准 SQL 数据类型（Integer、String、Text、DateTime、Numeric、Boolean、LargeBinary 等）
+- A/B/M 三种兼容模式自动检测和适配
 
-- SQLAlchemy Core DDL、DML、查询
-- 真实表生命周期：建表、表存在性检查、插入、查询、更新、删除和清理
-- 事务回滚
-- 批量插入
-- ORM CRUD
-- 元数据反射
-- 常用数据类型
-- 主键、唯一约束、普通索引反射
-- 序列和默认值
-- Alembic Operations
-- Alembic autogenerate 基础无差异检测
-- 复杂索引、表达式索引、视图反射和分区表反射
-- 连接池基础复用
-- A/B/M 兼容语法场景，包括 Oracle 风格、MySQL 风格、`serial`、`auto_increment`、`nextval` 和表达式索引
+## 已知限制
 
-## 适配范围
+- **ON CONFLICT**：GaussDB 集中式不支持 PostgreSQL `ON CONFLICT` upsert 语法
+- **M 兼容 LIKE**：默认大小写不敏感（MySQL 行为）；A/B 兼容为大小写敏感
+- **M 兼容集合运算**：不支持 `INTERSECT` / `EXCEPT`
+- **M 兼容临时表**：不支持 `CREATE TEMP TABLE`，需用 `CREATE TEMPORARY TABLE`
+- **M 兼容 CAST**：不支持 `CAST(x AS VARCHAR)`，需用 `CAST(x AS CHAR)`
+- **M 兼容 TIMESTAMP DEFAULT**：`TIMESTAMP(6) DEFAULT current_timestamp` 不被支持
+- **M 兼容 TEXT**：最大 65535 字节
+- **Decimal 精度**：GaussDB/JDBC 侧对超过 15 位有效数字的 Decimal 有精度损失
+- **SERIALIZABLE 隔离级别**：GaussDB 集中式不支持，静默降级为 REPEATABLE READ
 
-当前版本面向 GaussDB 轻量化集中式 505.1 的 A 兼容、B 兼容和 M 兼容基础 SQLAlchemy 接入场景，适合应用侧先完成连接、查询、事务、连接池和 ORM 基础能力适配。
+## 并发限制
 
-已在 GaussDB Kernel 507.0.0 环境验证过 A 兼容、B 兼容和 M 兼容基础能力。GaussDB 505.1、Windows 实机和客户真实库仍需按测试指导手册继续验证。
+通过 JayDeBeApi/JPype 在 Python 进程内调用 JVM。`threadsafety = 1`，模块可被多线程共享，但连接对象不应跨线程共享。建议每个线程从 SQLAlchemy engine 独立获取连接。
 
-## 已知限制
+## 开发和测试
 
-- GaussDB 集中式不支持 PostgreSQL `ON CONFLICT` upsert 语法。SQLAlchemy PostgreSQL 方言的 `insert(...).on_conflict_do_update()` 会生成 `ON CONFLICT` SQL，当前版本仅声明该限制，不做自动改写。
-- M 兼容下 `LIKE` 默认大小写不敏感，符合 MySQL 风格行为；A/B 兼容下 `LIKE` 为大小写敏感。跨兼容模式迁移时需要单独确认查询语义。
-- M 兼容下不支持 `INTERSECT` / `EXCEPT` 集合运算；SQLAlchemy 的 `intersect()` / `except_()` 在 M 兼容库上会由数据库返回语法错误。
-- M 兼容下 raw SQL `CREATE TEMP TABLE` 不支持，需使用 `CREATE TEMPORARY TABLE`；通过 SQLAlchemy 创建临时表时建议显式使用 `prefixes=["TEMPORARY"]`。
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install --upgrade pip
+pip install -e ".[test]"
+pytest
+```
 
-## 并发限制
+连接真实 GaussDB 环境跑集成测试：
 
-本项目通过 JayDeBeApi/JPype 在 Python 进程内调用 JVM。`threadsafety = 1`，表示模块可被多线程共享，但连接对象不应跨线程共享。建议每个线程独立从 SQLAlchemy engine 获取连接，并避免在 JVM 首次启动阶段做高并发连接初始化。
+```bash
+export GAUSSDB_TEST_URL_A='gaussdb+jdbc://user:password@host:port/a_db?sslmode=disable'
+export GAUSSDB_TEST_URL_B='gaussdb+jdbc://user:password@host:port/b_db?sslmode=disable'
+export GAUSSDB_TEST_URL_M='gaussdb+jdbc://user:password@host:port/m_db?sslmode=disable'
+pytest -m integration
+```
 
 ## 打包
 
 ```bash
-python -m pip install build
+pip install build
 python -m build
 ```
 
-打包后文件会生成在 `dist/` 目录：
+打包产物在 `dist/` 目录，whl 约 1.5MB（含内置 JDBC 驱动）。
 
-```text
-dist/gaussdb_sqlalchemy_driver-0.1.0-py3-none-any.whl
-dist/gaussdb_sqlalchemy_driver-0.1.0.tar.gz
+## 技术架构
+
+```
+Python 应用
+    ↓
+SQLAlchemy (ORM / Core)
+    ↓
+GaussDB SQLAlchemy Dialect (本驱动)
+    ↓
+JayDeBeApi + JPype1
+    ↓
+JVM (JRE/JDK 8+)
+    ↓
+GaussDB JDBC Driver (内置 jar)
+    ↓
+GaussDB 集中式
 ```
 
 ## 开源协议
 
-本项目采用 Apache License 2.0 开源协议发布，详见 [LICENSE](LICENSE)。
+Apache License 2.0

dist/gaussdb_sqlalchemy_driver-0.1.0-py3-none-any.whl

@@ -3,11 +3,11 @@ requires = ["setuptools>=69", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "gaussdb-sqlalchemy-driver"
+name = "gaussdb-sqlalchemy-python-driver"
 version = "0.1.0"
 description = "Lightweight SQLAlchemy JDBC dialect for Huawei GaussDB centralized 505.1."
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.8"
 license = "Apache-2.0"
 authors = [{ name = "GaussDB Python Driver Contributors" }]
 keywords = ["gaussdb", "sqlalchemy", "database", "driver", "windows"]
@@ -17,6 +17,7 @@ classifiers = [
     "Operating System :: Microsoft :: Windows",
     "Operating System :: POSIX",
     "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -38,8 +39,8 @@ test = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/jarrenL/GaussDB-Python-Driver"
-Issues = "https://github.com/jarrenL/GaussDB-Python-Driver/issues"
+Homepage = "https://github.com/jarrenL/GaussDB-SQLAlchemy-Python-Driver"
+Issues = "https://github.com/jarrenL/GaussDB-SQLAlchemy-Python-Driver/issues"
 
 [project.entry-points."sqlalchemy.dialects"]
 gaussdb = "gaussdb_sqlalchemy.jdbc:GaussDBDialect_jdbc"
@@ -48,6 +49,9 @@ gaussdb = "gaussdb_sqlalchemy.jdbc:GaussDBDialect_jdbc"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+gaussdb_sqlalchemy = ["gaussdbjdbc.jar"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]