sql-linker-cli

Important / 重要提示： All scripts/ paths are relative to this skill directory. Run CLI: cd {skill_dir}/scripts/service_layer && python main.py --help

---

sql-linker-cli vs sql-linker

中文

sql-linker-cli 是 sql-linker 的安全增强版，两者主要区别如下：

安全优势：

• dbpw_key 不再存储在本地，即使 OpenClaw agent 能读取配置文件，也无法获取数据库密码
• 凭证审批闸门（--approve）确保每次敏感操作都有显式授权记录
• 云端统一管理 API Key，支持 Key 轮换和撤销

迁移指南：

• 从 sql-linker 迁移到 sql-linker-cli，只需在 官网 创建 API Key 并填入 audit_config.json

English

sql-linker-cli is the security-enhanced version of sql-linker. Key differences:

Security advantages:

• dbpw_key is no longer stored locally; even if OpenClaw reads config files, it cannot obtain the database password
• Credential approval gate (--approve) ensures every sensitive operation has explicit authorization
• Cloud unified API Key management supports rotation and revocation

Migration guide:

• Migrating from sql-linker to sql-linker-cli: just create an API Key at portal and fill it into audit_config.json

---

API Key 获取官网

中文

官方门户：

这是获取和管理 API Key 的唯一官方地址。所有 cloud_api_key、dbpw_key、agent 绑定和审计日志查询都在此处。

获取步骤：

1. 打开 并登录
2. 进入 API Keys 管理页面
3. 点击 Create 创建新 key，填写 agent name（这个 name 会出现在审计日志的 username 字段里）
4. 创建后立即复制 API Key（格式：slk_xxxxxxxxxxxxxxx），关闭对话框就再也看不到完整值

拿到 API Key 后：把它填进 .sql_linker/config_home/audit_config.json 的 cloud_api_key 字段，然后运行 python main.py apikey status 验证。

English

Official Portal:

This is the only official portal to obtain and manage API Keys. All cloud_api_key, dbpw_key, agent binding, and audit log query live here.

Steps:

1. Open and log in
2. Go to API Keys management page
3. Click Create to create a new key, fill in agent name (this name will appear in audit log username field)
4. Copy immediately after creation (format: slk_xxxxxxxxxxxxxxx) — dialog closes and full value is unrecoverable

After getting the key: Fill it into cloud_api_key field in .sql_linker/config_home/audit_config.json, then run python main.py apikey status to verify.

---

Security & Privacy Notice

⚠️ Security Disclosures / 安全声明

This skill has the following security-relevant behaviors that operators should be aware of:

1. Cloud Audit Telemetry: INSERT/UPDATE/DELETE operations automatically transmit SQL metadata (masked), user context, and operation details to https://sqllinker.agentpower.hk.cn. This is not optional for write operations.

2. Credential Access: password_env reads from OS environment variables; dbpw_key is fetched from the cloud API when using cloud-managed credentials.

3. Bootstrap File Creation: bootstrap command creates config files in .sql_linker/ directory. set_env.ps1/sh generate encrypted credentials for OS environment variables (user-scope). User must manually add export line to shell config for persistence.

4. Arbitrary SQL: The query command accepts any SQL text (not limited to SELECT). Use parameterized queries to prevent injection.

中文

凭据安全

密码使用 dbpw_key（6 位密钥，HMAC-SHA256）加密后存入 OS 环境变量。dbpw_key 通过 API Key 从云端自动拉取，不要本地存储。

云端管理的数据库加密码

配置 cloud_api_key 后，dbpw_key 从 https://sqllinker.agentpower.hk.cn/api/user/api-keys/by-key 接口拉取（需要网络）。

云端审计

写操作（INSERT/UPDATE/DELETE）通过 API Key 自动同步到 https://sqllinker.agentpower.hk.cn/api/audit/logs。

凭证审批闸门

当 audit.require_explicit_credential_approval=true 时，每一次 静默凭证访问都必须显式授权：

• Python API: 在 db.connect() 前调用 db.explicit_credential_approval(approved=True)
• CLI: 每次调用传 --approve 参数

该 flag 仅本次调用有效——不进配置、不继承。每次敏感操作都会在 shell history 留痕。

English

Credential Security

Password is encrypted with dbpw_key (6-char key, HMAC-SHA256) before storing in OS environment variable. The dbpw_key is fetched automatically from cloud via your API Key — never store it locally.

Cloud-Managed dbpw_key

When cloud_api_key is configured, dbpw_key is fetched from https://sqllinker.agentpower.hk.cn/api/user/api-keys/by-key (requires network).

Cloud Audit

Write operations (INSERT/UPDATE/DELETE) are auto-synced to https://sqllinker.agentpower.hk.cn/api/audit/logs via API Key.

Credential Approval Gate

When audit.require_explicit_credential_approval=true, every silent-credential operation must be explicitly approved:

• Python API: call db.explicit_credential_approval(approved=True) before db.connect()
• CLI: pass --approve flag on each invocation

This flag is per-invocation only — it is NOT stored in config and NOT inherited. This leaves an audit trail in shell history for every sensitive operation.

---

SQL-Linker CLI

中文

跨数据库 CRUD + 云端审计。支持 MySQL、PostgreSQL、SQLite。所有写操作同步到 https://sqllinker.agentpower.hk.cn。

快速开始

1. 获取 API Key

见本文档顶部的 API Key 获取官网。

2. 初始化配置

cd scripts/service_layer
python main.py bootstrap

生成以下文件：

• .sql_linker/config_home/config.yaml — 数据库连接配置
• .sql_menu/config_home/audit_config.json — 审计 + 云端配置（URL 已预填）
• .sql_linker/config_home/extra_tables.json — 特权表
• .sql_linker/table_home/table_dictionary.json — 主字典
• .sql_linker/set_env.ps1 / set_env.sh — 密码设置脚本

初始化后编辑 .sql_linker/config_home/audit_config.json，把 slk_your_api_key_here 替换成真实 API Key。

3. 设置密码

Windows:

cd .sql_linker
.\set_env.ps1
# 输入密码（不回显）

Linux/macOS:

cd .sql_linker
bash set_env.sh

4. 验证

# 验证 API Key 有效性（无需连库）
python main.py apikey status

# 列出表（需要连库）
python main.py tables

# 查看连接配置
python main.py config

5. 使用 CLI

# 查询
python main.py query "SELECT * FROM users WHERE status = %s" --params '["active"]'

# 插入（闸门开启时需传 --approve）
python main.py insert users --data '{"name": "test", "email": "test@example.com"}' --approve

# 更新
python main.py update users --data '{"status": "active"}' --where "id = 1" --approve

# 删除
python main.py delete users --where "id = 1" --approve

# 从 JSON 文件（避免 shell 转义）
python main.py insert users --file data.json --approve

English

Cross-database CRUD with cloud audit. Supports MySQL, PostgreSQL, SQLite. All write operations sync to https://sqllinker.agentpower.hk.cn.

Quick Start

1. Get API Key

See API Key Official Portal at the top of this document.

2. Bootstrap Configuration

cd scripts/service_layer
python main.py bootstrap

Creates:

• .sql_linker/config_home/config.yaml — DB connection config
• .sql_linker/config_home/audit_config.json — Audit + cloud config (URL pre-filled)
• .sql_linker/config_home/extra_tables.json — Privileged tables
• .sql_linker/table_home/table_dictionary.json — Main dictionary
• .sql_linker/set_env.ps1 / set_env.sh — Password setup scripts

After bootstrap, edit .sql_linker/config_home/audit_config.json and replace slk_your_api_key_here with your real API key.

3. Set Password

Windows:

cd .sql_linker
.\set_env.ps1
# Enter password (no echo)

Linux/macOS:

cd .sql_linker
bash set_env.sh

4. Verify Setup

# Check API key is valid (no DB connection needed)
python main.py apikey status

# List tables (uses DB connection)
python main.py tables

# Inspect connection
python main.py config

5. Use CLI

# Query
python main.py query "SELECT * FROM users WHERE status = %s" --params '["active"]'

# Insert (audit-gated; pass --approve when gate enabled)
python main.py insert users --data '{"name": "test", "email": "test@example.com"}' --approve

# Update
python main.py update users --data '{"status": "active"}' --where "id = 1" --approve

# Delete
python main.py delete users --where "id = 1" --approve

# From JSON file (avoids shell escaping)
python main.py insert users --file data.json --approve

---

Commands

中文

apikey status - API Key 状态查询

从云端拉取当前 API Key 的元数据：

[API Key Status]
  status     : OK
  agent_name : 客服
  key_name   : test3
  key_id     : 5
  key_masked : slk_rs6p...GvBY
  dbpw_key   : 6 chars (value hidden)

• 不连数据库
• 不需要凭证审批（不走静默路径）
• 用于验证 key 有效性、排错审计归属、确认 dbpw_key 云端同步
• 退出码: 0=OK, 1=未配置, 2=云端不可达, 3=意外错误

--approve 参数

当 audit_config.json 中 require_explicit_credential_approval=true 时，每个会触库的 CLI 调用都需要显式授权：

# 不传 --approve：被闸门拦下
python main.py insert users --data '{...}'
# → [ERROR] Silent credential access requires explicit approval.

# 传 --approve：放行
python main.py insert users --data '{...}' --approve

重要约束：

• --approve 仅本次调用有效，不进配置、不进环境变量
• shell history 会留痕——这是审计痕迹
• 不要把 --approve 写进 shell alias，会破坏审计痕迹
• --approve 不会改变审计内容，只授权凭证访问

English

apikey status

Shows current API key metadata fetched from https://sqllinker.agentpower.hk.cn:

[API Key Status]
  status     : OK
  agent_name : 客服
  key_name   : test3
  key_id     : 5
  key_masked : slk_rs6p...GvBY
  dbpw_key   : 6 chars (value hidden)

• Does NOT connect to the database
• Does NOT require credential approval (no silent-credential path)
• Useful for verifying key validity, debugging audit attribution, checking dbpw_key cloud sync
• Exit codes: 0=OK, 1=not configured, 2=cloud unreachable, 3=unexpected error

--approve Flag

When audit.require_explicit_credential_approval=true in audit_config.json, every CLI invocation that touches the database needs explicit approval:

# Without --approve — blocked at credential gate
python main.py insert users --data '{...}'
# → [ERROR] Silent credential access requires explicit approval.

# With --approve — proceeds
python main.py insert users --data '{...}' --approve

Important constraints:

• --approve is per-invocation only. Not stored in config. Not inherited from environment.
• This leaves a trace in shell history for every sensitive operation.
• Do NOT alias python main.py to include --approve — that defeats the audit trail.
• --approve does NOT change what gets audited; it only authorizes the credential access that triggers the audit.

---

Four-Layer Access Model

中文

English

---

Configuration

中文

config_home/config.yaml

type: mysql                      # 数据库类型: mysql/postgres/sqlite
host: 127.0.0.1                  # 主机地址
port: 3306                       # 端口号
database: db_dev                 # 数据库名
user: admin                      # 用户名
password_env: mysql_pw           # OS 环境变量键（存储加密密码）
read_only: false                 # 只读模式（默认安全）
max_rows: 1000                   # 最大返回行数
timeout: 30                       # 连接超时（秒）
extra_tables_enabled: false      # 特权表开关（默认关闭）

config_home/audit_config.json

{
  "username": "CLI",                                    // 用户标识名
  "cloud_audit_url": "https://sqllinker.agentpower.hk.cn/api/audit/logs",  // 云端审计地址
  "cloud_api_key": "slk_xxxxxxxxxxxxxxx",               // API 密钥
  "audit": {
    "enabled": true,                                    // 审计开关
    "log_table": "sql_audit_log",                       // 审计日志表名
    "log_select": false,                                // SELECT 是否记录
    "mask_values": true,                                 // 敏感值脱敏
    "collect_lan_ip": false,                            // 收集局域网IP
    "require_explicit_credential_approval": false        // 凭证审批闸门
  }
}

新装默认 cloud_audit_url 为新域名，老用户配置继续工作。

table_home/table_dictionary.json

表和字段白名单，只能写入声明过的字段。bootstrap 模板见 scripts/service_layer/main.py。

English

config_home/config.yaml

type: mysql                      # Database type: mysql/postgres/sqlite
host: 127.0.0.1                  # Host address
port: 3306                       # Port number
database: db_dev                 # Database name
user: admin                      # Username
password_env: mysql_pw           # OS env key (stores encrypted password)
read_only: false                 # Read-only mode (safe by default)
max_rows: 1000                   # Maximum rows returned
timeout: 30                       # Connection timeout (seconds)
extra_tables_enabled: false      # Privileged table gate (off by default)

config_home/audit_config.json

{
  "username": "CLI",                                    // User identifier
  "cloud_audit_url": "https://sqllinker.agentpower.hk.cn/api/audit/logs",  // Cloud audit endpoint
  "cloud_api_key": "slk_xxxxxxxxxxxxxxx",               // API Key
  "audit": {
    "enabled": true,                                    // Audit enabled
    "log_table": "sql_audit_log",                       // Audit log table name
    "log_select": false,                                // Log SELECT queries
    "mask_values": true,                                // Mask sensitive values
    "collect_lan_ip": false,                            // Collect LAN IP
    "require_explicit_credential_approval": false        // Require credential approval gate
  }
}

New installs default to new domain URL. Existing installs continue to work.

table_home/table_dictionary.json

Whitelist of tables and fields. Only declared fields can be written. Bootstrap template in scripts/service_layer/main.py.

---

Python API

中文

import sys
sys.path.insert(0, "scripts/service_layer")
from db_bridge import DBBridge

# 方式一：构造时直接传授权
db = DBBridge(user_label="myagent", session_id="main", approved=True)
db.require_cloud_api_key()
db.connect()
rows = db.query("SELECT * FROM users WHERE status = %s", ("active",))

# 方式二：显式调用授权（推荐）
db = DBBridge(user_label="myagent", session_id="main")
db.require_cloud_api_key()
db.explicit_credential_approval(approved=True)  # 闸门开启时必须
db.connect()

# 云端 introspection（无需连库，直接使用 SQLLinker）
import sys
sys.path.insert(0, "scripts/controller_layer")
from sql_linker import SQLLinker
linker = SQLLinker()
info = linker.fetch_api_key_info()  # 返回非敏感元数据: agent_name, key_name, id, key_masked
print(info["agent_name"], info["key_name"])

English

import sys
sys.path.insert(0, "scripts/service_layer")
from db_bridge import DBBridge

# Option 1: Pass approval in constructor
db = DBBridge(user_label="myagent", session_id="main", approved=True)
db.require_cloud_api_key()
db.connect()
rows = db.query("SELECT * FROM users WHERE status = %s", ("active",))

# Option 2: Call explicit approval (recommended)
db = DBBridge(user_label="myagent", session_id="main")
db.require_cloud_api_key()
db.explicit_credential_approval(approved=True)  # Required when gate is enabled
db.connect()

# Cloud introspection (no DB needed, use SQLLinker directly)
import sys
sys.path.insert(0, "scripts/controller_layer")
from sql_linker import SQLLinker
linker = SQLLinker()
info = linker.fetch_api_key_info()  # Returns non-sensitive metadata: agent_name, key_name, id, key_masked
print(info["agent_name"], info["key_name"])

---

Common Errors

中文

English

---

Directory Structure

中文

sql-linker-cli/                        # 技能根目录
├── SKILL.md                           # 本文档
├── _meta.json                         # 元数据（版本、发布信息）
├── scripts/
│   ├── controller_layer/              # 数据操作层
│   │   ├── sql_linker.py             # 连接 + CRUD + 云端审计 + 密钥获取
│   │   └── sql_audit.py              # 审计模块
│   └── service_layer/                # 业务层
│       ├── db_bridge.py              # 访问控制 + 时间戳
│       └── main.py                   # CLI 入口点

workspace/
└── .sql_linker/                      # 配置根目录（bootstrap 创建）
    ├── config_home/
    │   ├── config.yaml                # 数据库连接配置
    │   ├── audit_config.json          # 审计 + 云端配置
    │   └── extra_tables.json          # 特权表
    ├── table_home/
    │   └── table_dictionary.json     # 主字典
    ├── set_env.ps1                   # 密码设置脚本（Windows）
    └── set_env.sh                    # 密码设置脚本（Linux/macOS）

English

sql-linker-cli/                        # Skill root directory
├── SKILL.md                           # This document
├── _meta.json                         # Metadata (version, publish info)
├── scripts/
│   ├── controller_layer/              # Data operation layer
│   │   ├── sql_linker.py             # Connection + CRUD + cloud audit + key fetch
│   │   └── sql_audit.py             # Audit module
│   └── service_layer/                # Business layer
│       ├── db_bridge.py              # Access control + timestamp
│       └── main.py                   # CLI entry point

workspace/
└── .sql_linker/                      # Config root (created by bootstrap)
    ├── config_home/
    │   ├── config.yaml               # DB connection config
    │   ├── audit_config.json         # Audit + cloud config
    │   └── extra_tables.json         # Privileged tables
    ├── table_home/
    │   └── table_dictionary.json    # Main dictionary
    ├── set_env.ps1                  # Password setup (Windows)
    └── set_env.sh                   # Password setup (Linux/macOS)