連線檔案格式
功能性的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 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 跳數。 |
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 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" }
]
}