Формат файла подключений

функциональный

Как устроен файл подключений 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 МБ. Тип определяется по самому изображению.
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).
environmentlocal, dev, test, staging, production, или unset.
client, projectИмена меток.
authenticationКак войти – см. ниже.
tlsmode (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 для прямого TLS в PostgreSQL 17).
timeout_seconds, statement_timeout_secondsТайм-аут подключения (по умолчанию 30) и необязательный лимит на каждую инструкцию.
application_nameСообщается серверу (по умолчанию SQLLY).
safetyauto_wrap_rollback, block_all_but_select, confirm_data_changes, allow_unbounded_mutations, и production_override для этого одного соединения.
favoriteПометить соединение звездочкой.
startup_sqlSQL для выполнения сразу после подключения.
redis_key_delimiter, clickhouse_native_portДополнительные возможности движков Redis и ClickHouse.
redis_sentinel, redis_sentinel_passwordТолько Redis: мастер-группа Sentinel и sentinels, к которым обращаться, плюс пароль самих sentinels в открытом виде (при импорте переносится в связку ключей, никогда не экспортируется).
redis_clusterТолько Redis: режим кластера (auto, standalone, cluster) и карта узлов.
redis_entra_userRedis со входом Microsoft Entra: имя пользователя Redis, под которым выполняется вход; если не указано, вход выполняется под object id токена.
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 переходы.
maskinginclude и exclude списки шаблонов столбцов, таких как "*ssn*", или { "pattern": "users.email", "scope": "table-dot-column" }.

Методы входа

typeПоля
sql-loginusername и password, или account указание общего логина. Не указывайте пароль, и SQLly спросит его при первом подключении.
integratedWindows / Kerberos (SQL Server).
entra-browser, entra-device-codeMicrosoft Entra (SQL Server, Azure SQL).
aws-rds-iamusername, region, необязательно profile.
gcp-cloud-sql-iamusername.
auth-tokenlibSQL / 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" }
  ]
}