연결 파일 형식

정상 동작

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, 최대 1MB. 형식은 이미지 자체에서 감지합니다.
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 PostgreSQL 17 직접 TLS 연결용입니다).
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_sql연결 직후 실행할 SQL.
redis_key_delimiter, clickhouse_native_portRedis 및 ClickHouse용 엔진별 추가 기능.
redis_sentinel, redis_sentinel_passwordRedis 전용: 물어볼 센티넬 마스터 그룹과 센티넬 목록, 그리고 평문 상태의 센티넬 비밀번호(가져올 때 키체인으로 옮겨지며 절대 내보내지 않습니다).
redis_clusterRedis 전용: 클러스터 모드(auto, standalone, cluster) 및 노드 맵.
redis_entra_userMicrosoft Entra 로그인을 지원하는 Redis: 로그인에 사용할 Redis 사용자 이름이며, 비워 두면 토큰의 object id로 로그인합니다.
entra_accountMicrosoft 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 (익명 서버의 경우 생략).
noneSQLite 및 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, 그리고 색상 클라이언트와 SELECT만 허용하는 프로덕션 환경을 갖춘 로컬 SQLite 파일.

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