Metadata-Version: 2.4
Name: ns-pydm
Version: 0.0.3
Summary: Dameng (DM) DB-API 2.0 driver implemented on top of JDBC via JPype
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ns-pydm

基于 JDBC + JPype 的达梦（DM）Python 驱动，提供 DB-API 2.0 风格接口，跨平台使用。

## 特性

- DB-API 2.0 风格：`connect()` / `Connection` / `Cursor` / `commit()` / `rollback()`
- 参数绑定：支持 `?` 占位符；兼容把 SQL 中的 `%s`（非引号区域）自动转换为 `?`
- 内置达梦 JDBC 驱动 Jar：安装 Python 包即可使用（仍需本机存在 Java 运行时）
- 自动选择 Jar：根据 `java -version` 探测的 Java 主版本选择对应驱动

## 依赖

- Python 3.7+
- 运行环境需要安装 Java（JRE/JDK），并确保 `java` 在 PATH 中或已配置 `JAVA_HOME`

## 安装

```bash
pip install ns-pydm
```

## 快速开始

```python
import nspydm

conn = nspydm.connect(
    user="SYSDBA",
    password="SYSDBA",
    server="127.0.0.1",
    port=5236,
)

cur = conn.cursor()
cur.execute("select ? as x", [1])
print(cur.fetchone())
conn.close()
```

## 参数绑定

推荐写法（JDBC 原生）：使用 `?`

```python
cur.execute("select ? as x, ? as y", [1, "hello"])
```

兼容写法：使用 `%s`（会转换为 `?`）

```python
cur.execute("select %s as x, %s as y", [1, "hello"])
```

## 事务与自动提交

```python
conn = nspydm.connect(..., autocommit=False)
cur = conn.cursor()
cur.execute("insert into t(a) values(?)", [1])
conn.commit()
```

也可以通过属性开关：

```python
conn.autocommit = True
```

## Schema 切换示例

```python
cur.execute("set schema your_schema")
```

## 连接参数

- `connect(user, password, server, port, dsn, url, autocommit, properties, jars, driver_class)`
- `url` 优先级最高，支持直接传入 `jdbc:dm://host:port` 形式
- `dsn` 传入 `host:port` 时会自动拼接为 `jdbc:dm://{dsn}`

## Jar 选择与 Java 版本识别

- 默认会通过 `java -version` 探测 Java 主版本，并自动选择内置的驱动 Jar：
  - Java 6 -> `DmJdbcDriver6.jar`
  - Java 7 -> `DmJdbcDriver7.jar`
  - Java 8/9/10 -> `DmJdbcDriver8.jar`
  - Java 11+ -> `DmJdbcDriver11.jar`
- 如需自定义或覆盖默认选择：
  - 环境变量：`DM_JDBC_JAR=/abs/path/to/DmJdbcDriver8.jar`
  - 代码传参：`connect(..., jars=["/abs/path/to/DmJdbcDriver8.jar"])`

## 常见问题

1. 提示找不到 `java`
   - 确认已安装 JRE/JDK，并保证 `java -version` 能在命令行执行
2. 连接时报错但信息不全
   - 驱动底层异常会被映射为 DB-API 异常（例如 `OperationalError`），可直接打印异常信息排查
