Abrir o SQLly em uma consulta

Inicie o SQLly direto em uma aba de consulta: o script, sua conexão e banco de dados, os valores de parâmetro e o cursor, enviados com o token de inicialização dos botões «Abrir no SQLly».

Um token de lançamento normalmente abre um workbench vazio. Adicione um open campo quando você o emite, e o SQLly abre direto em uma ou mais abas de consulta: o script carregado, a aba conectada ao servidor e banco de dados corretos, seus valores de parâmetro preenchidos, o cursor onde você o deixou. Isso dá a você botões «Abrir no SQLly» em qualquer lugar em que seu app mostre SQL: ao lado de um relatório, em uma consulta com falha, em uma trilha de auditoria.

Nada é executado sozinho. Um lançamento só carrega abas. Quem está no navegador revisa cada consulta e pressiona Executar, a mesma regra que os links de consulta do SQLly desktop seguem. Não há como fazer um lançamento executar SQL.

Emitir um token com contexto de inicialização

É o mesmo POST /manage/tokens chame como qualquer launch (passo 4 para criar seu próprio aplicativo), com um campo extra:

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 }
  }
}'

A resposta é o token usual mais openTabs, o número de abas que a sessão abrirá:

{ "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 }

Entregue o token à página exatamente como em uma abertura normal. Quando o usuário chega, o SQLly se conecta ao Shop, muda para sales, e mostra uma aba chamada «Grandes pedidos» com a consulta carregada, a barra de parâmetros com 500 e 2026-10-01 e o cursor na terceira linha.

O que uma aba pode carregar

open é um objeto, ou uma lista de até 8 para várias abas. O primeiro recebe o foco. Cada campo é opcional, mas uma entrada precisa de pelo menos um script ou uma conexão.

CampoTipoSignificado
connectionstringUma conexão do perfil do token, pelo nome (maiúsculas e minúsculas tanto faz) ou pelo id. Omita quando o perfil tiver só uma conexão. Com várias e nenhuma nomeada, a aba abre sem conexão.
databasestringO banco de dados para o qual mudar, em vez do padrão da conexão. No máximo 128 caracteres.
titlestringO título da aba. No máximo 120 caracteres. Sem ele, o SQLly nomeia a aba como sempre.
scriptstringO SQL a carregar, exatamente como está. No máximo 256 KiB. As quebras de linha do Windows são convertidas para \n.
parametersobjectValores para os @name parâmetros do script, no máximo 64. Veja parâmetros.
cursor{ line, column }Para onde vai o cursor, ambos contados a partir de 1, a coluna em caracteres. Deve apontar dentro do script (uma coluna além do final de uma linha é permitida).

Parâmetros

O SQLly tem parâmetros de consulta tipados: uma -- sqlly param: @name <type> linha declara um, e uma faixa acima dos resultados mantém seu valor. Os parâmetros de execução usam essa mesma faixa, então seus valores aparecem como entradas visíveis e editáveis e as próprias instruções são carregadas exatamente como você as enviou.

  • Nomes usam @name, em todos os mecanismos. Envie a chave com ou sem o @ ("min_total" e "@min_total" são iguais). Um nome é uma letra ou _ seguido de letras, dígitos ou _, no máximo 64 caracteres, e pode aparecer apenas uma vez (em qualquer capitalização). Se o seu aplicativo escrever parâmetros de outra forma ($name, :name, ?), reescreva-os para @name ao criar o script.
  • Um valor simples pega seu tipo do JSON: um número inteiro é int, qualquer outro número decimal, true/false bool, uma string text, e null deixa a entrada vazia para o usuário preencher.
  • Um valor tipado é { "type": "date", "value": "2026-10-01" }. Os tipos são text, int, decimal, bool, date, datetime, time, uuid, json e binary. Envie documentos JSON como strings com "type": "json".
  • Declarações são adicionadas para você. Para cada parâmetro que o script não declara, o SQLly adiciona um -- sqlly param: linha acima do script, e o cursor se move para baixo junto com o script. Um parâmetro que o script já declara mantém a declaração e o tipo do script, e recebe seu valor.
  • Como os valores chegam ao banco de dados. Quando o usuário pressiona Executar, o SQLly verifica cada valor em relação ao seu tipo e substitui cada @name fora de strings e comentários por um literal escrito corretamente para aquele mecanismo e envia a instrução. Um valor que não cabe no tipo dele interrompe a execução e foca o campo em questão. Seu aplicativo nunca emenda valores no texto SQL.

Uma inicialização, um token

  • As abas abrem uma vez. A ponte os entrega para a primeira sessão SQLly que usa o token e então os esquece. Recarregar a página restaura o workbench, que o SQLly salva no navegador, então as abas não são abertas duas vezes. O próprio token ainda funciona até expirar.
  • Emita um token novo para cada clique em «Abrir no SQLly». Não reutilize um token em cache em uma inicialização com contexto: ele não abriria nada. Um novo token para um usuário que já tem uma vaga não consome uma vaga.
  • Cada clique é uma nova aba. Isso conta para o sessionsPerSeat (quatro nos planos pagos, um no teste). No teste, o usuário precisa fechar primeiro a outra aba do SQLly, ou a nova é recusada com «<user> já tem o número máximo de sessões SQLly abertas».
  • O contexto é fixo no momento da cunhagem - como o perfil. As conexões são resolvidas com base no perfil como ele estiver naquele momento.

Erros são capturados no momento da emissão

A ponte verifica o valor inteiro open antes de criar o token, então seu servidor descobre na hora, em vez de um usuário encontrar uma aba quebrada. Um valor inválido é 400 invalid_open com uma entrada em problems por erro, cada uma indicando onde está. Nenhum token é emitido e nenhum assento é ocupado:

{
  "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)"
  ]
}

Campos desconhecidos são recusados em vez de ignorados, então um erro de digitação como sql para script falha de forma evidente. Valores do tipo int, decimal e bool também são verificados. Outros tipos são verificados pela barra de parâmetros do SQLly antes de a consulta ser executada.

Receitas

Reabrir uma consulta do registro de auditoria

O registro de auditoria de consultas registra cada consulta com seu perfil, conexão, banco de dados e SQL, que é tudo o que uma inicialização precisa. A página Consultas do aplicativo de exemplo tem um Reabrir no SQLly botão em cada instrução completa. Ele consulta a linha na ponte novamente (o formulário nomeia a linha e nada mais), e então emite um launch de administrador com este contexto:

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 });

O SQL registrado é o que realmente foi executado, então os valores dos parâmetros já estão nele como literais e nenhum parâmetro é necessário. Para uma instrução que falhou, o aplicativo de exemplo também lê onde o motor diz que falhou (do PostgreSQL POSITION: 53, do MySQL «na linha 2») e envia isso como o cursor, de modo que o cursor fique na coluna problemática.

«Abrir no SQLly» na página de erro do seu aplicativo

Se seu aplicativo executa SQL próprio (um gerador de relatórios, um framework de páginas baseado em SQL, tarefas agendadas), ele sabe no momento em que uma instrução falha qual era a instrução, os valores vinculados a ela e em qual banco de dados ela rodou. Coloque um botão na página de erro que cria um lançamento com aquela instrução, seus valores como parâmetros e o cursor na linha em que o banco de dados reclamou. O desenvolvedor recebe um workbench completo para aquela consulta, com IntelliSense, o explorador de objetos e planos de execução, sem copiar nada à mão:

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

Ofereça isso apenas a quem deve ter um ambiente de trabalho naquele banco de dados, por exemplo em desenvolvimento ou para administradores. O perfil decide o que a pessoa pode acessar, exatamente como em qualquer outro lançamento.