Metadata-Version: 2.4
Name: oceanbase-data-etl-tool
Version: 1.0.0
Summary: A tool for importing and exporting OceanBase database tables to/from Excel and CSV formats, with a Streamlit web UI.
Author: OceanBase ETL Team
License: MIT
Project-URL: Homepage, https://github.com/oceanbase/oceanbase-data-etl-tool
Project-URL: Documentation, https://github.com/oceanbase/oceanbase-data-etl-tool#readme
Keywords: oceanbase,etl,excel,csv,streamlit,database
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Office/Business
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pymysql>=1.0.2
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: streamlit>=1.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"

# OceanBase Data ETL Tool

一款用于 OceanBase 数据库表数据导入/导出 Excel 和 CSV 格式的工具，提供 CLI 命令行界面和 Streamlit 可视化操作页面。

## 功能特性

- **数据导出**: 将 OceanBase 表数据导出为 CSV 或 Excel (.xlsx) 格式
- **数据导入**: 将 CSV 或 Excel 文件导入到 OceanBase 表中
- **批量操作**: 支持单表和多表批量导入导出
- **重复列名处理**: 自动检测并去重 CSV/Excel 中的重复列名（追加 `_1`, `_2` 后缀）
- **中文字段支持**: 创建新表时自动识别中文字段名，保留原始中文列名
- **列名清洗**: 自动清理特殊字符，确保 SQL 兼容性
- **忽略首行表头**: 可选择是否跳过文件第一行（表头行）
- **Web UI**: 基于 Streamlit 的可视化操作界面
- **CLI 命令行**: 支持自动化脚本集成
- **OceanBase 兼容**: 完美兼容 OceanBase CE v4.5.0 (MySQL 5.7 协议)
- **多架构支持**: 纯 Python 实现，支持 x86_64 和 aarch64 架构

## 安装

### 方式一: 使用 pip 安装 wheel 包

```bash
pip install oceanbase_data_etl_tool-1.0.0-py3-none-any.whl
```

### 方式二: 从源码安装

```bash
cd oceanbase-data-etl-tool
pip install -e .
```

### 方式三: 内网部署 (离线)

```bash
# 在有网络的机器上下载依赖
pip download -d ./wheels -r requirements.txt

# 在内网 aarch64 服务器上安装
pip install --no-index --find-links=./wheels oceanbase_data_etl_tool-1.0.0-py3-none-any.whl
```

## 快速开始

### CLI 命令行

```bash
# 测试数据库连接
oceanbase-etl test --host 127.0.0.1 --port 2881 --user root --password your_password --database test_db

# 列出表
oceanbase-etl list --host 127.0.0.1 --port 2881 --user root --password your_password --database test_db

# 查看表结构
oceanbase-etl describe --host 127.0.0.1 --port 2881 --user root --password your_password --database test_db --table users

# 导出单表到 CSV
oceanbase-etl export --host 127.0.0.1 --port 2881 --user root --password your_password \
    --database test_db --table users --output ./users.csv

# 导出所有表到 Excel (多 sheet)
oceanbase-etl export --host 127.0.0.1 --port 2881 --user root --password your_password \
    --database test_db --all-tables --output ./all_data.xlsx

# 带条件导出
oceanbase-etl export --host 127.0.0.1 --port 2881 --user root --password your_password \
    --database test_db --table orders --output ./active_orders.csv \
    --where "status = 'active'" --order-by "created_at DESC" --limit 1000

# 导入 CSV 到现有表
oceanbase-etl import --host 127.0.0.1 --port 2881 --user root --password your_password \
    --database test_db --table users --file ./users.csv --truncate

# 从 CSV 自动创建表并导入
oceanbase-etl import --host 127.0.0.1 --port 2881 --user root --password your_password \
    --database test_db --table new_users --file ./data.csv --create-table

# 启动 Web UI
oceanbase-etl ui --server-port 8501 --server-address 0.0.0.0 --headless
```

### Streamlit Web UI

```bash
oceanbase-etl ui --server-port 8501 --server-address 0.0.0.0
```

启动后访问 `http://<server-ip>:8501` 即可使用可视化界面。

## 项目结构

```
oceanbase-data-etl-tool/
├── src/
│   └── oceanbase_etl/
│       ├── __init__.py
│       ├── config.py           # 配置管理
│       ├── database.py         # 数据库连接和操作
│       ├── exporter/
│       │   ├── __init__.py
│       │   ├── csv_exporter.py  # CSV 导出
│       │   └── excel_exporter.py # Excel 导出
│       ├── importer/
│       │   ├── __init__.py
│       │   ├── csv_importer.py  # CSV 导入
│       │   └── excel_importer.py # Excel 导入
│       ├── cli/
│       │   ├── __init__.py
│       │   └── main.py          # CLI 入口
│       └── ui/
│           ├── __init__.py
│           └── app.py           # Streamlit UI
├── tests/
├── pyproject.toml
├── requirements.txt
├── README.md
└── setup.sh                     # 打包脚本
```

## 构建 Wheel 包

```bash
# 安装构建工具
pip install build wheel setuptools

# 构建 wheel 包
python -m build --wheel

# 产物在 dist/ 目录下
ls dist/
# oceanbase_data_etl_tool-1.0.0-py3-none-any.whl
```

## aarch64 部署

由于本项目是纯 Python 实现（依赖 pymysql、openpyxl、streamlit 均为纯 Python 或有 aarch64 wheel），可直接部署：

```bash
# 方案一：直接安装 wheel（纯 Python 包，架构无关）
pip install oceanbase_data_etl_tool-1.0.0-py3-none-any.whl

# 方案二：离线安装（适用于无网络环境）
# 1. 在有网络的同架构机器上下载依赖
pip download -d ./wheels oceanbase-data-etl-tool==1.0.0
pip download -d ./wheels pymysql openpyxl streamlit

# 2. 拷贝 wheels 目录到内网服务器
# 3. 在内网服务器上安装
pip install --no-index --find-links=./wheels oceanbase-data-etl-tool
```

## 技术细节

| 项目 | 值 |
|------|-----|
| Python 版本 | >= 3.9 |
| OceanBase 版本 | 5.7.25-OceanBase_CE-v4.5.0.0 |
| 数据库驱动 | PyMySQL (MySQL 5.7 兼容协议) |
| Excel 处理 | openpyxl |
| Web 框架 | Streamlit |
| 架构支持 | x86_64, aarch64 (纯 Python) |

## License

MIT
