连接文件格式
功能的SQLly 连接文件的布局——标签、共享登录、隧道配置与连接——包括它接受的每一个键和一个完整示例。
SQLly 连接文件是一个 JSON 文档。它既是 文件 → 导出连接… 和 文件 → 导出连接及凭据… 写入的内容,也是 文件 → 导入连接… 读取(见 导出与导入连接)。你也可以手写一个。本页概述这个文件的布局方式,以及每个部分接受哪些内容。
password, passphrase,以及 token 字段都可以省略:导出连接不会写入其中任何一个,没有该字段的连接会在首次连接时向你索要。包含这些字段的文件本身就是一份机密。SQLly 会在导入时把每个密码移入系统钥匙串,绝不保留文件副本——导入完成后请把这个文件删掉。布局一览
{
"format": "sqlly-credentials", // required, always this value (with or without passwords)
"version": 1, // required
"clients": [ … ], // labels with color, icon, protections
"projects": [ … ],
"environments": [ … ],
"sql_auth_accounts": [ … ], // shared logins: name, username, optional password
"tunnel_profiles": [ … ], // named SSH / proxy / Kubernetes chains
"connections": [ … ] // any number of servers and databases
}
每个部分都是可选的,除了 format 和 version。连接指向共享登录、隧道配置文件和标签 按名称,这样一个登录或隧道就能供多个连接共用。名称匹配不区分大小写,名称也可以指向 SQLly 中已保存的条目。
一台服务器上的多个数据库,其实就是几条共享同一个
server 并在 database上有所不同的连接而已。同一个数据库上的多个登录,是使用不同账户的多条连接。
任何更改生效前先检查
- 全有或全无 - 会先检查整个文件。如果有问题,所有问题都会连同其位置一起列出(例如
connections[2] "Ops": port must be 1-65535),并且不会导入任何内容。 - 拼写错误视为错误 - 未知键,例如
"pasword"会被报告出来,而不是被悄悄忽略。 - 适用引擎规则 - 引擎不支持的登录方式、要求 TLS 却未启用加密的托管引擎、缺少私钥的客户端证书,全都会被报告出来。
- 较新版本会被拒绝 - 一个带有
version比你的 SQLly 能识别的版本更新时会明确提示,而不是只导入一半。
客户、项目和环境
| 键 | 包含内容 |
|---|---|
name | 必需。与同名的现有标签合并,或创建一个新标签。 |
color | #RGB, #RRGGBB,或 #RRGGBBAA ( # 是可选的)。 |
image | 图标,以 Base64 编码——一个 data:image/png;base64,… URI 或纯 base64。PNG、JPEG、GIF、WebP、BMP、ICO 或 SVG,最大 1 MB。类型由图像本身检测。 |
safety | 以下任意一个 is_production, only_allow_select, use_confirmation_dialog, use_outer_transaction_rollback_scope, require_ai_review_for_data_changes, allow_unconstrained_update, allow_unconstrained_delete, require_touch_id_to_connect, require_touch_id_for_non_select (每个 true / false)。只有你列出的开关会改变。 |
省略 color, image,或安全开关会保留现有标签已有的内容。
共享登录
{ "name": "Reader", "username": "ro", "password": "…" }
连接使用的一个映射带有如下内容: "authentication": { "type": "sql-login", "account": "Reader" }。导入时若与已保存登录同名且用户名相同,则会就地更新其密码。
隧道配置文件
{ "name": "Corp bastion", "ssh": { … }, "proxy": { … }, "kube": { … } }
各跳使用与连接的 transport (见下文)。一个连接会使用如下形式的 "tunnel_profile": "Corp bastion",而不是内联的
transport.
连接
只有 name, engine,以及 server 是必需的。任何被忽略的部分都会得到连接编辑器给予的默认值。
| 键 | 包含内容 |
|---|---|
name | 在资源管理器中显示的名称。 |
engine | 可以简写: postgresql, postgres, mssql, sql-server, mysql, mariadb, sqlite, duckdb, libsql, clickhouse, oracle, redis, valkey, neon, supabase, planetscale, cockroachdb,以及 SQLly 支持的其他引擎。 |
server | 主机名,IP, host\instance,或 SQLite 和 DuckDB 的文件路径。 |
port | 默认使用引擎的常用端口。 |
database | 要打开的数据库(Oracle:服务名称,或 SID:ORCL). |
environment | local, dev, test, staging, production,或 unset. |
client, project | 标签名称。 |
authentication | 如何登录 - 见下文。 |
tls | mode (disable, require, verify-ca, verify-full),或 SQL Server 风格的 encrypt 和 trust_server_certificate 开关。同时 ca_file, client_cert_file,以及 client_key_file 路径,和 trust_os_roots (true 也信任操作系统的证书存储;Redis), 并且 direct (true 用于 PostgreSQL 17 的直接 TLS)。 |
timeout_seconds, statement_timeout_seconds | 连接超时(默认 30)以及可选的每条语句限制。 |
application_name | 向服务器报告(默认 SQLLY). |
safety | auto_wrap_rollback, block_all_but_select, confirm_data_changes, allow_unbounded_mutations,以及 production_override 针对这个连接。 |
favorite | 将连接加星标。 |
startup_sql | 连接后立即执行的 SQL。 |
redis_key_delimiter, clickhouse_native_port | Redis 和 ClickHouse 的引擎专属附加功能。 |
redis_sentinel, redis_sentinel_password | 仅限 Redis:待询问的 Sentinel 主机组和哨兵列表,以及哨兵本身的明文密码(导入时移入钥匙串,从不导出)。 |
redis_cluster | 仅限 Redis:集群模式(auto, standalone, cluster)和节点映射。 |
redis_entra_user | 通过 Microsoft Entra 登录的 Redis:要以其身份登录的 Redis 用户名;留空则以令牌的对象 ID 登录。 |
entra_account | 固定一个 Microsoft Entra 账户: account_id, tenant_id, username. |
route | { "type": "direct" } (默认)或 { "type": "via-relay", "relay_device_id", "pair_id" }. |
tunnel_profile 或者 transport | 一个命名的隧道配置文件,或内联 proxy, ssh,以及 kube 跳。 |
masking | include 和 exclude 列模式列表,例如 "*ssn*",或 { "pattern": "users.email", "scope": "table-dot-column" }. |
登录方法
type | 字段 |
|---|---|
sql-login | username 和 password,或 account 命名一个共享登录名。密码留空,SQLly 会在首次连接时询问。 |
integrated | Windows / Kerberos(SQL Server)。 |
entra-browser, entra-device-code | Microsoft Entra(SQL Server、Azure SQL)。 |
aws-rds-iam | username, region,可选 profile. |
gcp-cloud-sql-iam | username. |
auth-token | libSQL / Turso token (对于匿名服务器请省略)。 |
none | SQLite 和 DuckDB 文件。 |
隧道跳数
ssh-host,port(22),username,以及auth:{ "type": "agent" },{ "type": "key-file", "path", "passphrase" },或{ "type": "password", "password" }(passphrase和password可以省略;SQLly 会在首次连接时询问)。一个可选的jump主机使用相同的字段。keepalive_seconds(默认 30,0 表示无) 和keepalive_max(3) 用来设置隧道的 SSH 保活。proxy-kind(socks5或者http-connect),host,port,以及可选的username和password.kube-namespace,target_kind(pod,service,deployment),target_name,remote_port,以及可选的kubeconfig和context。它不能与 SSH 或代理一起使用。
完整示例
一台 PostgreSQL 服务器上的两个数据库,经堡垒机访问,共用读写登录名;一台使用自己密码的 SQL Server;以及一个本地 SQLite 文件,配一个带颜色标记的客户和一个只允许 SELECT 的生产环境。
{
"format": "sqlly-credentials",
"version": 1,
"clients": [
{ "name": "Acme", "color": "#1E88E5", "image": "data:image/png;base64,iVBORw0KGgo…" }
],
"environments": [
{ "name": "Production", "color": "#C62828", "safety": { "only_allow_select": true } }
],
"sql_auth_accounts": [
{ "name": "Reader", "username": "ro", "password": "ro-secret" },
{ "name": "Writer", "username": "rw", "password": "rw-secret" }
],
"tunnel_profiles": [
{ "name": "Corp bastion",
"ssh": { "host": "bastion.acme.com", "username": "deploy",
"auth": { "type": "key-file", "path": "~/.ssh/id_ed25519" } } }
],
"connections": [
{ "name": "Sales (read)", "engine": "postgresql", "server": "pg1.acme.internal", "database": "sales",
"client": "Acme", "environment": "production", "tunnel_profile": "Corp bastion",
"authentication": { "type": "sql-login", "account": "Reader" },
"tls": { "mode": "verify-full" } },
{ "name": "Sales (write)", "engine": "postgresql", "server": "pg1.acme.internal", "database": "sales",
"client": "Acme", "environment": "production", "tunnel_profile": "Corp bastion",
"authentication": { "type": "sql-login", "account": "Writer" },
"safety": { "confirm_data_changes": true } },
{ "name": "HR", "engine": "postgresql", "server": "pg1.acme.internal", "database": "hr",
"client": "Acme", "tunnel_profile": "Corp bastion",
"authentication": { "type": "sql-login", "account": "Reader" } },
{ "name": "Ops", "engine": "sql-server", "server": "sql01.acme.internal", "database": "ops",
"authentication": { "type": "sql-login", "username": "ops", "password": "ops-secret" },
"tls": { "encrypt": true, "trust_server_certificate": true }, "favorite": true },
{ "name": "Scratch", "engine": "sqlite", "server": "~/data/scratch.db" }
]
}