Formato de archivo de conexiones
funcionalCó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.
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
versionmás reciente de lo que entiende tu SQLly lo avisa en lugar de importar a medias.
Clientes, proyectos y entornos
| Clave | Lo que contiene |
|---|---|
name | Obligatorio. Se combina con una etiqueta existente del mismo nombre, o crea una. |
color | #RGB, #RRGGBB, o #RRGGBBAA (el # es opcional). |
image | El 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. |
safety | Cualquiera 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.
| Clave | Lo que contiene |
|---|---|
name | El nombre que se muestra en el explorador. |
engine | Escrito 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. |
server | Nombre del host, IP, host\instance, o la ruta del archivo para SQLite y DuckDB. |
port | Por defecto, usa el puerto habitual del motor. |
database | Base de datos a abrir (Oracle: nombre del servicio, o SID:ORCL). |
environment | local, dev, test, staging, production, o unset. |
client, project | Nombres de etiquetas. |
authentication | Cómo iniciar sesión - ver más abajo. |
tls | mode (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_seconds | Tiempo de espera de conexión (por defecto 30) y un límite opcional por instrucción. |
application_name | Se informa al servidor (por defecto SQLLY). |
safety | auto_wrap_rollback, block_all_but_select, confirm_data_changes, allow_unbounded_mutations, y production_override para esta conexión. |
favorite | Marca la conexión con una estrella. |
startup_sql | SQL a ejecutar justo después de conectar. |
redis_key_delimiter, clickhouse_native_port | Extras específicos del motor para Redis y ClickHouse. |
redis_sentinel, redis_sentinel_password | Solo 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_cluster | Solo Redis: modo clúster (auto, standalone, cluster) y el mapa de nodos. |
redis_entra_user | Redis 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_account | Fijar 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 transport | Un perfil de túnel con nombre, o en línea proxy, ssh, y kube saltos. |
masking | include y exclude listas de patrones de columnas como "*ssn*", o { "pattern": "users.email", "scope": "table-dot-column" }. |
Métodos de inicio de sesión
type | Campos |
|---|---|
sql-login | username y password, o account nombrando un inicio de sesión compartido. Omite la contraseña y SQLly la pedirá en la primera conexión. |
integrated | Windows / Kerberos (SQL Server). |
entra-browser, entra-device-code | Microsoft Entra (SQL Server, Azure SQL). |
aws-rds-iam | username, region, opcional profile. |
gcp-cloud-sql-iam | username. |
auth-token | libSQL / Turso token (omítelo si el servidor es anónimo). |
none | Archivos SQLite y DuckDB. |
Saltos de túnel
ssh-host,port(22),username, yauth:{ "type": "agent" },{ "type": "key-file", "path", "passphrase" }, o{ "type": "password", "password" }(passphraseypasswordpueden omitirse; SQLly luego pregunta en la primera conexión). Unjumphost opcional toma los mismos campos.keepalive_seconds(30 si se omite, 0 para ninguno) ykeepalive_max(3) establecen los keepalives SSH del túnel.proxy-kind(socks5ohttp-connect),host,port, y opcionalusernameypassword.kube-namespace,target_kind(pod,service,deployment),target_name,remote_port, y opcionalkubeconfigycontext. 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" }
]
}