连接文件格式

功能的

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).
environmentlocal, dev, test, staging, production,或 unset.
client, project标签名称。
authentication如何登录 - 见下文。
tlsmode (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).
safetyauto_wrap_rollback, block_all_but_select, confirm_data_changes, allow_unbounded_mutations,以及 production_override 针对这个连接。
favorite将连接加星标。
startup_sql连接后立即执行的 SQL。
redis_key_delimiter, clickhouse_native_portRedis 和 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 跳。
maskinginclude 和 exclude 列模式列表,例如 "*ssn*",或 { "pattern": "users.email", "scope": "table-dot-column" }.

登录方法

type字段
sql-loginusername 和 password,或 account 命名一个共享登录名。密码留空,SQLly 会在首次连接时询问。
integratedWindows / Kerberos(SQL Server)。
entra-browser, entra-device-codeMicrosoft Entra(SQL Server、Azure SQL)。
aws-rds-iamusername, region,可选 profile.
gcp-cloud-sql-iamusername.
auth-tokenlibSQL / Turso token (对于匿名服务器请省略)。
noneSQLite 和 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" }
  ]
}