API 참조

SQLly Embedded 브리지 관리 API의 모든 엔드포인트(OpenAPI(swagger.json) 문서에서 생성됨)와 sqlly.app 링크 엔드포인트.

swagger.json 다운로드 OpenAPI 3.0 버전 1.0.0 기본 http://127.0.0.1:8445

임베디드 모드의 SQLly 브리지는 관리 리스너에서 이 API를 노출합니다 (--manage-bind기본값 127.0.0.1:8445). 웹 앱은 서버 측에서 이를 호출하여 연결 프로필을 저장하고, 연결을 테스트하며, 로그인한 사용자를 위한 실행 토큰을 발급하고, 좌석을 확인하며, 라이선스 상태를 읽거나 변경합니다.

모든 /manage/... 호출에는 Authorization: Bearer <manage token> (브리지의 --manage-token, 최소 16자). 본문은 입출력 모두 JSON 형식이며, 최대 8MB입니다 ( 413 too_large 한도를 넘는 즉시). 경로 세그먼트와 쿼리 문자열 값은 퍼센트 디코딩됩니다; 잘못된 이스케이프는 400 bad_request입니다. 자격 증명 문서가 유효하지 않을 때 오류는 항상 { "error": "<code>", "message": "<sentence>" }, 그리고 problems 자격 증명 문서가 유효하지 않을 때입니다. API는 CORS 헤더를 보내지 않으므로 루프백이나 사설 네트워크에서만 쓰고 브라우저에 노출하지 마세요. 프로필에는 데이터베이스 비밀번호가 담겨 있습니다.

그 Linking 작업은 브리지에 없습니다: 이들은 관리자 앱이 키를 복사하지 않고 설치를 라이선스에 연결할 때 쓰는 sqlly.app의 공개 엔드포인트입니다. 그 서버는 sqlly.app.

가이드: sqlly.app/docs/embedded

규칙

  • 인증: Authorization: Bearer <manage token> 매번 /manage/… 호출. 누락되었거나 잘못된 토큰은 401 unauthorized. /healthz 그리고 sqlly.app 연동 엔드포인트는 필요 없습니다.
  • 오류 은 { "error": "<code>", "message": "<sentence>" }. 다음 값으로 분기하고 error; 표시 message. 잘못된 자격 증명 문서에는 problems, 실수 하나당 문자열 하나씩.
  • 본문 JSON이고 최대 8MB입니다. 이 한도는 본문이 도착하는 동안 적용됩니다. 브리지의 응답은 다음과 같습니다 413 too_large 전달되는 즉시 시작하고 그 이상 버퍼링하지 않습니다. 도착하는 데 30초가 넘게 걸리는 본문은 408 timeout. 파싱할 수 없는 것은 전부 400 bad_json, 그리고 알 수 없는 경로는 404 not_found.
  • 경로 세그먼트 및 쿼리 값 퍼센트 디코딩되므로 사용자 ID와 타임스탬프는 URL 인코딩하세요 (DELETE /manage/seats/a%2Fb 가 해제하는 사용자는 a/b). 잘못된 이스케이프나 UTF-8이 아닌 결과는 400 bad_request.
  • 필드 이름 API 자체 페이로드에서는 camelCase입니다. 자격 증명 문서 안에서는 자격 증명 형식을 따릅니다 (sql_auth_accounts, trust_server_certificate).

엔드포인트

상태

Liveness, 토큰 필요 없음.

GET /healthz 토큰 없음

Liveness 프로브

관리 리스너가 시작되자마자 응답합니다. 토큰이 필요 없으며, 시작 스크립트와 서비스 상태 확인에서 사용하세요.

200
관리 API가 리스닝 중입니다.
200 응답 예시
{
  "ok": true
}

라이선스

브리지가 실행되는 라이선스: 상태, 체크인, 연결 및 연결 해제.

GET /manage/status

브리지 및 라이선스 상태

관리자 화면에 필요한 모든 정보: 라이선스 상태와 그 출처, 서명된 권한 부여가 담은 허용 범위, 사용 중인 좌석, 열려 있는 세션, 브라우저가 사용하는 프록시 URL.

200
현재 상태.
401
unauthorized: 관리 토큰이 없거나 잘못됨.
200 응답 예시
{
  "version": "1.1.0",
  "instanceId": "b5e1c0f2-7d3a-4c8e-9a61-0f2d4b7e9c13",
  "mode": "connected",
  "license": {
    "state": "ok",
    "source": "linked",
    "licenseId": "emb_Q2x0b3VkU3FsbHkxMjM0NTY3",
    "plan": "embedded-25",
    "planName": "SQLly Embedded 25",
    "status": "active",
    "seats": 25,
    "sessionsPerSeat": 4,
    "instances": 1,
    "domain": "portal.example.com",
    "periodEnd": "2027-10-14T00:00:00+00:00",
    "graceEnd": null,
    "daysRemaining": 365,
    "lastCheckinAt": "2026-10-14T15:00:02Z",
    "staleAt": "2026-10-14T15:40:02Z",
    "licenseFile": null,
    "message": null,
    "fromCache": false,
    "features": [
      "embedded",
      "unlimited-connections",
      "all-engines",
      "test-connection"
    ]
  },
  "seatsUsed": 3,
  "activeSessions": 4,
  "proxyUrl": "wss://portal.example.com/sqlly/proxy",
  "allowLocalhostOrigins": false,
  "storeUrl": "https://sqlly.app",
  "allowFileEngines": false
}
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
PREFERRED /manage/license/checkin

지금 sqlly.app에서 체크인하세요

연결됐거나 링크된 라이선스: 20분 주기를 기다리지 않고 즉시 체크인합니다. 오프라인 라이선스: 라이선스 파일을 다시 읽고 네트워크는 전혀 쓰지 않습니다. 어느 쪽이든 응답은 시도 뒤의 상태이며, 실패해도 상태는 그대로입니다.

200
체크인 후 상태.
401
unauthorized: 관리 토큰이 없거나 잘못됨.
409
not_linked: 브리지에 라이선스가 없으므로 체크인할 것이 없습니다.
422
license_file_invalid (오프라인): 파일이 없거나 손상되었거나 다른 키로 서명되었습니다.
502
store_unreachable 또는 grant_invalid: sqlly.app에 연결할 수 없거나 응답이 검증되지 않았습니다.
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
409 응답 예시
{
  "error": "not_linked",
  "message": "this bridge is not linked to a license yet"
}
PUT /manage/license

연결된 라이선스 키 설치

다음 플래그 없이 시작된 브리지에 --license-key / --license-file 런타임에 이 키를 받습니다(보통은 관리 앱이 링크 절차를 통해 sqlly.app에서 방금 수집한 키입니다). 브리지는 이 키로 먼저 체크인하고 나서 저장합니다(<state-dir>/license-key, 모드 0600)로 저장되지만 sqlly.app가 검증된 승인으로 답할 때만입니다. 그 후로는 연결된 브리지로 실행되고, 키는 재시작 후에도 재사용됩니다. 실패하면 아무것도 바뀌지 않습니다: 쓰던 키는 새 키가 검증될 때까지 계속 일합니다. 연결된 키를 다른 라이선스의 키로 바꾸면 새 키가 검증된 뒤에 기존 라이선스의 인스턴스 슬롯이 해제되고, 같은 라이선스로 재발급한 키는 스토어의 인스턴스 행을 재사용합니다.

요청 본문(LinkLicenseRequest)
{
  "licenseKey": "sqe_2xH7c0VqHk9LmZr1aPq4tN8bW6yD3sJfUe5o"
}
200
연결됨. 이제 상태에는 license.source: linked.
400
invalid_license_key: 비어 있거나, 잘못되었거나, 알 수 없거나, 취소된 키.
401
unauthorized: 관리 토큰이 없거나 잘못됨.
409
license_from_flag: 브리지가 다음 옵션으로 시작되었습니다 --license-key 또는 --license-file, 따라서 해당 라이선스는 이 API를 통해 관리되지 않습니다.
502
store_unreachable: sqlly.app에 접근할 수 없거나 응답이 확인되지 않았습니다.
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/license

이 설치의 연결 해제

이 브리지의 인스턴스 슬롯을 해제하고, sqlly.app에서 키를 폐기하고(가능한 경우), 저장된 키를 삭제하고, 열려 있는 모든 세션을 닫은 뒤 브리지를 다음으로 되돌립니다 unlicensed.

204
UNLINK됨.
401
unauthorized: 관리 토큰이 없거나 잘못됨.
404
not_linked: 연결된 키는 저장되지 않습니다.
409
license_from_flag: 브리지가 다음 옵션으로 시작되었습니다 --license-key 또는 --license-file, 따라서 해당 라이선스는 이 API를 통해 관리되지 않습니다.
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

엔진

자격 증명 형식이 허용하는 데이터베이스 엔진 목록으로, UI가 이를 하드코딩할 필요가 없습니다.

GET /manage/engines

자격 증명 형식에서 허용하는 엔진

SQLly가 지원하는 모든 데이터베이스 엔진과 자격 증명 문서에 적을 engine 자격 증명 문서에 적을 id, 기본 포트, 그리고 다음 여부 server 파일 경로이며, authentication.type 허용하는 값들입니다.

200
엔진.
401
unauthorized: 관리 토큰이 없거나 잘못됨.
200 응답 예시
[
  {
    "id": "sql-server",
    "name": "Microsoft SQL Server",
    "defaultPort": 1433,
    "fileBased": false,
    "authentication": [
      "sql-login",
      "integrated",
      "entra-browser",
      "entra-device-code"
    ]
  },
  {
    "id": "postgres",
    "name": "PostgreSQL",
    "defaultPort": 5432,
    "fileBased": false,
    "authentication": [
      "sql-login"
    ]
  },
  {
    "id": "sqlite",
    "name": "SQLite",
    "defaultPort": 0,
    "fileBased": true,
    "authentication": [
      "none"
    ]
  }
]
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

프로필

프로필은 이름이 붙은 SQLly 자격 증명 문서로, 한 그룹의 사용자에게 보이는 연결(과 레이블)입니다. 브리지가 원본 저장소이며, 비밀 정보는 브라우저까지 오지 않습니다.

GET /manage/profiles

프로필 목록

저장된 모든 프로필을 자격 증명 없이 반환합니다.

200
프로필 목록.
401
unauthorized: 관리 토큰이 없거나 잘못됨.
200 응답 예시
[
  {
    "id": "analysts",
    "name": "Analysts",
    "connections": 2,
    "updatedAt": "2026-10-14T15:02:11Z"
  }
]
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
GET /manage/profiles/{id}

프로필 하나 읽기

비밀값까지 담은 전체 자격 증명 문서가 붙은 프로필: 호출자는 신뢰되는 서버 측 앱입니다.

id
경로 · ^[A-Za-z0-9_-]{1,64}$ 패턴의 문자열 · 필수 - 프로필에 쓸 ID입니다.
200
프로필.
400
invalid_profile_id: ID는 다음 문자로 된 1-64자 A-Z a-z 0-9 _ -.
401
unauthorized: 관리 토큰이 없거나 잘못됨.
404
unknown_profile: 해당 ID를 가진 프로필이 없습니다.
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
404 응답 예시
{
  "error": "unknown_profile",
  "message": "no profile with id analysts"
}
PUT /manage/profiles/{id}

프로필 생성 또는 교체

프로필을 다음 위치에 저장합니다. id (생성 또는 교체). 자격 증명 문서는 작성되기 전에 전체적으로 검증됩니다: 파서가 찾는 모든 문제는 problems, 그리고 잘못된 문서는 아무것도 바꾸지 않습니다. 파일 기반 엔진(SQLite, DuckDB)을 담은 문서는 브리지가 다음 옵션으로 실행되지 않는 한 같은 방식으로 거부됩니다. --allow-file-engines true, 이러한 연결은 사용자가 브리지 호스트에서 파일에 접근할 수 있게 해주기 때문입니다. 이미 열린 세션은 시작한 카탈로그를 유지하며, 편집 사항은 다음 실행에 적용됩니다.

id
경로 · ^[A-Za-z0-9_-]{1,64}$ 패턴의 문자열 · 필수 - 프로필에 쓸 ID입니다.
요청 본문(PutProfileRequest)
{
  "name": "Analysts",
  "credentials": {
    "format": "sqlly-credentials",
    "version": 1,
    "clients": [
      {
        "name": "Northwind Traders",
        "color": "#1E88E5"
      }
    ],
    "environments": [
      {
        "name": "Production",
        "color": "#C62828",
        "safety": {
          "only_allow_select": true
        }
      }
    ],
    "sql_auth_accounts": [
      {
        "name": "Reader",
        "username": "reader",
        "password": "…"
      }
    ],
    "connections": [
      {
        "name": "Northwind",
        "engine": "sql-server",
        "server": "sql01.internal",
        "database": "Northwind",
        "environment": "production",
        "client": "Northwind Traders",
        "authentication": {
          "type": "sql-login",
          "account": "Reader"
        },
        "tls": {
          "encrypt": true,
          "trust_server_certificate": true
        }
      },
      {
        "name": "Warehouse",
        "engine": "postgres",
        "server": "dw.internal",
        "database": "dw",
        "environment": "production",
        "client": "Northwind Traders",
        "authentication": {
          "type": "sql-login",
          "account": "Reader"
        },
        "tls": {
          "mode": "verify-full"
        }
      }
    ]
  }
}
200
저장됨.
400
invalid_profile (와 함께 problems: 파서 문제, 또는 파일 기반 엔진이 다음인 동안 --allow-file-engines 꺼져 있음), 또는 invalid_profile_id.
401
unauthorized: 관리 토큰이 없거나 잘못됨.
500
storage: 상태 디렉터리를 쓸 수 없습니다.
400 응답 예시
{
  "error": "invalid_profile",
  "message": "the credential document has 2 problems",
  "problems": [
    "connections[0].engine: unknown engine \"postgress\"",
    "connections[1].authentication.pasword: unknown key"
  ]
}
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/profiles/{id}

프로필 삭제

프로필을 제거합니다. 열려 있는 세션은 시작할 때의 카탈로그를 유지하며, 새 실행 토큰은 다음 오류와 함께 거부됩니다 unknown_profile.

id
경로 · ^[A-Za-z0-9_-]{1,64}$ 패턴의 문자열 · 필수 - 프로필에 쓸 ID입니다.
204
삭제됨.
400
invalid_profile_id: ID는 다음 문자로 된 1-64자 A-Z a-z 0-9 _ -.
401
unauthorized: 관리 토큰이 없거나 잘못됨.
404
unknown_profile: 해당 ID를 가진 프로필이 없습니다.
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
404 응답 예시
{
  "error": "unknown_profile",
  "message": "no profile with id analysts"
}

실행

실행 토큰은 한 사용자가 하나의 프로필로 SQLly를 열도록 합니다. 좌석은 동시 사용자 수입니다.

PREFERRED /manage/tokens

실행 토큰 발급

짧은 수명의 토큰을 생성해 SQLly를 엽니다. 대상 사용자는 user 와 함께 profile, 원하면 곧바로 쿼리 탭으로 (open, 런치 컨텍스트). 반환된 proxyUrl 그리고 token 를 SQLly를 불러오는 페이지에 넣습니다 (globalThis.SQLLY_PROXY_URL / globalThis.SQLLY_PROXY_TOKEN). 토큰은 만료될 때까지(페이지 재로드) 재사용할 수 있으며, 프로필은 발급 시점에 캡처됩니다.

사용자는 열린 세션이나 만료되지 않은 토큰이 있는 동안 좌석을 점유합니다. 좌석을 이미 가진 사용자의 토큰 발급은 좌석 수 때문에 실패하지 않고, 새 사용자의 발급은 다음 오류로 실패합니다 seat_limit 라이선스의 모든 좌석이 사용 중일 때, 라이선스의 모든 브리지에 있는 사용자를 합산합니다.

요청 본문(MintTokenRequest)
{
  "user": "dana.analyst",
  "profile": "analysts",
  "open": {
    "connection": "Shop",
    "database": "sales",
    "title": "Big orders",
    "script": "SELECT *\nFROM orders\nWHERE total > @min_total",
    "parameters": {
      "min_total": 500
    },
    "cursor": {
      "line": 3,
      "column": 7
    }
  }
}
201
토큰.
400
invalid_user (비어 있거나 공백 포함, 최대 128자), invalid_profile (저장된 프로필이 더 이상 유효하지 않거나, 파일 기반 엔진을 보유하고 있을 경우 --allow-file-engines 꺼져 있음), 또는 invalid_open (실행 컨텍스트가 알 수 없는 연결, 알 수 없는 필드나 유형, 잘못된 매개변수 이름 또는 값, 범위를 벗어난 커서, 또는 제한을 전달하는 경우; problems 각 오류를 경로와 함께 나열합니다. 예를 들어 open[1].cursor: …).
401
unauthorized: 관리 토큰이 없거나 잘못됨.
404
unknown_profile: 해당 ID를 가진 프로필이 없습니다.
409
seat_limit: 모든 좌석이 사용 중입니다. 하나를 해제하세요(DELETE /manage/seats/{user}) 또는 더 큰 플랜을 구매하세요.
503
license_not_ok: 라이선스가 다음이 아닙니다 ok 또는 grace (오래되었거나, 만료되었거나, 취소되었거나, 승인되지 않았거나, 도메인이 일치하지 않거나 라이선스가 없음). 메시지에 그중 무엇인지 나옵니다.
201 응답 예시
{
  "token": "elt_q3J0n8w2Zx5rVb1kTq9yLs4dHf7cMa6p",
  "expiresAt": "2026-10-14T15:12:11Z",
  "proxyUrl": "wss://portal.example.com/sqlly/proxy",
  "user": "dana.analyst",
  "profile": "analysts",
  "seatsUsed": 3,
  "seats": 25,
  "openTabs": 0
}
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
GET /manage/seats

사용 중인 좌석

이 브리지에서 좌석을 차지한 사용자와 열려 있는 세션, 활성 토큰 목록입니다. seatsUsed 같은 라이선스의 다른 브리지에서 sqlly.app이 보고한 사용자도 포함합니다.

200
좌석 사용 현황
401
unauthorized: 관리 토큰이 없거나 잘못됨.
200 응답 예시
{
  "seats": 25,
  "seatsUsed": 2,
  "users": [
    {
      "user": "dana.analyst",
      "activeSessions": 1,
      "tokens": 1,
      "since": "2026-10-14T15:02:11Z"
    },
    {
      "user": "sam.support",
      "activeSessions": 2,
      "tokens": 1,
      "since": "2026-10-14T14:40:03Z"
    }
  ]
}
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/seats/{user}

사용자의 좌석 해제

사용자의 토큰을 무효화하고 세션을 모두 닫아 좌석을 즉시 회수합니다. 사용자가 앱에서 로그아웃하거나 접근 권한을 잃었을 때 호출하세요. 좌석을 갖고 있지 않은 사용자를 회수해도 오류는 아닙니다. 경로 세그먼트는 퍼센트 디코딩됩니다: a%2Fb 가 해제하는 사용자는 a/b.

사용자
경로 · 문자열 · 필수 - 토큰을 발급한 사용자 ID (URL 인코딩됨).
204
출시됨.
400
bad_request: 이 세그먼트는 유효한 퍼센트 인코딩이 아닙니다.
401
unauthorized: 관리 토큰이 없거나 잘못됨.
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

연결

사람이 쓰기 전에 연결이 동작하는지 먼저 확인하세요.

PREFERRED /manage/test-connection

하나의 연결 테스트

정확히 연결 하나가 담긴 자격 증명 문서로 일회용 엔진을 띄워 간단한 쿼리를 실행합니다. 연결 실패는 다음으로 보고됩니다 ok: false 엔진 자체 메시지(HTTP 200)로 보고됩니다; 사용할 수 없는 문서만 HTTP 오류입니다.

요청 본문(TestConnectionRequest)
{
  "credentials": {
    "format": "sqlly-credentials",
    "version": 1,
    "connections": [
      {
        "name": "Northwind",
        "engine": "sql-server",
        "server": "sql01.internal",
        "database": "Northwind",
        "authentication": {
          "type": "sql-login",
          "username": "reader",
          "password": "…"
        },
        "tls": {
          "encrypt": true,
          "trust_server_certificate": true
        }
      }
    ]
  }
}
200
결과, 성공 여부.
400
invalid_profile: 문서가 유효하지 않거나, 정확히 하나의 연결을 담고 있지 않거나, 파일 기반 엔진을 담고 있는 동안 --allow-file-engines 이(가) 꺼져 있습니다(자세한 내용은 problems).
401
unauthorized: 관리 토큰이 없거나 잘못됨.
200 응답 예시
{
  "ok": true,
  "elapsedMs": 212,
  "message": "Connected: SQL Server 17.0"
}
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

감사

쿼리 감사 기록: 한 세션이 실행한 모든 쿼리와 행 편집, 실행한 사람, 어떤 연결을 상대로 했는지, 어떻게 끝났는지. 메모리와 <state-dir>/queries.jsonl (SQL 텍스트 포함). 브리지가 다음과 함께 실행되지 않으면 --query-log false.

GET /manage/queries

쿼리 감사 추적

브리지 세션이 실행한 모든 쿼리와 행 편집, 최신 것부터: 실행 토큰의 사용자와 프로필, 지정한 연결(이름, 서버, 엔진, 데이터베이스), SQL 텍스트(64 KiB로 자름, 다음 참조 sqlTruncated), 시작 시각, 상태와 소요 시간, 실패했을 때의 엔진 오류가 표시됩니다. 아직 실행 중인 요청은 다음 상태로 나열됩니다 running; 라이선스가 정상적이지 않아 거부된 요청은 failed 라이선스 메시지와 함께 표시됩니다. 세션이 종료될 때 실행 중이던 것은 cancelled 다음 오류와 함께 session closed.

브리지에는 최신 --query-log-max-entries 개 항목(기본값 20,000)은 메모리와 <state-dir>/queries.jsonl에 유지되므로 이 기록은 재시작 후에도 남습니다. --query-log false 아무것도 기록되지 않으며 응답은 { "enabled": false, "queries": [] }.

제한
query · 정수 - 반환할 항목 수, 1-1000으로 제한됩니다.
사용자
query · 문자열 - 지정한 사용자 ID와 정확히 일치하는 항목만 (URL 인코딩).
프로필
query · 문자열 - 지정한 프로필 ID와 정확히 일치하는 항목만.
이후
query · 문자열 (날짜-시간) - 다음 조건에 맞는 항목만 at 다음 RFC 3339 타임스탬프 이후이거나 같은 시각입니다(URL 인코딩).
상태
query · QueryStatus - 이 상태인 항목만.
200
일치하는 항목, 최신순.
400
bad_request: limit 정수가 아니면, since 이(가) RFC 3339 형식이 아니면, status 을(를) 알 수 없거나 어떤 값이 유효한 퍼센트 인코딩이 아니면
401
unauthorized: 관리 토큰이 없거나 잘못됨.
200 응답 예시
{
  "enabled": true,
  "total": 2,
  "limit": 200,
  "queries": [
    {
      "id": "q-7",
      "sessionId": 12,
      "kind": "query",
      "at": "2026-10-14T15:04:09.120Z",
      "user": "dana.analyst",
      "profile": "analysts",
      "profileName": "Analysts",
      "connection": "Northwind",
      "server": "sql01.internal",
      "database": "Northwind",
      "engine": "Microsoft SQL Server",
      "sql": "SELECT TOP 100 * FROM Orders",
      "sqlTruncated": false,
      "status": "completed",
      "durationMs": 184,
      "error": null
    },
    {
      "id": "q-6",
      "sessionId": 12,
      "kind": "query",
      "at": "2026-10-14T15:03:51.004Z",
      "user": "dana.analyst",
      "profile": "analysts",
      "profileName": "Analysts",
      "connection": "Northwind",
      "server": "sql01.internal",
      "database": "Northwind",
      "engine": "Microsoft SQL Server",
      "sql": "SELECT * FROM Ordres",
      "sqlTruncated": false,
      "status": "failed",
      "durationMs": 31,
      "error": "Invalid object name 'Ordres'."
    }
  ]
}
401 응답 예시
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

연결 중

sqlly.app 엔드포인트 (서버) sqlly.app) 설치를 라이선스에 연결하는 절차입니다: 코드를 만들고, 소유자가 브라우저에서 승인하면, 설치 고유 키를 한 번 수집한 뒤 PUT /manage/license로 브리지에 전달합니다.

GET /api/embedded/public-key sqlly.app 토큰 없음

라이선스 서명 공개 키 (sqlly.app)

sqlly.app가 라이선스 승인에 서명할 때 쓰는 PEM 공개 키로, 운영자가 브리지에 컴파일된 키와 비교할 수 있습니다.

200
PEM 텍스트.
503
signing_not_configured.

스키마

위 객체들은 다음에 정의된 그대로입니다 swagger.json. A ? 타입 뒤에 나타나면 이는 가능함을 의미합니다. null.

오류

모든 오류 응답. error 기계가 읽을 수 있는 안정적인 코드입니다; message 관리자에게 보여줄 수 있는 문장입니다.

필드타입설명
error * string
message * string
problems string[] 포함되는 경우는 invalid_profile: 자격 증명 파서가 찾은 모든 문제.

LicenseState

ok 그리고 grace 쿼리를 처리합니다; 그 외 상태에서는 SQLly가 사용자에게 보여 주는 메시지와 함께 요청을 거부합니다.

다음 중 하나: ok grace stale not_admitted expired revoked domain_mismatch unlicensed

StatusReport

필드타입설명
version string 브리지 버전.
instanceId string sqlly.app에서 보는 이 브리지 프로세스의 ID.
mode connected | offline
license LicenseReport
seatsUsed integer 라이선스의 모든 브리지에서 사용 중인 좌석 수.
activeSessions integer 이 브리지에서 열려 있는 SQLly 세션.
proxyUrl string 브라우저가 사용하는 WebSocket URL (--public-url).
allowLocalhostOrigins boolean
storeUrl string
allowFileEngines boolean 프로필이 파일 기반 엔진을 담을 수 있는지 (--allow-file-engines).

LicenseReport

허용량은 서명된 그랜트에서 나오며, 서명되지 않은 데이터에서는 절대 나오지 않습니다.

필드타입설명
state LicenseState
source flag | file | linked | none flag: --license-key; file: --license-file; linked: PUT /manage/license로 저장됨; none: 라이선스 없음.
licenseId string?
plan string? 계획 ID, 또는 custom 자체 약관으로 배포되는 라이선스입니다.
planName string?
status string? 마지막 체크인 기준 sqlly.app 상태: 활성, 유예, 만료, 해지, 도메인 불일치.
seats integer 라이선스가 허용하는 동시 사용자 수.
sessionsPerSeat integer 한 사용자가 열 수 있는 SQLly 탭 수.
instances integer 한 번에 실행할 수 있는 브리지 수(연결된 라이선스; 오프라인 0).
domain string? 바인딩된 도메인이며, 브라우저는 이 도메인이나 하위 도메인에서 접속해야 합니다.
periodEnd string? 유료 기간 종료 (ISO 8601).
graceEnd string? 유예 기간에 설정되는 값: 브리지가 서비스를 중단하는 시각.
daysRemaining integer? 브리지가 서비스를 중단할 때까지 남은 일 수(하루 단위).
lastCheckinAt string (date-time)?
staleAt string (date-time)? 체크인이 한 번도 성공하지 않으면 브리지가 오래된 상태가 되는 시점(마지막 유효 권한 + 40분).
licenseFile string? 오프라인: 사용 중인 라이선스 파일.
message string? 문제가 생겼을 때 사용자에게 보이는 문장(유예 카운트다운에도 사용).
fromCache boolean sqlly.app에 접근할 수 없어서 브리지가 캐시된 권한에서 시작되었을 때 true.
features string[]

LinkLicenseRequest

필드타입설명
licenseKey * string 다음으로 시작하는 키 sqe_.

EngineInfo

필드타입설명
id string 그 engine 자격 증명 문서의 값.
name string
defaultPort integer
fileBased boolean server 파일 경로이므로 로그인은 적용되지 않습니다.
authentication string[] 수락됨 authentication.type 값.

ProfileSummary

필드타입설명
id string
name string
connections integer 문서 내 연결 수.
updatedAt string (date-time)

StoredProfile

필드타입설명
id string
name string
credentials CredentialDocument
updatedAt string (date-time)

PutProfileRequest

필드타입설명
name * string SQLly에서 사용자에게 표시되는 이름.
credentials * CredentialDocument

CredentialDocument

SQLly 자격 증명 문서(SQLly의 파일 → 연결 가져오기와 동일한 형식). 알 수 없는 키는 오류로 처리되므로 오타가 무시되지 않고 보고됩니다. 전체 참조: sqlly.app/docs (자격 증명 파일 형식).

필드타입설명
format * sqlly-credentials
version * 1
clients Label[]
projects Label[]
environments Label[]
sql_auth_accounts SharedLogin[]
tunnel_profiles object[]
connections Connection[]

라벨

필드타입설명
name * string
color string #RGB, #RRGGBB 또는 #RRGGBBAA.
image string 아이콘은 data: URI 또는 base64 문자열(PNG, JPEG, GIF, WebP, BMP, ICO, SVG; 최대 1MB)로 지정합니다.
safety object 나열한 플래그만 변경됩니다.

SharedLogin

필드타입설명
name * string
username * string
password string

연결

필드타입설명
name * string
engine * string GET /manage/engines에서 가져온 ID.
server * string 호스트, IP, host\instance 또는 SQLite/DuckDB 파일 경로.
port integer
database string
environment string local, dev, test, staging, production, 또는 설정하지 않음.
client string 클라이언트 레이블 이름.
project string 프로젝트 라벨의 이름입니다.
authentication Authentication
tls object
timeout_seconds integer
statement_timeout_seconds integer
application_name string
safety object
favorite boolean
startup_sql string
tunnel_profile string
transport object 인라인 프록시, SSH, 쿠버네티스 홉.
masking object { include: [...], exclude: [...] } 열 마스킹 규칙.

인증

필드타입설명
type * sql-login | integrated | entra-browser | entra-device-code | aws-rds-iam | gcp-cloud-sql-iam | auth-token | none
username string
password string
account string sql_auth_accounts의 공유 로그인 이름.
region string
profile string
token string

MintTokenRequest

필드타입설명
user * string 각 사용자를 식별하는 고정 ID(공백 없음). 좌석은 고유 사용자별로 집계됩니다.
profile * string 프로필 ID.
ttlSeconds integer 토큰 수명; 기본값은 --token-ttl-seconds (600)이며 10초 - 24시간 범위로 제한됩니다.
open LaunchTab | LaunchTab[] 실행 컨텍스트: 세션이 시작될 때 SQLly가 여는 쿼리 탭으로, 1개 또는 최대 8개입니다. 토큰이 허가하는 첫 세션에만 전달되며, 새로 고침이나 이후 세션에는 전달되지 않습니다. 발급 시점에 프로필과 대조해 검증합니다(400 invalid_open). 사용자가 Run을 누르기 전에는 아무것도 실행되지 않습니다. 가이드: sqlly.app/docs/embedded/launch-context

LaunchTab

실행 하나가 여는 쿼리 탭 한 개. 필요한 것: script, connection, 혹은 둘 다.

필드타입설명
connection string 토큰 프로필의 연결. 이름(대소문자 구분 없음, 고유해야 함) 또는 id로 지정. 프로필에 연결이 하나면 선택 사항이고, 여러 개인데 이름을 지정하지 않으면 탭이 연결 없이 열립니다.
database string 연결 기본값 대신 전환할 데이터베이스.
title string 탭 제목.
script string 불러올 SQL(원문 그대로, 최대 256 KiB, CRLF는 LF로 변환).
parameters object 스크립트의 @name 매개변수, 이름으로 구분하며(다음을 붙이거나 붙이지 않거나 @). 단독 값의 유형은 추론됩니다(정수는 int, 다른 숫자는 decimal, 불리언은 bool, 문자열은 text, null은 empty); 다음을 사용해 { type, value } 선택하면 됩니다. 스크립트가 선언하지 않은 매개변수에는 -- sqlly param: 줄로 선언하세요. 값은 SQLly의 파라미터 스트립에 나타나며, 앱이 SQL에 직접 끼워 넣는 일은 없습니다
cursor LaunchCursor

LaunchParameterValue

필드타입설명
type text | int | decimal | bool | date | datetime | time | uuid | json | binary
value string | number | boolean

LaunchCursor

다음의 캐럿 위치: script, 1 기반입니다. 열은 문자 수를 세며, 줄 끝보다 한 칸 뒤일 수도 있습니다.

필드타입설명
line integer
column integer

발행된 토큰

필드타입설명
token string
expiresAt string (date-time)
proxyUrl string
user string
profile string
seatsUsed integer 이 사용자를 포함한 사용 중인 좌석.
seats integer
openTabs integer 세션이 열 탭 수(실행 컨텍스트가 없으면 0).

좌석 보고서

필드타입설명
seats integer
seatsUsed integer
users UserSeat[]

UserSeat

필드타입설명
user string
activeSessions integer
tokens integer 만료되지 않은 실행 토큰.
since string (date-time)

TestConnectionRequest

필드타입설명
credentials * CredentialDocument

TestOutcome

필드타입설명
ok boolean
elapsedMs integer
message string 엔진 자체 메시지, 성공 또는 실패.

쿼리 상태

running 엔진이 응답할 때까지 기다립니다; 그런 다음 completed, failed (참조 error) 또는 cancelled (사용자에 의해, 또는 session closed).

다음 중 하나: running completed failed cancelled

쿼리 입력

감사 기록이 남는 요청 한 건.

필드타입설명
id string 엔진 요청 ID로, 세션 안에서 고유합니다.
sessionId integer 브라우저 세션에 대한 브리지 ID.
kind query | row-edit
at string (date-time) 요청이 브리지에 도달한 시간.
user string 시작 토큰의 사용자 ID.
profile string 시작 토큰의 프로필 ID.
profileName string
connection string 프로필에 있는 연결의 이름.
server string
database string? 프로필이 데이터베이스를 지정해 두면 그 데이터베이스, 아니면 요청이 가리킨 데이터베이스.
engine string 엔진의 표시 이름.
sql string SQL 텍스트 또는 row edit: <op> 행 편집용. 64 KiB로 잘립니다.
sqlTruncated boolean
status QueryStatus
durationMs integer? 실행 중에는 NULL입니다.
error string? 엔진의 오류 failed; session closed 세션이 끊겨 요청이 중단된 경우입니다.

쿼리 목록

필드타입설명
enabled boolean 브리지가 다음 옵션으로 실행될 때는 False --query-log false; 그런 다음 queries 항상 비어 있습니다.
queries QueryEntry[] 최신 순.
total integer 필터와 일치하는 항목 중 limit 적용되었습니다.
limit integer 적용된 페이지 크기 (1-1000).

CreateLinkRequest

필드타입설명
name string 승인 페이지와 소유자의 Embedded 페이지에 표시됩니다.
hostname string
appVersion string

CreateLinkResponse

필드타입설명
linkId string
code string 소유자에게 보여 주고 일치 여부를 확인하도록 하세요.
secret string 서버 쪽에 보관하며, 키를 수집합니다.
linkUrl string 소유자가 승인할 수 있도록 이것을 엽니다.
expiresAt string (date-time)
pollIntervalSeconds integer

LinkTokenRequest

필드타입설명
linkId * string
secret * string

LinkPending

필드타입설명
status pending
expiresAt string (date-time)

LinkApproved

필드타입설명
status approved
licenseKey string 한 번만 반환됩니다. PUT /manage/license에 전달하세요.
keyId string
licenseId string
plan string 계획 ID, 또는 custom.
planName string
accountEmail string

* 필수