Metadata-Version: 2.4
Name: ezr-database-sdk
Version: 0.1.3
Summary: Synchronous read-only EZR brand database metadata and table routing SDK
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyMySQL>=1.0.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=5.0; extra == "release"

# EZR Database SDK

公司内部数据库元数据 SDK，提供同步、只读的 Python 接口：

- 多环境基础库配置，实例间连接隔离。
- 查询品牌的业务库连接节点和分表配置。
- 根据整数或字符串 ID 计算物理表名，兼容 C# BKDR Hash。

Python 3.10+，包名 `ezr-database-sdk`，导入名 `ezr_database_sdk`。

## 安装与开发

```bash
python -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m unittest discover -s tests -v
```

其他项目在自己的虚拟环境内安装本项目路径或已发布的 wheel：

```bash
python -m pip install /path/to/ezr-database-sdk
```

## 快速使用

复制 `database.example.yaml` 为私有的 `database.yaml`，设置选中环境的配置变量：

```python
from ezr_database_sdk import (
    EzrDatabaseSDK, physical_table_name_by_int, physical_table_name_by_hash,
)

with EzrDatabaseSDK.from_yaml("database.yaml", env="qcloud") as sdk:
    rules = sdk.get_table_shards(brand_id=6812, database="crm")
    nodes = sdk.get_connection_strings(brand_id=6812, database="crm")
    # 默认选择第一个主节点；多主节点也允许，不要打印返回的连接串。
    connection_string = sdk.get_connection_string(brand_id=6812, database="crm")
    # 计算已配置分表规则的表名：
    # table = sdk.get_physical_table_name_by_int(6812, "crm", "实际逻辑表名", 123)
    # hashed = sdk.get_physical_table_name_by_hash(6812, "crm", "实际逻辑表名", "123")

# 不连接数据库的纯计算接口：
assert physical_table_name_by_int("vip", 123, 16) == "vip12"
assert physical_table_name_by_hash("vip", "123", 16) == "vip3"
```

两种算法通过方法名显式选择，并严格检查参数类型，不自动转换；整数方法传入字符串、Hash 方法传入整数均会报错。旧的自动分派接口仅保留兼容并标记弃用，迁移说明见使用文档。

连接串含敏感凭据，禁止打印或写入日志。建议每个线程独立创建 SDK 实例，并使用上下文管理器关闭。

详细配置、返回字段、业务库代号、算法兼容及错误处理见 [使用文档](docs/database-sdk.md)。

## 发布

```bash
.venv/bin/python -m pip install -e '.[release]'
.venv/bin/python upload.py --dry-run     # 预演，不修改、不上传
.venv/bin/python upload.py --build-only  # 测试、构建、校验，不改版本、不上传
# 正式发布（先配置 Twine 凭据；会递增版本并实际上传）：
# .venv/bin/python upload.py
```

版本递增规则与 `kxy/framework` 一致，补丁号超过 19 时进位。仓库、凭据和故障恢复见 [发布文档](docs/releasing.md)。

本项目从 `testdata` 工具项目独立迁出，不依赖其脚本、私有配置或数据库凭据。
