クエリを指定して SQLly を開く

SQLly をクエリタブに直接起動します。スクリプト、その接続とデータベース、パラメーター値、カーソルが、「SQLly で開く」ボタン用の起動トークンとともに送信されます。

起動トークンは通常、空のワークベンチを開きます。次の open フィールドを付けて発行すると、SQLlyはその代わりに1つ以上のクエリタブで直接開きます:スクリプトが読み込まれ、タブは正しいサーバーとデータベースに接続され、パラメーターの値が入力され、カーソルは指定した位置に置かれます。これにより、アプリがSQLを表示するあらゆる場所に「SQLlyで開く」ボタンを置けます:レポートの横、失敗したクエリの横、監査証跡などです。

何も勝手には実行されません。 起動で読み込まれるのはタブだけです。ブラウザーを使う人が各クエリを確認して「実行」を押します。SQLly のデスクトップ版クエリリンクも同じルールです。起動によって SQL を実行させる方法はありません。

起動コンテキスト付きのトークンを発行

同じです POST /manage/tokens 他の起動と同じように呼び出せます(独自アプリ構築のステップ 4)に加えて、フィールドが 1 つ増えます:

シェル
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 が入り、キャレットは 3 行目にあります。

タブが引き継げるもの

open は 1 つのオブジェクト、または複数のタブ向けに最大 8 件のリストです。最初のものにフォーカスが移ります。各フィールドは省略可能ですが、エントリには少なくともスクリプトか接続が必要です。

フィールド型意味
connection文字列トークンのプロファイル内の接続を、名前(大文字小文字は区別しない)または ID で指定します。プロファイルに接続が 1 つしかない場合は省略してください。複数あって名前を指定しない場合、タブは接続なしで開きます。
database文字列接続の既定データベースの代わりに使うデータベース。最大 128 文字。
title文字列タブのタイトル。最大 120 文字です。指定しない場合、SQLly はいつもどおりタブに名前を付けます。
script文字列読み込む SQL(そのまま)。最大 256 KiB。Windows の改行コードは、次の値に折りたたまれます: \n.
parametersobjectスクリプトの @name パラメーターは最大 64 個。詳細は パラメーター.
cursor{ line, column }キャレットの位置です。行と列はどちらも 1 から数え、列は文字単位です。スクリプト内を指している必要があります(行末の 1 つ後ろの列も指定できます)。

パラメーター

SQLly には型付きクエリパラメーターがあります: -- sqlly param: @name <type> 行が 1 つ宣言し、結果の上のストリップにその値が入ります。起動パラメーターも同じストリップを使うため、値は目に見える編集可能な入力欄として現れ、ステートメント自体は送信したとおりそのまま読み込まれます。

  • 名前には @name、すべてのエンジンで。キーは、次の有無どちらでも送れます @ ("min_total" そして "@min_total" は同じです)。名前は文字または _ の後に、文字、数字、または _、最大 64 文字で、1 回だけ指定できます(大文字小文字は問いません)。アプリがパラメーターを別の方法で書く場合($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: スクリプトの上の行に置かれ、カーソルもスクリプトと一緒に下へ移動します。スクリプトがすでに宣言しているパラメーターは、スクリプト側の宣言と型を保持したまま、指定した値を受け取ります。
  • 値がデータベースに届く仕組み。 ユーザーが「実行」を押すと、SQLly は各値をその型に照らして確認し、それぞれを次に置き換えます @name 文字列やコメントの外にある部分を、そのエンジン向けに正しく書かれたリテラルに置き換えてから、ステートメントを送信します。型に合わない値は実行を止め、その入力欄にフォーカスします。アプリが値を SQL テキストに直接埋め込むことはありません。

1 回の起動に 1 つのトークン

  • タブは一度だけ開きます。 ブリッジは、それらをトークンを使う最初の SQLly セッションに渡し、その後は保持しません。ページを再読み込みすると、SQLly がブラウザーに保存しているワークベンチが復元されるため、タブが二重に開くことはありません。トークン自体は、期限が切れるまで引き続き有効です。
  • 「SQLlyで開く」をクリックするたびに、新しいトークンを発行します。 コンテキスト付きの起動には、キャッシュされたトークンを再利用しないでください。何も開かないためです。すでにシートを持っているユーザーに新しいトークンを発行しても、シートは消費されません。
  • クリックするたびに新しいタブが開きます。 これはユーザーの sessionsPerSeat (有料プランは 4 つ、トライアルは 1 つ)。トライアルでは、先に他の SQLly タブを閉じる必要があります。閉じないと、新しいタブは「<user> はすでに最大数の SQLly セッションを開いています」というメッセージで拒否されます。
  • コンテキストは、発行時に固定されます - プロファイルと同様です。接続は、その時点のプロファイルに対して解決されます。

ミスは発行時に検出されます

ブリッジは全体を確認します open 値をトークン作成前に検証するため、ユーザーが壊れたタブに遭遇する前に、サーバー側ですぐに問題が分かります。不正な値は 400 invalid_open に 1 件のエントリを持つ 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 で再度開く ボタンをすべての完全なステートメントに表示します。ブリッジで再度その行を検索し(フォームには行名のみが含まれます)、次のコンテキストで管理者起動を発行します:

javascript
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 駆動のページフレームワーク、定期ジョブなど)を実行している場合、ステートメントが失敗した時点で、それがどのステートメントで、どんな値がバインドされ、どのデータベースに対して実行されたかを把握しています。エラーページにボタンを設け、そのステートメント、パラメーターとしての値、データベースが指摘した行へのカーソル位置を指定した起動を発行できるようにします。開発者は何も手作業でコピーせずに、IntelliSense、オブジェクトエクスプローラー、実行プランを備えた本格的なワークベンチをそのクエリで手に入れます:

javascript
// 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,
  },
});

そのデータベースでワークベンチを使うべき人(開発環境の利用者や管理者など)にだけ、これを開放してください。到達できる範囲は、他の起動とまったく同じようにプロファイルが決めます。