Credential file format

How a SQLly credential file is laid out - labels, shared logins, tunnel profiles, and connections - with every key it accepts and a complete example.

A SQLly credential file is a single JSON document. It is what File → Export Credentials… writes and what File → Import Connections… reads (see Export & import credentials). You can also write one by hand. This page is an overview of how the file is laid out and what each part accepts.

Layout at a glance

{
  "format": "sqlly-credentials",   // required, always this value
  "version": 1,                     // required
  "clients":      [ … ],          // labels with color, icon, protections
  "projects":     [ … ],
  "environments": [ … ],
  "sql_auth_accounts": [ … ],     // shared logins: name, username, 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 version newer than your SQLly understands says so instead of half-importing.

Clients, projects & environments

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.

Sign-in methods

Tunnel hops

• ssh - host, port (22), username, and auth: { "type": "agent" }, { "type": "key-file", "path", "passphrase" }, or { "type": "password", "password" }. An optional jump host takes the same fields.
• proxy - kind (socks5 or http-connect), host, port, and optional username and password.
• kube - namespace, target_kind (pod, service, deployment), target_name, remote_port, and optional kubeconfig and context. 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" }
  ]
}

To see every option a connection of yours uses, set it up in SQLly and export it with File → Export Credentials… - then compare with Export & import credentials.