navop/docs-site/docs/guide/database-connections.md

数据库连接

Navop 内置支持 MySQL、PostgreSQL、SQLite、DuckDB、SQL Server、Oracle、ClickHouse；TDengine 改为通过扩展市场安装的驱动提供（官方 taos WebSocket 驱动，经 taosAdapter :6041 连接，纯 Rust 无需本地 C 依赖），并可通过扩展增加达梦、金仓、GBase 8s、OceanBase、openGauss、IoTDB 等数据库。历史内置 TDengine 连接在打开时会提示安装对应驱动扩展。具体字段和能力取决于驱动与服务器版本。

内置 Oracle 驱动依赖 Oracle Instant Client；若不希望安装 Instant Client，可从扩展市场安装纯 Go Oracle 驱动。连接 Oracle 时可按需选择 Native 或 Go 驱动。

本页先介绍所有数据库都通用的连接流程；驱动特有的参数、SQL 方言和对象能力以实际连接表单和驱动版本为准。

创建网络数据库连接

选择数据库类型，填写连接名称、主机、端口、用户名、密码和默认数据库。先用“测试连接”验证网络、认证和驱动，再保存并打开。连接失败时按错误层级排查 DNS、端口、防火墙、账号权限、数据库状态和版本兼容性，不要反复修改多个字段导致原因难以定位。

部分数据库允许选择默认 Schema、字符集或额外参数。生产环境建议使用权限最小化账号：日常查询账号不要同时拥有 DROP、TRUNCATE 或全局管理权限。保存密码前确认设备已设置主密钥。

本地数据库文件

SQLite 和 DuckDB 可以直接选择本地文件，也可以通过系统文件关联打开 .db 或 .duckdb。打开前确认文件路径、读写权限和锁状态；若文件来自生产系统或其他程序仍在写入，先复制到安全位置进行分析。

相对路径、网络磁盘和云盘同步目录可能导致锁或一致性问题。重要修改前制作文件级备份，并避免让多个工具同时写同一个数据库文件。删除 Navop 连接不会等同于删除数据库文件，但任何 SQL 写入仍会修改文件内容。

代理与 SSH 隧道

无法直连时，可以配置 SOCKS5 或 HTTP CONNECT 代理，并按需填写代理认证。代理只改变网络路径，不会替代数据库 TLS 和账号权限。测试失败时分别确认代理地址、代理凭据、目标端口和代理侧访问规则。

SSH 隧道可以引用已保存的 SSH/SFTP 连接，也可以手动填写跳板机。认证支持密码、私钥文件、私钥内容和 SSH Agent；需要时配置实际隧道目标，而不是默认假设数据库就在 SSH 主机本机。先测试 SSH，再测试数据库，有助于区分隧道与数据库错误。

SSH 跳板机配置在禁用后仍会保留，便于快速重新启用，不必重新填写认证信息。

SSL/TLS 与证书

服务器要求加密时启用 SSL/TLS，并按驱动提供 CA、客户端证书、客户端私钥或验证模式。严格验证能防止连接到伪造服务器，生产环境不应为方便而长期关闭证书验证。主机名必须与证书匹配，系统时间错误也可能导致证书被判定无效。

证书文件和私钥属于敏感材料，不要放入公开仓库或 Notes 同步目录。更新证书后重新测试连接，并确认扩展数据库驱动是否支持所需的 TLS 参数。

Schema 过滤与连接高级设置

Schema 过滤可自动隐藏系统对象、仅包含指定 Schema、排除指定 Schema，或显示全部。过滤只影响导航树的可见范围，不会改变账号权限，也不会阻止 SQL 直接访问被隐藏对象。排查“对象不存在”时同时检查当前数据库、当前 Schema、名称大小写和过滤规则。

连接建立后，先浏览数据库与 Schema，再打开只读查询确认默认上下文。需要修改连接时先关闭依赖它的 SQL 编辑器、表数据页和比较任务，避免活动会话仍使用旧参数。

通用字段说明

字段	常见值	什么时候需要特别确认
连接名称	测试 · PostgreSQL	名称只用于识别，不会改变远端资源
主机	域名、IP、127.0.0.1	使用 SSH 隧道时通常填写本地监听地址
端口	MySQL 3306、PostgreSQL 5432、Redis 6379	端口由服务实际监听值决定，不要只按数据库类型猜测
用户名/密码	数据库账号	建议使用最小权限账号，密码由主密钥保护
数据库	默认数据库或文件路径	PostgreSQL 的数据库和 Schema 不是同一概念
Schema	public 或自定义 Schema	过滤只影响导航树，不等同于权限限制
TLS	关闭、验证 CA、客户端证书	生产环境不要长期关闭证书验证

三种常见连接示例

网络数据库

1. 选择数据库类型并填写真实主机、端口和账号。
2. 先不启用代理和 SSH 隧道，测试基础网络是否可达。
3. 测试成功后再配置 Schema、TLS 或连接高级参数。
4. 打开连接，确认默认数据库和 Schema 正确。

本地 SQLite/DuckDB 文件

1. 选择本地文件，或通过系统打开 .db、.duckdb。
2. 如果文件仍被其他程序写入，先复制到测试目录。
3. 打开后先浏览表结构，再执行只读查询。
4. 修改前保存文件副本；删除 Navop 连接不会删除文件，但 SQL 写入会改变文件内容。

SSH 隧道后的数据库

1. 先单独测试 SSH 连接和主机指纹。
2. 配置本地监听端口，例如 127.0.0.1:13306。
3. 数据库连接的主机填写 127.0.0.1，端口填写本地监听端口。
4. 数据库目标填写 SSH 主机能够访问的真实地址和端口。
5. 先测试 SSH 隧道，再测试数据库，失败时不要同时修改两组参数。

连接成功的判断标准

连接测试成功只是网络和认证通过。真正打开后还应确认：

• 数据库名称符合当前环境。
• Schema 树可以展开，且没有被过滤规则意外隐藏。
• 能看到预期表、视图或集合。
• 执行一条只读查询能返回结果。
• TLS、代理和 SSH 隧道状态与连接要求一致。

高风险操作前的最小检查

执行写入 SQL、导入覆盖、Schema 同步或删除对象前，至少确认连接卡片名称、数据库、Schema、账号权限和事务模式。把连接复制到另一个环境后，必须重新修改名称和目标，不能只依赖颜色区分。