安装

hwc-dws-cli 是一个 Python 命令行工具，通过 pip 安装后直接使用 hwc-dws-cli 命令。

环境要求

Python 3.10+（pyproject.toml 中 requires-python = ">=3.10"）
pip（随 Python 自带）
psycopg2（DWS 官方驱动，依赖自动安装）— 用于 SQL 执行与元数据查询
网络 — 可访问华为云 DWS 控制面 API（api / cluster / ops 命令需要）

安装

方式一：pip 直接安装（包已发布到 PyPI 后）

pip install hwc-dws-cli

方式二：源码目录安装脚本（推荐）。脚本自动检测 Python 解释器（默认 python，若为 2.x 则回退 python3）、从 pyproject.toml 读取版本号，并校验安装结果：

# Linux / macOS (bash)
./install.sh

# Windows (PowerShell)
.\install.ps1

如需安装可选依赖（odbc / parquet / agent）：

# Linux / macOS
./install.sh --extras

# Windows
.\install.ps1 -Extras

安装完成后按提示运行 hwc-dws-cli config set（命令行 8 步向导）或 hwc-dws-cli config set web（网页向导）完成配置。

如需 ODBC 驱动支持（可选，仅作参考场景使用）：

pip install hwc-dws-cli[odbc]

ODBC 说明

ODBC 驱动不用于生产 DWS 连接，仅作为参考回退。DWS SQL 执行统一使用 psycopg2（DWS 官方驱动）。

依赖

pyproject.toml 中声明的核心依赖：

依赖	版本	用途
`psycopg2-binary`	>=2.9	DWS SQL 连接与执行（官方驱动）
`click`	>=8.1	CLI 命令行框架
`pydantic`	==2.14.2	Envelope 响应模型
`cryptography`	>=42.0	配置加密（AES-256-GCM）
`PyYAML`	>=6.0	配置文件解析
`sqlglot`	>=30.7	SQL 分类解析（DWS 方言）
`requests`	>=2.31	API 网关调用
`structlog`	>=24.1	结构化日志
`tqdm`	>=4.66	进度条
`keyring`	>=24.0	系统凭据存储（可选）

可选依赖：[odbc] 提供 pyodbc；[parquet] 提供 pyarrow。

验证安装

hwc-dws-cli --version
# hwc-dws-cli, version 1.0.1

hwc-dws-cli --help
# Usage: hwc-dws-cli [OPTIONS] COMMAND [ARGS]...
# Commands:
#   api        DWS API passthrough commands (read-only).
#   audit      Audit log management commands (show/search/clean).
#   check-con  Check database connection.
#   cluster    Cluster management commands (read-only DWS OpenAPI queries).
#   config     Configuration management.
#   data       Data import/export management.
#   meta       Metadata commands for schemas, tables, and columns.
#   ops        Database operations and monitoring (read-only queries).
#   sql        Execute SQL statement.
#   tune       SQL tuning configuration management.

配置目录

首次运行前需配置连接。运行 hwc-dws-cli config set 启动 8 步交互式向导（AK/SK → proxy → region → cluster → endpoint → credentials → DB 连通性 → API 连通性）。配置文件位于 ~/.hwc-dws-cli/：

文件	说明
`config.yaml`	三层配置（global / regions / clusters）。AK 明文，SK / proxy / 连接密码加密。
`crypto.json`	主密钥冗余备份（机器指纹 + PBKDF2 + AES-256-GCM 元数据）。
`store.db`	JSON KV 状态存储（审计日志、token 缓存、传输会话、任务队列）。
`<effective_dir>/semantic.db`	语义元数据库（生效目录 = {base}/{cluster_marker}/{database}/）。
`regionlist.md`	区域中文名缓存（来自 IAM list-projects）。

下一步：快速开始 →