작동 방식
동작 원리: 브리지, 세션별 엔진, 실행 토큰, 서명된 라이선스 승인, 체크인, 좌석, Origin 규칙, 그리고 자격 증명이 어디에 담기는지.
SQLly Embedded는 SQLly를 비밀이 필요한 절반과 그렇지 않은 절반으로 나눕니다. SQLly UI는 사용자의 브라우저에서 WebAssembly로 실행됩니다. 데이터베이스를 건드리는 모든 일은 서버 위에서, SQLly 브리지와 그 브리지가 띄우는 엔진 안에서 이뤄집니다. 여러분의 웹 앱은 브리지 옆에 붙어 누가 어떤 연결로 SQLly를 열 수 있는지 알려줍니다. 이 페이지는 각 구성 요소와 그렇게 만든 이유를 설명합니다.
아키텍처
왜 분리되었는가
- 비밀 정보는 서버에만 보관됩니다. 브라우저는 자기 사용자에게 데이터베이스 비밀번호를 숨길 수 없습니다. 그래서 브라우저는 애초에 비밀번호를 받지 않습니다. 받는 것은 연결 목록이고, 쿼리 프레임을 보내면, 자격 증명은 서버만 가진 채 브리지가 실행합니다.
- 신원 관리는 앱이 계속 담당합니다. 브리지에는 사용자 계정이 없습니다. 로그인한 사람이 누구인지는 앱이 이미 알고 있습니다. 브리지에 "SQLly를 열어 달라고 말하되 대상은 이것 사용자와 이것 프로필"이라고 실행 토큰을 발행해 알려 주고, 브리지는 그 토큰을 신뢰합니다.
- 세션당 한 개의 엔진. 각 브라우저 탭에는 자신만의
sqlly-cli프로세스이므로 세션은 연결 상태, 트랜잭션 또는 임시 테이블을 공유하지 않으며, 충돌이 발생해도 하나의 탭만 종료되고 브리지는 영향을 받지 않습니다.
브리지 내부
sqlly-bridge embedded 은(는) 프로세스 하나로 세 가지 일을 합니다:
| 작업 | 수신 주소 | 통신 대상 |
|---|---|---|
| 브라우저 프록시: SQLly 탭마다 WebSocket을 수락하고, Origin과 실행 토큰을 확인하며, 토큰의 프로필로 엔진을 시작하고, 프레임을 양방향으로 중계합니다. | --bind기본값 0.0.0.0:8444경로 /proxy | 브라우저(TLS를 앞에) |
| 관리 API: 프로필, 실행 토큰, 좌석, 연결 테스트, 라이선스 상태, 쿼리 감사 기록. 참고. | --manage-bind기본값 127.0.0.1:8445 | 앱의 서버 측 전용, 베어러 토큰 사용 |
| 라이선스 모니터: 시작 시와 연결 중일 때는 20분마다 sqlly.app에 체크인하고, 오프라인일 때는 매분 라이선스 파일을 다시 읽으며, 브리지를 라이선스 상태 사이에서 옮깁니다. | 없음 | HTTPS로 sqlly.app와 통신(연결된 경우만) |
이 도구의 상태 디렉토리 (--state-dir, Linux와 macOS에서 소유자 전용으로 생성)은 모든 프로필을 profiles/<id>.json, 마지막으로 유효한 라이선스 허가(license.json), 연결된 설치 키(license-key, 모드 0600), 엔진에 제공하는 세션별 자격 증명 파일, 그리고 쿼리 감사 기록(queries.jsonl: 세션에서 실행한 모든 쿼리와 해당 SQL 텍스트). 백업하고, 비밀번호 파일처럼 비공개로 보관하세요. 실제로 비밀번호 파일과 다름없기 때문입니다. 어디에 두는지, 그리고 Windows에 필요한 것.
프로필: 사용자가 볼 수 있는 것
A 프로필 이름 붙은 SQLly 자격 증명 문서입니다. SQLly 데스크톱 앱이 가져오고 내보내는 그와 같은 JSON 형식이죠. 연결(서버, 데이터베이스, 엔진, 인증, TLS, 안전 규칙)과 이를 색으로 구분하고 묶는 클라이언트·프로젝트·환경 레이블이 기록됩니다. 앱은 프로필을 다음과 함께 저장합니다 PUT /manage/profiles/{id}. 브리지는 문서 전체를 미리 검증해 문제를 한꺼번에 보고하므로, 다음 같은 오타는 "pasword" 무시되는 대신 명확하게 실패합니다.
브리지에서 사용자는 프로필에 속하지 않습니다. 실행할 때마다 프로필을 하나 지정합니다. 분석가에게는 읽기 전용 프로필을 주세요(연결에 only_allow_select, 또는 block_all_but_select 인 라벨입니다: 엔진은 데이터베이스에 도달하기 전에 SELECT 외에는 거부합니다) 지원 담당자에게는 다른 프로필을, 멀티테넌트 앱이라면 고객별로 프로필을 하나씩 만드세요. 파일 기반 엔진(SQLite, DuckDB)은 브리지가 다음과 함께 시작된 경우가 아니면 거부됩니다 --allow-file-engines, 이런 연결은 사용자에게 브리지 호스트의 파일 접근을 주기 때문입니다. 연결 수를 줄여 주려면 다른 프로필을 만드세요. 세션이 열리면 브라우저는 그 프로필의 카탈로그: 연결 이름, 엔진, 데이터베이스 및 라벨을 모든 비밀 정보가 제거된 상태로 받습니다. 프로필을 편집하면 다음 실행에 적용됩니다. 이미 열린 세션은 시작할 때의 카탈로그를 유지합니다.
세션의 수명 주기
- 로그인한 사용자가 앱에서 SQLly 페이지를 엽니다.
- 내 서버가 다음을 호출합니다
POST /manage/tokens사용자 ID와 받게 될 프로필, 그리고 필요하면 열 내용: 스크립트, 연결, 매개변수 값, 커서를 갖춘 쿼리 탭(실행 컨텍스트). - 브리지는 라이선스와 좌석 수를 확인하고, 프로필을 캡처하며, 임의의 토큰, 만료 시간 및 공개 프록시 URL을 반환합니다.
- 내 서버가 SQLly 페이지를 돌려줍니다 (
web/index.html) 두 개의 전역 변수를 다음보다 먼저 설정한 상태로boot.js:SQLLY_PROXY_URL그리고SQLLY_PROXY_TOKEN. - SQLly는
wss://…/proxy?token=…브리지는 순서대로 브라우저를 확인합니다Origin(업그레이드 시 403으로 거부됨), 토큰, 라이선스, 사용자의 열린 세션, 그리고 자체 세션 한도. 브라우저는 업그레이드 실패 이유를 읽을 수 없으므로, 오리진 검사 이후의 모든 거부는 열린 소켓을 통해 다음과 같은error사유가 담긴 메시지가 먼저 전달되고, 이어서 종료 코드가 전달됩니다.4000 + HTTP status(4401 토큰 없음 또는 만료, 4503 라이선스 문제, 4429 세션 한도); SQLly는 그 문장 자체를 보여 줍니다. - 브리지는 프로필의 자격 증명을 세션별 개인 파일에 기록한 뒤
sqlly-cli엔진 모드로 실행할 때 씁니다. - 브라우저는 비밀 없이 연결 카탈로그를 담은 hello와 현재 라이선스 상태를 받습니다. 실행 컨텍스트를 넣어 발급한 토큰의 첫 세션은 열어 둘 탭도 함께 받는데, SQLly는 탭을 불러올 뿐 아무것도 실행하지 않습니다.
- 이 시점부터 SQLly의 요청(connect, run, cancel, IntelliSense용 메타데이터 가져오기, 결과 페이징)은 바이너리 프레임으로 전송됩니다. 브리지(bridge)는 이를 엔진으로 중계하고, 모든 쿼리와 행 편집을 기록하며 감사 추적, 그리고 라이선스가 무효가 되면 메시지와 함께 이를 거부합니다.
좌석과 세션
A 좌석 열린 세션이나 만료되지 않은 실행 토큰을 가진 별개의 사용자 ID입니다. 좌석은 이름이 아니라 동시 접속 기준입니다. 사용자의 마지막 탭이 닫히고 마지막 토큰이 만료되면 좌석은 즉시 풀려 다른 사람이 쓸 수 있습니다. 브리지는 라이선스에 속한 모든 브리지를 합쳐 좌석을 세는데, sqlly.app이 체크인할 때마다 다른 인스턴스의 사용자 수를 보고하기 때문입니다.
- 토큰 발급 대상 사용자가 이미 좌석을 유지하는 것은 항상 성공합니다. 모든 좌석이 사용 중일 때 새 사용자를 발급하려고 하면
409 seat_limit, 그래서 앱이 명확한 메시지를 보여줄 수 있습니다. - 각 좌석은 담을 수 있습니다
sessionsPerSeat열려 있는 탭: 유료 플랜에서는 네 개, 체험판에서는 한 개입니다. 초과 탭은 그 사실을 알린 뒤 닫힙니다(코드 4429). 브리지는 모든 탭에 핑을 보내 90초 동안 침묵하는 탭을 끊어 버리므로, 잠자는 노트북 때문에 사라진 탭은 스스로 세션을 해제합니다. 사용자의 마지막 탭이 닫히면 실행 토큰은 2분 안에 만료됩니다. DELETE /manage/seats/{user}사용자의 토큰을 취소하고 세션을 모두 닫습니다. 누군가 앱에서 로그아웃하거나 접근 권한을 잃었을 때 호출합니다.- 사용자 ID는 전달하는 값 그대로입니다. 이메일 주소를 보내고 싶지 않다면 안정적이고 불투명한 ID(데이터베이스 키나 해시)를 사용하세요. 좌석을 점유하는 ID는 sqlly.app에 보고되어 브리지 여러 곳에서 좌석 수를 셉니다.
누가 연결할 수 있는지: Origin 규칙
각 라이선스는 하나의 도메인에 묶여 있습니다. 브리지는 브라우저 WebSocket의 Origin 헤더가 해당 도메인 또는 그 하위 도메인(깊이, 스킴, 포트 무관)이거나 localhost / 127.0.0.1 / [::1] 하는 동안 --allow-localhost-origins 이(가) 켜져 있습니다(개발 시 기본값). 도메인을 묶지 않은 라이선스는 localhost만 허용합니다. 도메인은 다음에서 묶을 수 있습니다 Embedded 관리 페이지, 또는 다음으로 브리지를 한 번 시작합니다 --domain.
관리 API는 CORS 헤더를 전혀 보내지 않습니다. 서버 간 통신용이므로 다른 오리진의 브라우저는 호출할 수 없으며, 어차피 루프백에 바인딩해야 합니다.
라이선스 적용 방식
브리지가 신뢰하는 것은 단 하나입니다: 라이선스 부여, sqlly.app이 ES384(ECDSA P-384)로 서명한 컴팩트 JWS입니다. 검증 키는 브리지에 컴파일되어 있습니다. 모든 허용 사항(좌석 수, 좌석당 세션 수, 브리지 인스턴스, 도메인, 기간 종료일, 유예일, 기능)은 권한 부여의 서명된 클레임에서 읽습니다. 그 주변의 서명되지 않은 JSON은 표시용일 뿐입니다.
연결된 라이선스
- 시작할 때와 20분마다 브리지는
POST /api/embedded/checkin라이선스 키, 인스턴스 ID, 새로 만든 32바이트 nonce, 버전과 호스트 이름, 시작될 때 지정한 도메인, 그리고 지금 좌석을 쓰고 있는 사용자 ID들과 함께 전송합니다. - 응답에 담긴 권한 부여(grant)는 컴파일 시 넣어 둔 키로 검증되고, 그 논스를 그대로 돌려 보내야 하며, 이 인스턴스와 같은 라이선스를 가리켜야 하고, 브리지 시계 기준 5분 안에 발급되어야 합니다. 재생되거나 위조된 응답은 이 검사에 걸리고 실패한 체크인으로 간주됩니다. 호스트 시계는 정확히 맞춰 두세요(NTP).
- 권한은 40분간 유효합니다. sqlly.app에 연결할 수 없으면 브리지는 마지막 유효 권한으로 계속 서비스하다가, 그 권한이 소진되면 이후 오래됨 그리고 다음 체크인이 성공할 때까지 작업을 거부합니다. 재시작은 필요하지 않습니다. 장애 도중에 재시작된 브리지는 해당 권한이 만료되지 않은 동안에만 캐시해 둔 권한으로 시작합니다.
- 연결된 각 라이선스는 동시에 일정 수의 브리지 인스턴스 한 번에 하나씩만(기본값 1개) 허용됩니다. 같은 키로 두 번째 브리지가 접속하면 기록은 되지만 첫 번째 브리지가 체크인을 이어가는 동안은 받아들이지 않습니다. 정상 종료한 브리지는 슬롯을 즉시 내놓고, 죽은 브리지는 40분 후에 내놓습니다.
오프라인 라이선스
오프라인 라이선스는 파일({ "format": "sqlly-embedded-license", "version": 1, "token": "<grant>" }) 도메인이 설정된 뒤 sqlly.app에서 내려받는 파일입니다. 안에 담긴 권한 부여는 오래 유효하며 기간 끝에 유예일을 더한 시점에 만료됩니다. 브리지는 로컬에서 검증하고 SQLly 서버와는 절대 통신하지 않으며, 파일을 매분 다시 읽으므로 갱신한다는 것은 파일을 교체한다는 뜻입니다. 오프라인 라이선스에는 인스턴스 상한이 없습니다.
연결된 설치
키도 없고 파일도 없이 시작한 브리지는 라이선스 없음: 관리 API는 동작하고(프로필을 만들고 테스트할 수 있음) 실행만 거부됩니다. 이후 관리 앱은 키가 노출되지 않은 채 설치를 연결합니다: sqlly.app에 링크 코드를 요청하면 라이선스 소유자가 브라우저에서 승인하고, 앱이 이 설치 전용으로 발급된 키를 받아 다음과 함께 브리지에 넘깁니다 PUT /manage/license브리지는 그것을 검증하고 저장하며 재시작 시에도 계속 사용합니다. 각 연결된 설치마다 자체 키가 있으므로 소유자는 다른 키를 건드리지 않고 하나를 취소할 수 있습니다. 구축 방법.
라이선스가 유효하지 않을 때
다음을 제외한 모든 상태에서 ok 그리고 grace, 브리지는 열린 소켓을 유지하되 각 요청 프레임에는 일반 문장이 담긴 실패로 응답합니다("…40분 동안 sqlly.app에서 라이선스를 확인하지 못했습니다; 관리자에게 확인을 요청하세요."). SQLly 클라이언트는 그 문장을 상태 줄과 알림으로 보여 주어 사용자가 이유를 알게 합니다. 새 세션에도 같은 문장을 알려 주고 닫으며(코드 4503), 시작 토큰은 다음으로 거부됩니다 503 license_not_ok거부됩니다. 기간이 끝난 뒤 15일간의 유예 기간에는 모든 기능이 동작하지만 모든 사용자에게 카운트다운이 보입니다. 모든 상태, 하나씩 설명.
서버에서 나가는 것
| 체크인 시 sqlly.app으로 전송됨 | 어디에도 전송되지 않음 |
|---|---|
| 라이선스 키 · 브리지 인스턴스 ID · 브리지 버전 · 호스트명 · 요청된 도메인 · 좌석을 가진 사용자 ID · 열린 세션 수 | 쿼리 · 결과 · 데이터베이스 이름과 호스트 · 자격 증명 · 프로필 · 사용자가 입력하는 모든 것 |
오프라인 라이선스는 아무것도 보내지 않습니다. 브라우저는 오직 앱과 브리지와만 통신합니다.