Connection file format
functionalHow a SQLly connection file is laid out - labels, shared logins, tunnel profiles, and connections - with every key it accepts and a complete example.
A SQLly connection file is a single JSON document. It is what both File → Export Connections… and File → Export Conn w/ Creds… write and what File → Import Connections… reads (see Export & import connections). You can also write one by hand. This page is an overview of how the file is laid out and what each part accepts.
password, passphrase, and token field can be left out: Export Connections writes none of them, and a connection without one asks for it on first connect. A file that has them is a secret in its own right. SQLly moves every password into your system keychain on import and never keeps a copy of the file, delete it once it has been imported.Layout at a glance
{
"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
}
Every section is optional except format and version. Connections
point to shared logins, tunnel profiles, and labels by name, so one login
or tunnel can serve many connections. Names are matched without regard to case, and a
name can also point to something already saved in SQLly.
One server with several databases is simply several connections that share a
server and differ in database. Several logins on the same
database are several connections that use different accounts.
Checked before anything changes
- All or nothing - the whole file is checked first. If anything is wrong, every problem is listed with its location (for example
connections[2] "Ops": port must be 1-65535) and nothing is imported. - Typos are errors - an unknown key such as
"pasword"is reported rather than quietly ignored. - Engine rules apply - a sign-in method the engine doesn't support, a hosted engine that requires TLS with encryption turned off, or a client certificate without its key are all reported.
- Newer versions are refused - a file with a
versionnewer than your SQLly understands says so instead of half-importing.
Clients, projects & environments
| Key | What it holds |
|---|---|
name | Required. Merges with an existing label of the same name, or creates one. |
color | #RGB, #RRGGBB, or #RRGGBBAA (the # is optional). |
image | The icon, base64 encoded - a data:image/png;base64,… URI or bare base64. PNG, JPEG, GIF, WebP, BMP, ICO, or SVG, up to 1 MB. The type is detected from the image itself. |
safety | Any of 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 (each true / false). Only the switches you list change. |
Leaving out color, image, or a safety switch keeps whatever the existing label already has.
Shared logins
{ "name": "Reader", "username": "ro", "password": "…" }
A connection uses one with "authentication": { "type": "sql-login", "account": "Reader" }.
Importing over a saved login with the same name and user name updates its password in place.
Tunnel profiles
{ "name": "Corp bastion", "ssh": { … }, "proxy": { … }, "kube": { … } }
The hops use the same shapes as a connection's transport (below). A connection
uses one with "tunnel_profile": "Corp bastion", instead of an inline
transport.
Connections
Only name, engine, and server are required. Anything left out gets the same default the connection editor would give it.
| Key | What it holds |
|---|---|
name | The name shown in the explorer. |
engine | Written loosely: postgresql, postgres, mssql, sql-server, mysql, mariadb, sqlite, duckdb, libsql, clickhouse, oracle, redis, valkey, neon, supabase, planetscale, cockroachdb, and the rest of the engines SQLly supports. |
server | Host name, IP, host\instance, or the file path for SQLite and DuckDB. |
port | Defaults to the engine's usual port. |
database | Database to open (Oracle: service name, or SID:ORCL). |
environment | local, dev, test, staging, production, or unset. |
client, project | Label names. |
authentication | How to sign in - see below. |
tls | mode (disable, require, verify-ca, verify-full), or the SQL Server style encrypt and trust_server_certificate switches. Also ca_file, client_cert_file, and client_key_file paths, and trust_os_roots (true to also trust the operating system's certificate store; Redis), and direct (true for PostgreSQL 17 direct TLS). |
timeout_seconds, statement_timeout_seconds | Connect timeout (default 30) and an optional per-statement limit. |
application_name | Reported to the server (default SQLLY). |
safety | auto_wrap_rollback, block_all_but_select, confirm_data_changes, allow_unbounded_mutations, and production_override for this one connection. |
favorite | Star the connection. |
startup_sql | SQL to run right after connecting. |
redis_key_delimiter, clickhouse_native_port | Engine-specific extras for Redis and ClickHouse. |
redis_sentinel, redis_sentinel_password | Redis only: the Sentinel master group and sentinels to ask, and the sentinels' own password in clear text (moved to the keychain on import, never exported). |
redis_cluster | Redis only: cluster mode (auto, standalone, cluster) and the node map. |
redis_entra_user | Redis with Microsoft Entra sign-in: the Redis user name to sign in as; absent signs in as the token's object id. |
entra_account | Pin a Microsoft Entra account: account_id, tenant_id, username. |
route | { "type": "direct" } (default) or { "type": "via-relay", "relay_device_id", "pair_id" }. |
tunnel_profile or transport | A named tunnel profile, or inline proxy, ssh, and kube hops. |
masking | include and exclude lists of column patterns such as "*ssn*", or { "pattern": "users.email", "scope": "table-dot-column" }. |
Sign-in methods
type | Fields |
|---|---|
sql-login | username and password, or account naming a shared login. Leave out the password and SQLly asks for it on first connect. |
integrated | Windows / Kerberos (SQL Server). |
entra-browser, entra-device-code | Microsoft Entra (SQL Server, Azure SQL). |
aws-rds-iam | username, region, optional profile. |
gcp-cloud-sql-iam | username. |
auth-token | libSQL / Turso token (leave it out for an anonymous server). |
none | SQLite and DuckDB files. |
Tunnel hops
ssh-host,port(22),username, andauth:{ "type": "agent" },{ "type": "key-file", "path", "passphrase" }, or{ "type": "password", "password" }(passphraseandpasswordmay be left out; SQLly then asks on first connect). An optionaljumphost takes the same fields.keepalive_seconds(30 when absent, 0 for none) andkeepalive_max(3) set the tunnel's SSH keepalives.proxy-kind(socks5orhttp-connect),host,port, and optionalusernameandpassword.kube-namespace,target_kind(pod,service,deployment),target_name,remote_port, and optionalkubeconfigandcontext. It can't be combined with SSH or a proxy.
A complete example
Two databases on one PostgreSQL server reached through a bastion, sharing read and write logins; a SQL Server with its own password; and a local SQLite file, with a colored client and a production environment that allows SELECT only.
{
"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" }
]
}