連線檔案格式

功能性的

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 master 群組與 Sentinel 清單,以及 Sentinel 自己的明文密碼(匯入時移進鑰匙圈,匯出時一律不包含)。
redis_cluster僅限 Redis:叢集模式(auto, standalone, cluster)和節點圖。
redis_entra_user搭配 Microsoft Entra 登入的 Redis:用來登入的 Redis 使用者名稱;留空則以權杖的物件識別碼登入。
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 keepalive。
  • 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" }
  ]
}