쿼리와 함께 SQLly 열기

SQLly를 바로 쿼리 탭으로 실행하세요: 스크립트, 연결 및 데이터베이스, 매개변수 값과 커서를 'SQLly에서 열기' 버튼용 실행 토큰과 함께 전송합니다.

실행 토큰은 보통 빈 워크벤치를 엽니다. 여기에 open 필드를 넣으면 SQLly가 곧바로 하나 이상의 쿼리 탭으로 열립니다: 스크립트가 로드되고, 탭은 알맞은 서버와 데이터베이스에 연결되고, 매개변수 값이 채워지고, 커서는 지정한 위치에 놓입니다. 이러면 앱에 SQL이 보이는 어디에든 "SQLly에서 열기" 버튼을 달 수 있습니다: 보고서 옆에, 실패한 쿼리 옆에, 감사 기록에.

아무 것도 자동으로 실행되지 않습니다. 실행 링크는 탭을 불러올 뿐입니다. 브라우저 속 사람이 각 쿼리를 검토하고 실행을 누릅니다. SQLly 데스크톱 쿼리 링크와 같은 규칙입니다. 실행 링크로 SQL을 강제로 돌릴 방법은 없습니다.

실행 컨텍스트를 담아 토큰 발급

이는 일반 실행 때와 동일한 POST /manage/tokens 호출이며 어떤 실행과도 같습니다(직접 앱 만들기의 4단계), 필드가 하나 추가됩니다:

shell
curl -s -X POST -H "Authorization: Bearer $SQLLY_EMBEDDED_MANAGE_TOKEN" \
  -H 'content-type: application/json' http://127.0.0.1:8445/manage/tokens -d '{
  "user": "dana.analyst",
  "profile": "analysts",
  "open": {
    "connection": "Shop",
    "database": "sales",
    "title": "Big orders",
    "script": "SELECT *\nFROM orders\nWHERE total > @min_total AND placed_at >= @since",
    "parameters": { "min_total": 500, "since": { "type": "date", "value": "2026-10-01" } },
    "cursor": { "line": 3, "column": 7 }
  }
}'

응답은 평소 토큰에 더해 openTabs, 세션에서 열리는 탭 수:

{ "token": "…", "expiresAt": "2026-10-18T15:12:11Z", "proxyUrl": "wss://portal.example.com/sqlly/proxy",
  "user": "dana.analyst", "profile": "analysts", "seatsUsed": 3, "seats": 25, "openTabs": 1 }

토큰은 일반 실행 때와 똑같이 페이지에 전달합니다. 사용자가 도착하면 SQLly가 Shop에 연결하고, sales, 그리고 "Big orders"라는 탭을 열어 쿼리를 불러오고, 매개변수 스트립에는 500과 2026-10-01이 담기고, 캐럿은 세 번째 줄에 놓입니다.

탭이 담을 수 있는 것

open 객체 하나이거나, 여러 탭이라면 최대 8개의 목록입니다. 첫 번째 것이 포커스를 받습니다. 모든 필드는 선택 사항이지만, 항목이 되려면 최소한 스크립트나 연결이 필요합니다.

필드타입의미
connection문자열토큰의 프로필에 있는 연결로, 이름(대소문자 구분 없음)이나 ID로 지정합니다. 프로필에 하나의 연결만 있을 경우 생략하세요. 여러 개 있고 이름이 없는 경우, 탭은 연결 없이 열립니다.
database문자열연결 기본값 대신 전환할 데이터베이스입니다. 최대 128자입니다.
title문자열탭의 제목입니다. 최대 120자입니다. 없으면 SQLly가 평소처럼 탭 이름을 지정합니다.
script문자열불러올 SQL 원문. 최대 256 KiB. Windows 줄바꿈은 다음으로 변환됩니다: \n.
parametersobject스크립트의 @name 매개변수, 최대 64개입니다. 자세한 내용은 다음을 보세요 매개변수.
cursor{ line, column }캐럿이 들어가는 위치는 모두 1부터 계산한 열 단위입니다. 반드시 스크립트 내부를 가리켜야 합니다(줄 끝을 한 칸 넘는 열은 허용됩니다).

매개변수

SQLly는 타입이 지정된 쿼리 매개변수를 지원합니다: -- sqlly param: @name <type> 줄이 매개변수 하나를 선언하고, 결과 위의 파라미터 스트립에 그 값이 담깁니다. 실행 매개변수도 같은 스트립을 쓰므로 값이 눈에 보이는 편집 가능한 입력으로 표시되며, 문 자체는 전송한 그대로 로드됩니다.

  • 이름은 @name, 어느 엔진에서든 작동합니다. 키는 다음을 붙여도 되고 @ ("min_total" 그리고 "@min_total" 동일합니다). 이름은 문자 또는 _ 그 뒤에는 문자, 숫자 또는 _, 최대 64자까지 가능하며, 한 번만 나타날 수 있습니다(대소문자 구분 없음). 앱이 다른 방식으로 매개변수를 작성하면 ($name, :name, ?), 다음과 같이 다시 씁니다 @name 스크립트를 만들 때 채워집니다.
  • 일반 값 유형은 JSON에서 정합니다: 정수는 int, 다른 수는 decimal, true/false bool, 문자열 text, 그리고 null 입력란을 비워 두어 사용자가 직접 채우게 합니다.
  • 타입이 지정된 값 입니다 { "type": "date", "value": "2026-10-01" }. 유형은 text, int, decimal, bool, date, datetime, time, uuid, json 그리고 binary입니다. JSON 문서는 "type": "json".
  • 선언은 자동으로 추가됩니다. 스크립트에 선언되지 않은 매개변수마다 SQLly는 다음을 추가합니다: -- sqlly param: 줄 위에 적고, 커서는 스크립트와 함께 아래로 이동합니다. 스크립트가 이미 선언한 매개변수는 스크립트의 선언과 타입을 유지하며 입력한 값을 받습니다.
  • 값이 데이터베이스에 도달하는 방법. 사용자가 실행(Run)을 누르면 SQLly는 각 값을 타입과 대조해 확인하고 각 @name 를 문자열과 주석 밖에서 해당 엔진에 맞게 올바로 쓴 리터럴로 바꾼 뒤 문을 전송합니다. 타입에 맞지 않는 값은 실행을 멈추고 해당 입력으로 초점을 옮깁니다. 앱이 SQL 텍스트에 값을 직접 끼워 넣는 일은 없습니다.

실행 한 번, 토큰 한 개

  • 탭은 한 번만 열립니다. 브리지는 이 토큰을 쓰는 첫 번째 SQLly 세션에 이것들을 넘긴 뒤 잊어버립니다. 페이지를 다시 로드하면 SQLly가 브라우저에 저장해 둔 워크벤치가 복원되므로 탭이 두 번 열리지 않습니다. 토큰 자체는 만료될 때까지 계속 쓸 수 있습니다.
  • "SQLly에서 열기"를 클릭할 때마다 새 토큰을 발급합니다. 컨텍스트가 있는 실행에는 캐시된 토큰을 재사용하지 마세요. 아무것도 열리지 않습니다. 이미 좌석을 보유한 사용자에게 발급하는 새 토큰은 좌석을 소모하지 않습니다.
  • 각 클릭은 새 탭입니다. 클릭 한 번이 사용자별 세션 한도에 포함됩니다 sessionsPerSeat (유료 플랜에서는 4개, 체험판에서는 1개). 체험판에서는 사용자가 다른 SQLly 탭을 먼저 닫아야 하며, 그렇지 않으면 새 탭이 "<user>이(가) 이미 SQLly 세션을 최대 개수만큼 열었습니다" 메시지와 함께 거부됩니다.
  • 컨텍스트는 발행 시점에 고정됩니다 - 프로필도 마찬가지입니다. 연결은 그 시점의 프로필을 기준으로 해석됩니다.

실수는 토큰 발급 시점에 잡힙니다

브리지가 검사하는 것은 전체 open 토큰을 만들기 전에 값을 검증하므로, 사용자가 깨진 탭을 발견하는 대신 서버가 바로 알아차립니다. 잘못된 값은 400 invalid_open 다음에 항목 하나로 problems 실수마다 하나씩 들어가고 각각 어디가 문제인지 알려 줍니다. 토큰이 발급되지도, 좌석이 차지되지도 않습니다:

{
  "error": "invalid_open",
  "message": "the launch context has 3 problems",
  "problems": [
    "open[0].connection: no connection \"Shopp\" in this profile (it has: Shop, Warehouse)",
    "open[0]: unknown field \"sql\" (allowed: connection, database, title, script, parameters, cursor)",
    "open[1].cursor: line 9 is past the end of the script (3 lines)"
  ]
}

알 수 없는 필드는 무시하지 않고 거부하므로, 다음과 같은 오타도 sql 대하여 script 로 쓰면 명확하게 실패합니다. 다음 타입의 값도 int, decimal 그리고 bool 도 검사합니다. 다른 유형은 쿼리 실행 전에 SQLly의 매개변수 스트립이 검사합니다.

레시피

감사 추적에서 쿼리 다시 열기

그 쿼리 감사 추적 는 쿼리마다 프로필, 연결, 데이터베이스, SQL을 함께 기록하는데, 이것만 있으면 재실행에 필요한 정보가 모두 있습니다. 샘플 앱의 Queries 페이지에는 SQLly에서 다시 열기 버튼이 완성된 모든 문장마다 붙어 있습니다. 이 버튼은 브리지에서 해당 행을 다시 조회한 뒤(폼에는 행 이름 외에 아무것도 담기지 않음), 이 컨텍스트로 관리자 실행을 만들어 냅니다:

자바스크립트
const entry = (await bridge('GET', '/manage/queries?limit=1000')).queries
  .find((q) => String(q.sessionId) === form.session && q.id === form.id);
if (!entry || entry.kind === 'row-edit' || entry.sqlTruncated) return refuse();

const open = {
  connection: entry.connection,
  title: `${entry.status === 'failed' ? 'Failed' : 'Query'} from ${entry.user}`,
  script: entry.sql,
};
if (entry.database) open.database = entry.database;
const minted = await bridge('POST', '/manage/tokens', { user: `admin:${admin.id}`, profile: entry.profile, open });

기록된 SQL은 실제로 실행된 내용이므로 매개변수 값이 이미 리터럴로 들어 있고 매개변수는 필요하지 않습니다. 실패한 구문이라면 샘플 앱이 엔진이 가리키는 실패 위치까지 읽습니다(PostgreSQL의 POSITION: 53, MySQL의 "at line 2")를 읽어 그 내용을 다음으로 보냅니다 cursor로 보내므로 캐럿이 문제의 열에 놓입니다.

앱의 오류 페이지에서 "SQLly에서 열기"

앱이 자체 SQL을 실행한다면(리포트 빌더, SQL 기반 페이지 프레임워크, 예약 작업 같은), 문이 실패한 순간 어떤 문이었는지, 바인딩된 값이 무엇인지, 어느 데이터베이스에서 실행됐는지를 앱이 이미 알고 있습니다. 오류 페이지에 버튼을 하나 넣으세요. 그 버튼은 그 문을, 그 값들은 매개변수로, 커서는 데이터베이스가 문제 삼은 줄에 놓아 SQLly를 실행합니다. 개발자는 그 쿼리를 손으로 복사할 필요 없이 IntelliSense와 객체 탐색기, 실행 계획을 갖춘 온전한 작업대로 들어갑니다:

자바스크립트
// failure = { sql: 'SELECT … WHERE id = $id', params: { id: 42 }, line: 3 }
const script = failure.sql.replace(/\$([A-Za-z_]\w*)/g, '@$1');   // $id → @id
const minted = await bridge('POST', '/manage/tokens', {
  user: req.user.id,
  profile: 'app-database',            // a profile pointing at the app's own database
  open: {
    title: 'Failed statement',
    script,
    parameters: failure.params,
    cursor: failure.line ? { line: failure.line, column: 1 } : undefined,
  },
});

이 기능은 해당 데이터베이스에서 워크벤치를 써야 하는 사람에게만 제공하세요. 예를 들면 개발 환경이나 관리자입니다. 접근할 수 있는 범위는 프로필이 결정하며, 다른 실행과 마찬가지로 그대로 적용됩니다.