Formato de archivo de conexiones

funcional

Cómo se estructura un archivo de conexión de SQLly: etiquetas, inicios de sesión compartidos, perfiles de túnel y conexiones, con cada clave que acepta y un ejemplo completo.

Un archivo de conexión de SQLly es un único documento JSON. Es lo que ambos Archivo → Exportar conexiones… y Archivo → Exportar conexión con credenciales… escribe y lo que Archivo → Importar conexiones… lee (ver Exportar e importar conexiones). También puedes escribir uno a mano. Esta página es una visión general de cómo está organizado el archivo y qué acepta cada parte.

Las contraseñas son opcionales y, cuando se incluyen, van en texto claro. Cada password, passphrase, y token campo se puede omitir: Export Connections no escribe ninguno, y una conexión que no lo tenga lo pide al conectarse por primera vez. Un archivo que los contenga es un secreto en sí mismo. SQLly mueve cada contraseña a tu llavero del sistema al importar y nunca guarda una copia del archivo; elimínalo una vez importado.

Diseño a simple vista

{
  "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
}

Cada sección es opcional excepto format y version. Las conexiones apuntan a inicios de sesión compartidos, perfiles de túnel y etiquetas por nombre, por lo que un solo inicio de sesión o túnel puede servir para muchas conexiones. Los nombres se comparan sin distinguir mayúsculas de minúsculas, y un nombre también puede apuntar a algo ya guardado en SQLly.

Un servidor con varias bases de datos es simplemente varias conexiones que comparten un server y difieren en database. Varios inicios de sesión en la misma base de datos son varias conexiones que usan cuentas distintas.

Comprobación antes de cambiar nada

  • Todo o nada - primero se comprueba el archivo entero. Si algo está mal, se lista cada problema con su ubicación (por ejemplo connections[2] "Ops": port must be 1-65535) y no se importa nada.
  • Los errores tipográficos son errores - una clave desconocida como "pasword" se notifica en lugar de ignorarse en silencio.
  • Se aplican las reglas del motor - un método de inicio de sesión que el motor no soporta, un motor alojado que requiere TLS con el cifrado desactivado o un certificado de cliente sin su clave: todo se notifica.
  • Las versiones más nuevas se rechazan - un archivo con un version más reciente de lo que entiende tu SQLly lo avisa en lugar de importar a medias.

Clientes, proyectos y entornos

ClaveLo que contiene
nameObligatorio. Se combina con una etiqueta existente del mismo nombre, o crea una.
color#RGB, #RRGGBB, o #RRGGBBAA (el # es opcional).
imageEl icono, codificado en base64 - un data:image/png;base64,… URI o base64 sin formato. PNG, JPEG, GIF, WebP, BMP, ICO o SVG, hasta 1 MB. El tipo se detecta a partir de la propia imagen.
safetyCualquiera de 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 (cada true / false). Solo cambian los flags que enumeres.

Omitir color, image, o un interruptor de seguridad deja la etiqueta tal como está.

Inicios de sesión compartidos

{ "name": "Reader", "username": "ro", "password": "…" }

Una conexión usa uno con "authentication": { "type": "sql-login", "account": "Reader" }. Al importar sobre un inicio de sesión guardado con el mismo nombre y usuario, se actualiza la contraseña directamente.

Perfiles de túnel

{ "name": "Corp bastion", "ssh": { … }, "proxy": { … }, "kube": { … } }

Los saltos usan las mismas formas que el transport de una conexión (abajo). Una conexión usa uno con "tunnel_profile": "Corp bastion", en lugar de en línea transport.

Conexiones

Solo name, engine, y server son obligatorios. Lo que se omita toma el mismo valor por defecto que le habría dado el editor de conexiones.

ClaveLo que contiene
nameEl nombre que se muestra en el explorador.
engineEscrito de manera informal: postgresql, postgres, mssql, sql-server, mysql, mariadb, sqlite, duckdb, libsql, clickhouse, oracle, redis, valkey, neon, supabase, planetscale, cockroachdb, y el resto de los motores que SQLly soporta.
serverNombre del host, IP, host\instance, o la ruta del archivo para SQLite y DuckDB.
portPor defecto, usa el puerto habitual del motor.
databaseBase de datos a abrir (Oracle: nombre del servicio, o SID:ORCL).
environmentlocal, dev, test, staging, production, o unset.
client, projectNombres de etiquetas.
authenticationCómo iniciar sesión - ver más abajo.
tlsmode (disable, require, verify-ca, verify-full), o el estilo de SQL Server encrypt y trust_server_certificate interruptores. También ca_file, client_cert_file, y client_key_file rutas, y trust_os_roots (true también confiar en el almacén de certificados del sistema operativo; Redis), y direct (true para TLS directo de PostgreSQL 17).
timeout_seconds, statement_timeout_secondsTiempo de espera de conexión (por defecto 30) y un límite opcional por instrucción.
application_nameSe informa al servidor (por defecto SQLLY).
safetyauto_wrap_rollback, block_all_but_select, confirm_data_changes, allow_unbounded_mutations, y production_override para esta conexión.
favoriteMarca la conexión con una estrella.
startup_sqlSQL a ejecutar justo después de conectar.
redis_key_delimiter, clickhouse_native_portExtras específicos del motor para Redis y ClickHouse.
redis_sentinel, redis_sentinel_passwordSolo Redis: el grupo maestro de Sentinel y los sentinels a los que preguntar, y la contraseña de los propios sentinels en texto claro (se mueve al llavero al importar y nunca se exporta).
redis_clusterSolo Redis: modo clúster (auto, standalone, cluster) y el mapa de nodos.
redis_entra_userRedis con inicio de sesión de Microsoft Entra: el nombre de usuario de Redis con el que iniciar sesión; si no se proporciona, inicia sesión con el id de objeto del token.
entra_accountFijar una cuenta de Microsoft Entra: account_id, tenant_id, username.
route{ "type": "direct" } (predeterminado) o { "type": "via-relay", "relay_device_id", "pair_id" }.
tunnel_profile o transportUn perfil de túnel con nombre, o en línea proxy, ssh, y kube saltos.
maskinginclude y exclude listas de patrones de columnas como "*ssn*", o { "pattern": "users.email", "scope": "table-dot-column" }.

Métodos de inicio de sesión

typeCampos
sql-loginusername y password, o account nombrando un inicio de sesión compartido. Omite la contraseña y SQLly la pedirá en la primera conexión.
integratedWindows / Kerberos (SQL Server).
entra-browser, entra-device-codeMicrosoft Entra (SQL Server, Azure SQL).
aws-rds-iamusername, region, opcional profile.
gcp-cloud-sql-iamusername.
auth-tokenlibSQL / Turso token (omítelo si el servidor es anónimo).
noneArchivos SQLite y DuckDB.

Saltos de túnel

  • ssh - host, port (22), username, y auth: { "type": "agent" }, { "type": "key-file", "path", "passphrase" }, o { "type": "password", "password" } (passphrase y password pueden omitirse; SQLly luego pregunta en la primera conexión). Un jump host opcional toma los mismos campos. keepalive_seconds (30 si se omite, 0 para ninguno) y keepalive_max (3) establecen los keepalives SSH del túnel.
  • proxy - kind (socks5 o http-connect), host, port, y opcional username y password.
  • kube - namespace, target_kind (pod, service, deployment), target_name, remote_port, y opcional kubeconfig y context. No se puede combinar con SSH ni con un proxy.

Un ejemplo completo

Dos bases de datos en un mismo servidor PostgreSQL, a las que se llega por un bastión y compartiendo usuarios de lectura y escritura; un SQL Server con su propia contraseña; y un archivo SQLite local, con un cliente de color y un entorno de producción que solo permite 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" }
  ]
}