API 참조
SQLly Embedded 브리지 관리 API의 모든 엔드포인트(OpenAPI(swagger.json) 문서에서 생성됨)와 sqlly.app 링크 엔드포인트.
임베디드 모드의 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.
규칙
- 인증:
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).
엔드포인트
- GET
/healthz - GET
/manage/status - PREFERRED
/manage/license/checkin - PUT
/manage/license - DELETE
/manage/license - GET
/manage/engines - GET
/manage/profiles - GET
/manage/profiles/{id} - PUT
/manage/profiles/{id} - DELETE
/manage/profiles/{id} - PREFERRED
/manage/tokens - GET
/manage/seats - DELETE
/manage/seats/{user} - PREFERRED
/manage/test-connection - GET
/manage/queries - PREFERRED
/api/embedded/links - PREFERRED
/api/embedded/links/token - GET
/api/embedded/public-key
상태
Liveness, 토큰 필요 없음.
/healthz
토큰 없음
Liveness 프로브
관리 리스너가 시작되자마자 응답합니다. 토큰이 필요 없으며, 시작 스크립트와 서비스 상태 확인에서 사용하세요.
- 200
- 관리 API가 리스닝 중입니다.
200 응답 예시
{
"ok": true
}
라이선스
브리지가 실행되는 라이선스: 상태, 체크인, 연결 및 연결 해제.
/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"
}
/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"
}
/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"
}
/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가 이를 하드코딩할 필요가 없습니다.
/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 자격 증명 문서로, 한 그룹의 사용자에게 보이는 연결(과 레이블)입니다. 브리지가 원본 저장소이며, 비밀 정보는 브라우저까지 오지 않습니다.
/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"
}
/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"
}
/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"
}
/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를 열도록 합니다. 좌석은 동시 사용자 수입니다.
/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"
}
/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"
}
/manage/seats/{user}
사용자의 좌석 해제
사용자의 토큰을 무효화하고 세션을 모두 닫아 좌석을 즉시 회수합니다. 사용자가 앱에서 로그아웃하거나 접근 권한을 잃었을 때 호출하세요. 좌석을 갖고 있지 않은 사용자를 회수해도 오류는 아닙니다. 경로 세그먼트는 퍼센트 디코딩됩니다: a%2Fb 가 해제하는 사용자는 a/b.
- 사용자
- 경로 · 문자열 · 필수 - 토큰을 발급한 사용자 ID (URL 인코딩됨).
- 204
- 출시됨.
- 400
bad_request: 이 세그먼트는 유효한 퍼센트 인코딩이 아닙니다.- 401
unauthorized: 관리 토큰이 없거나 잘못됨.
401 응답 예시
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
연결
사람이 쓰기 전에 연결이 동작하는지 먼저 확인하세요.
/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.
/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로 브리지에 전달합니다.
/api/embedded/links
sqlly.app
토큰 없음
설치 연결 시작(sqlly.app)
익명. 링크 요청을 생성하면 짧은 코드, 앱만 아는 시크릿, 라이선스 소유자가 승인하는 URL이 반환됩니다. 코드를 표시하고 linkUrl 소유자를 위해, 그런 다음 폴링 POST /api/embedded/links/token 모든 pollIntervalSeconds 승인될 때까지 대기합니다. 링크는 15분 후에 만료됩니다.
요청 본문(CreateLinkRequest)
{
"name": "SQLly Embedded on portal-01",
"hostname": "portal-01",
"appVersion": "1.4.0"
}
- 201
- 링크가 생성되었습니다.
- 429
- 속도 제한에 걸렸습니다.
- 503
link_unavailable: 코드를 할당할 수 없습니다; 다시 시도하십시오.
201 응답 예시
{
"linkId": "eml_Y2h9u0bQ1sXk4tWm8pZr3vLa",
"code": "K7Q-4MX",
"secret": "pW0r7…",
"linkUrl": "https://sqlly.app/embedded/link?code=K7Q-4MX",
"expiresAt": "2026-10-14T15:17:11Z",
"pollIntervalSeconds": 3
}
/api/embedded/links/token
sqlly.app
토큰 없음
연결된 키 폴링(sqlly.app)
익명; 링크 시크릿이 자격 증명입니다. 소유자가 아직 결정하지 않은 동안에는 응답이 202 pending. 승인되면 이 설치 전용 라이선스 키를 발급해 딱 한 번 돌려줍니다(링크는 소모됨). 키를 브리지로 전달할 때는 다음을 씁니다 PUT /manage/license; 직접 저장하지 마세요.
요청 본문(LinkTokenRequest)
- 200
- 승인되면 키가 한 번 전달됩니다.
- 202
- 아직 소유자를 기다리고 있습니다.
- 401
wrong_secret.- 404
unknown_link.- 410
link_used,link_denied,link_expired또는license_revoked: 이 링크는 절대 완료될 수 없습니다. 새 링크를 시작하세요.- 429
- 속도 제한에 걸렸습니다.
/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 |
* 필수