Referência da API
Todos os endpoints da API de gerenciamento da ponte SQLly Embedded, gerados a partir do seu documento OpenAPI (swagger.json), além dos endpoints de vinculação sqlly.app.
A ponte SQLly em modo incorporado expõe esta API em seu listener de gerenciamento (--manage-bind, padrão 127.0.0.1:8445). Seu aplicativo web o chama do lado do servidor para guardar perfis de conexão, testar conexões, gerar tokens de inicialização para usuários conectados, acompanhar assentos e ler ou alterar o estado da licença.
Cada /manage/... de que a chamada precisa Authorization: Bearer <manage token> (da ponte) --manage-token, pelo menos 16 caracteres). Os corpos são JSON na entrada e na saída, com no máximo 8 MB (recusados com 413 too_large assim que o limite for ultrapassado). Segmentos de caminho e valores de query-string têm a codificação percentual decodificada; um escape inválido é 400 bad_request. Os erros são sempre { "error": "<code>", "message": "<sentence>" }, além de problems quando um documento de credencial é inválido. A API não envia cabeçalhos CORS: mantenha-a em loopback ou em uma rede privada e nunca a exponha a navegadores, porque os perfis contêm senhas de banco de dados.
O Linking operações não estão na ponte: são endpoints públicos do sqlly.app que um aplicativo de administração usa para vincular uma instalação a uma licença sem copiar uma chave. O servidor deles é sqlly.app.
Guia: sqlly.app/docs/embedded
Convenções
- Autenticação:
Authorization: Bearer <manage token>em cada/manage/…chamada. Um token ausente ou incorreto é401 unauthorized./healthze os endpoints de ligação do sqlly.app não precisam de nenhum. - Erros são
{ "error": "<code>", "message": "<sentence>" }. Decida com base emerror; mostrarmessage. Documentos de credenciais inválidos adicionamproblems, uma string por erro. - Corpos são JSON, com no máximo 8 MB. O limite é aplicado enquanto o corpo chega: a ponte responde
413 too_largeassim que ele é passado e nunca armazena mais nada. Um corpo que demora mais de 30 segundos para chegar é408 timeout. O que não dá para analisar é400 bad_json, e uma rota desconhecida é404 not_found. - Segmentos de caminho e valores de consulta são decodificados em percent-encoding, então codifique IDs de usuário e timestamps para URL (
DELETE /manage/seats/a%2Fblibera o usuárioa/b). Uma sequência de escape inválida ou um resultado que não seja UTF-8 é400 bad_request. - Nomes de campos são camelCase nos próprios payloads da API. Dentro de um documento de credencial eles seguem o formato de credencial (
sql_auth_accounts,trust_server_certificate).
Endpoints
- GET
/healthz - GET
/manage/status - POST
/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} - POST
/manage/tokens - GET
/manage/seats - DELETE
/manage/seats/{user} - POST
/manage/test-connection - GET
/manage/queries - POST
/api/embedded/links - POST
/api/embedded/links/token - GET
/api/embedded/public-key
Saúde
Verificação de atividade, sem necessidade de token.
/healthz
nenhum token
Sonda de atividade
Responde assim que o listener de gerenciamento estiver ativo. Não precisa de token; use-o a partir de scripts de inicialização e verificações de integridade do serviço.
- 200
- A API de gerenciamento está em escuta.
Exemplo de resposta 200
{
"ok": true
}
Licença
A licença sob a qual o bridge opera: estado, check-in, vinculação e desvinculação.
/manage/status
Status da ponte e da licença
Tudo o que uma tela de administração precisa: o estado da licença e de onde ela veio, as cotas que a concessão assinada traz, assentos em uso, sessões abertas e a URL do proxy que os navegadores usam.
- 200
- Status atual.
- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.
Exemplo de resposta 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
}
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license/checkin
Faça check-in com sqlly.app agora
Licenças conectadas e vinculadas: executa um check-in imediatamente em vez de esperar pelo ciclo de 20 minutos. Licenças offline: relê o arquivo de licença e nunca acessa a rede. De qualquer forma, a resposta é o status após a tentativa; uma falha mantém o estado inalterado.
- 200
- Status após o check-in.
- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.- 409
not_linked: a ponte não possui licença, não há nada para registrar.- 422
license_file_invalid(offline): o arquivo está ausente, danificado ou assinado para outra chave.- 502
store_unreachableougrant_invalid: não foi possível alcançar o sqlly.app, ou a resposta dele não passou na verificação.
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Exemplo de resposta 409
{
"error": "not_linked",
"message": "this bridge is not linked to a license yet"
}
/manage/license
Instalar chave de licença vinculada
Dá a uma ponte que foi iniciada sem --license-key / --license-file sua chave em tempo de execução (normalmente a chave que seu aplicativo de administração acabou de coletar do sqlly.app pelo fluxo de vinculação). A ponte primeiro faz o check-in com ela e a armazena (<state-dir>/license-key, modo 0600) somente se o sqlly.app responder com uma concessão verificada; a partir daí, ela funciona como uma ponte conectada, e a chave é reutilizada após reinicializações. Nada muda em caso de falha: a chave em uso continua servindo até que a nova seja verificada. Substituir uma chave vinculada por uma de outra licença libera o slot de instância da licença antiga após a nova chave ser verificada; uma chave regenerada da mesma licença reutiliza a linha de instância do armazenamento.
Corpo da solicitação (LinkLicenseRequest)
{
"licenseKey": "sqe_2xH7c0VqHk9LmZr1aPq4tN8bW6yD3sJfUe5o"
}
- 200
- Vinculado. O status agora mostra
license.source: linked. - 400
invalid_license_key: chave vazia, malformada, desconhecida ou revogada.- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.- 409
license_from_flag: a ponte foi iniciada com--license-keyou--license-file, pois a licença dele não é gerenciada por esta API.- 502
store_unreachable: não foi possível alcançar o sqlly.app ou a resposta dele não passou na verificação.
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license
Desvincular esta instalação
Libera o slot da instância desta ponte, revoga sua chave em sqlly.app (melhor esforço), exclui a chave armazenada, fecha todas as sessões abertas e retorna a ponte para unlicensed.
- 204
- Desvinculada.
- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.- 404
not_linked: nenhuma chave vinculada é armazenada.- 409
license_from_flag: a ponte foi iniciada com--license-keyou--license-file, pois a licença dele não é gerenciada por esta API.
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Mecanismos
Os mecanismos de banco de dados que o formato de credencial aceita, para que sua interface nunca fixe a lista no código.
/manage/engines
Mecanismos que o formato de credencial aceita
Todos os mecanismos de banco de dados que o SQLly suporta, com o engine id para escrever em um documento de credenciais, sua porta padrão, se server é um caminho de arquivo, e os authentication.type valores que ele aceita.
- 200
- Os mecanismos.
- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.
Exemplo de resposta 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"
]
}
]
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Perfis
Um perfil é um documento nomeado de credenciais do SQLly: as conexões (e rótulos) que um grupo de usuários vê. A ponte é o armazenamento oficial; segredos nunca chegam ao navegador.
/manage/profiles
Listar perfis
Todo perfil salvo, sem as credenciais.
- 200
- Os perfis.
- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.
Exemplo de resposta 200
[
{
"id": "analysts",
"name": "Analysts",
"connections": 2,
"updatedAt": "2026-10-14T15:02:11Z"
}
]
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
Ler um perfil
O perfil com o documento de credenciais completo, segredos incluídos: o chamador é o seu aplicativo confiável do lado do servidor.
- id
- caminho · string correspondente a ^[A-Za-z0-9_-]{1,64}$ · obrigatório - Seu ID para o perfil.
- 200
- O perfil.
- 400
invalid_profile_id: os IDs são de 1 a 64 deA-Z a-z 0-9 _ -.- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.- 404
unknown_profile: nenhum perfil possui esse ID.
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Exemplo de resposta 404
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
/manage/profiles/{id}
Criar ou substituir um perfil
Armazena o perfil em id (criar ou substituir). O documento de credencial é validado completamente antes de qualquer gravação: todo problema que o analisador encontrar retorna em problems, e um documento inválido não altera nada. Um documento que contém um mecanismo baseado em arquivo (SQLite, DuckDB) é recusado da mesma forma, a menos que a ponte seja executada com --allow-file-engines true, porque tal conexão dá aos seus usuários acesso a arquivos no host da ponte. Sessões já abertas mantêm o catálogo com que começaram; as edições valem a partir do próximo início.
- id
- caminho · string correspondente a ^[A-Za-z0-9_-]{1,64}$ · obrigatório - Seu ID para o perfil.
Corpo da solicitação (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
- Armazenado.
- 400
invalid_profile(comproblems: problemas de parser, ou cada motor baseado em arquivos enquanto--allow-file-enginesestá desligado), ouinvalid_profile_id.- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.- 500
storage: o diretório de estado não pôde ser escrito.
Exemplo de resposta 400
{
"error": "invalid_profile",
"message": "the credential document has 2 problems",
"problems": [
"connections[0].engine: unknown engine \"postgress\"",
"connections[1].authentication.pasword: unknown key"
]
}
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
Excluir um perfil
Remove o perfil. Sessões abertas mantêm o catálogo com o qual começaram; novos tokens de lançamento para ele são recusados com unknown_profile.
- id
- caminho · string correspondente a ^[A-Za-z0-9_-]{1,64}$ · obrigatório - Seu ID para o perfil.
- 204
- Excluído.
- 400
invalid_profile_id: os IDs são de 1 a 64 deA-Z a-z 0-9 _ -.- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.- 404
unknown_profile: nenhum perfil possui esse ID.
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Exemplo de resposta 404
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
Inicialização
Tokens de inicialização abrem o SQLly para um usuário com um perfil. Assentos são usuários simultâneos.
/manage/tokens
Emitir um token de inicialização
Cria um token de curta duração que abre o SQLly para user com profile, opcionalmente direto nas abas de consulta (open, o contexto de lançamento). Coloque o proxyUrl e token na página que carrega o SQLly (globalThis.SQLLY_PROXY_URL / globalThis.SQLLY_PROXY_TOKEN). O token pode ser reutilizado até expirar (recarregamento da página), e o perfil é capturado no momento da emissão.
Um usuário ocupa um assento enquanto tiver uma sessão aberta ou um token não expirado. Emitir um novo para quem já ocupa um assento nunca falha por causa da contagem de assentos; emitir para um usuário novo falha com seat_limit quando todos os assentos da licença estão em uso, contando usuários em cada ponte da licença.
Corpo da solicitação (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
- O token.
- 400
invalid_user(vazio ou contém espaços em branco, no máximo 128 caracteres),invalid_profile(o perfil armazenado não é mais válido, ou possui um mecanismo baseado em arquivo enquanto--allow-file-enginesestá desligado), ouinvalid_open(o contexto de inicialização nomeia uma conexão desconhecida, um campo ou tipo desconhecido, um nome ou valor de parâmetro incorreto, um cursor fora do intervalo, ou passa um limite;problemslista cada erro com seu caminho, por exemploopen[1].cursor: …).- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.- 404
unknown_profile: nenhum perfil possui esse ID.- 409
seat_limit: cada assento está em uso. Libere um (DELETE /manage/seats/{user}) ou compre um plano maior.- 503
license_not_ok: a licença não éokougrace(inválido, expirado, revogado, não admitido, domínio incompatível ou sem licença). A mensagem diz qual.
Exemplo de resposta 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
}
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats
Assentos em uso
Usuários que ocupam um assento nesta ponte, com suas sessões abertas e tokens ativos. seatsUsed também inclui os usuários que o sqlly.app reportou em outras pontes da mesma licença.
- 200
- Uso de assentos.
- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.
Exemplo de resposta 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"
}
]
}
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats/{user}
Liberar o assento de um usuário
Revoga os tokens do usuário e fecha as sessões dele, liberando a vaga de imediato. Chame-o quando um usuário sair do seu aplicativo ou perder o acesso. Liberar um usuário que não ocupa nenhuma vaga não é um erro. O segmento do caminho vem decodificado em percent-encoding: a%2Fb libera o usuário a/b.
- usuário
- caminho · string · obrigatório - O ID do usuário para o qual você emitiu tokens (codificado em URL).
- 204
- Liberado.
- 400
bad_request: o segmento não é uma codificação percentual válida.- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Conexões
Prove que uma conexão funciona antes de qualquer pessoa usá-la.
/manage/test-connection
Testar uma conexão
Executa um mecanismo descartável contra um documento de credencial que contém exatamente uma conexão e executa uma consulta trivial. Falhas de conexão são relatadas como ok: false com a própria mensagem do mecanismo (HTTP 200); apenas um documento inutilizável é um erro HTTP.
Corpo da solicitação (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
- O resultado, sucesso ou não.
- 400
invalid_profile: o documento é inválido, não contém exatamente uma conexão ou contém um motor baseado em arquivos enquanto--allow-file-enginesestá desligado (vejaproblems).- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.
Exemplo de resposta 200
{
"ok": true,
"elapsedMs": 212,
"message": "Connected: SQL Server 17.0"
}
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Auditoria
O rastreamento de auditoria de consultas: cada consulta e edição de linha realizada em uma sessão, quem a executou, contra qual conexão, e como terminou. Mantido em memória e em <state-dir>/queries.jsonl (texto SQL incluído) a menos que a ponte opere com --query-log false.
/manage/queries
Trilha de auditoria de consultas
Toda consulta e edição de linha que as sessões da ponte executaram, da mais recente para a mais antiga: o usuário e o perfil do token de inicialização, a conexão indicada no token (nome, servidor, mecanismo, banco de dados), o texto SQL (limitado a 64 KiB, veja sqlTruncated), quando começou, seu status e duração, e o erro do mecanismo quando falhou. Solicitações ainda em execução são listadas com status running; uma solicitação recusada porque a licença não estava em ordem é failed com a mensagem de licença; qualquer coisa que estava em execução quando uma sessão foi encerrada é cancelled com erro session closed.
A ponte mantém as entradas mais recentes --query-log-max-entries (20.000 por padrão) na memória e em <state-dir>/queries.jsonl, então o registro sobrevive a uma reinicialização. Com --query-log false nada é registrado e a resposta é { "enabled": false, "queries": [] }.
- limite
- query · integer - Entradas a retornar, limitado de 1 a 1000.
- usuário
- query · string - Apenas este ID de usuário (correspondência exata, codificado na URL).
- perfil
- query · string - Apenas este ID de perfil (correspondência exata).
- desde
- query · string (date-time) - Apenas entradas cuja
até igual ou posterior a este carimbo de data/hora RFC 3339 (codificado na URL). - status
- query · QueryStatus - Apenas entradas neste status.
- 200
- As entradas correspondentes, da mais nova para a mais antiga.
- 400
bad_request:limitnão é um número inteiro,sincenão é RFC 3339,statusé desconhecido, ou um valor não é codificação percentual válida.- 401
unauthorized: o token de gerenciamento está ausente ou incorreto.
Exemplo de resposta 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'."
}
]
}
Exemplo de resposta 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Vinculação
endpoints do sqlly.app (servidor sqlly.app) para vincular uma instalação a uma licença: crie um código, o proprietário aprova no navegador dele, colete uma única vez a chave da própria instalação e entregue-a à ponte com PUT /manage/license.
/api/embedded/links
sqlly.app
nenhum token
Comece a vincular uma instalação (sqlly.app)
Anônimo. Cria uma solicitação de vínculo e retorna um código curto, um segredo que só o seu app conhece e a URL em que o proprietário da licença aprova. Mostre o código e abra linkUrl para o proprietário, então faça polling POST /api/embedded/links/token cada pollIntervalSeconds até a aprovação. Os links expiram após 15 minutos.
Corpo da solicitação (CreateLinkRequest)
{
"name": "SQLly Embedded on portal-01",
"hostname": "portal-01",
"appVersion": "1.4.0"
}
- 201
- Link criado.
- 429
- Limite de requisições atingido.
- 503
link_unavailable: nenhum código pôde ser alocado; tente novamente.
Exemplo de resposta 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
nenhum token
Consultar a chave vinculada (sqlly.app)
Anônimo; o segredo do link é a credencial. Enquanto o proprietário não decide, responde 202 pending. Depois de aprovado, cunha a chave de licença desta instalação e a devolve exatamente uma vez (o link é consumido). Entregue a chave direto ao bridge com PUT /manage/license; não a armazene você mesmo.
Corpo da solicitação (LinkTokenRequest)
- 200
- Aprovado: a chave, uma vez.
- 202
- Ainda aguardando o proprietário.
- 401
wrong_secret.- 404
unknown_link.- 410
link_used,link_denied,link_expiredoulicense_revoked: este link nunca pode ser concluído. Inicie um novo.- 429
- Limite de requisições atingido.
/api/embedded/public-key
sqlly.app
nenhum token
Chave pública de assinatura de licença (sqlly.app)
A chave pública PEM que sqlly.app usa para assinar concessões de licença, para que um operador possa compará-la com a chave compilada na ponte.
- 200
- Texto PEM.
- 503
signing_not_configured.
Esquemas
Os objetos acima, conforme definidos em swagger.json. Uma ? depois de um tipo significa que pode ser null.
Erro
Toda resposta de erro. error é um código de máquina estável; message é uma frase que você pode mostrar a um administrador.
| Campo | Tipo | Descrição |
|---|---|---|
error * |
string |
|
message * |
string |
|
problems |
string[] |
Presente para invalid_profile: todo problema que o analisador de credenciais encontrou. |
LicenseState
ok e grace serve consultas; qualquer outro estado recusa o trabalho com uma mensagem que o SQLly mostra aos seus usuários.
Um de: ok grace stale not_admitted expired revoked domain_mismatch unlicensed
StatusReport
| Campo | Tipo | Descrição |
|---|---|---|
version |
string |
Versão da ponte. |
instanceId |
string |
ID deste processo da ponte, como o sqlly.app o vê. |
mode |
connected | offline |
|
license |
LicenseReport |
|
seatsUsed |
integer |
Assentos em uso em todas as pontes da licença. |
activeSessions |
integer |
Sessões SQLly abertas nesta ponte. |
proxyUrl |
string |
A URL do WebSocket que os navegadores usam (--public-url). |
allowLocalhostOrigins |
boolean |
|
storeUrl |
string |
|
allowFileEngines |
boolean |
Se os perfis podem conter mecanismos baseados em arquivos (--allow-file-engines). |
LicenseReport
As permissões vêm da concessão assinada, nunca de dados não assinados.
| Campo | Tipo | Descrição |
|---|---|---|
state |
LicenseState |
|
source |
flag | file | linked | none |
flag: --license-key; file: --license-file; linked: armazenado por PUT /manage/license; none: sem licença. |
licenseId |
string? |
|
plan |
string? |
ID do plano, ou custom para uma licença emitida com seus próprios termos. |
planName |
string? |
|
status |
string? |
o status do sqlly.app no último check-in: active, grace, expired, revoked, domain_mismatch. |
seats |
integer |
Usuários simultâneos permitidos pela licença. |
sessionsPerSeat |
integer |
Abas do SQLly que um usuário pode manter abertas. |
instances |
integer |
Pontes que podem rodar de uma vez (licenças conectadas; 0 offline). |
domain |
string? |
O domínio vinculado; os navegadores devem vir dele ou de um subdomínio. |
periodEnd |
string? |
Fim do período pago (ISO 8601). |
graceEnd |
string? |
Definido durante o período de carência: quando a ponte para de responder. |
daysRemaining |
integer? |
Dias inteiros até o bridge parar de atender. |
lastCheckinAt |
string (date-time)? |
|
staleAt |
string (date-time)? |
Quando o bridge fica obsoleto se nenhum check-in for bem-sucedido (última concessão válida + 40 minutos). |
licenseFile |
string? |
Offline: o arquivo de licença em uso. |
message |
string? |
A frase que os usuários veem quando algo está errado (também as contagens regressivas do período de carência). |
fromCache |
boolean |
Verdadeiro quando a bridge começou a partir da concessão em cache porque o sqlly.app estava inacessível. |
features |
string[] |
LinkLicenseRequest
| Campo | Tipo | Descrição |
|---|---|---|
licenseKey * |
string |
Uma chave começando sqe_. |
EngineInfo
| Campo | Tipo | Descrição |
|---|---|---|
id |
string |
O engine valor para um documento de credencial. |
name |
string |
|
defaultPort |
integer |
|
fileBased |
boolean |
server é um caminho de arquivo e nenhum login se aplica. |
authentication |
string[] |
Aceito authentication.type valores. |
ProfileSummary
| Campo | Tipo | Descrição |
|---|---|---|
id |
string |
|
name |
string |
|
connections |
integer |
Número de conexões no documento. |
updatedAt |
string (date-time) |
StoredProfile
| Campo | Tipo | Descrição |
|---|---|---|
id |
string |
|
name |
string |
|
credentials |
CredentialDocument |
|
updatedAt |
string (date-time) |
PutProfileRequest
| Campo | Tipo | Descrição |
|---|---|---|
name * |
string |
Nome para exibição, mostrado aos usuários no SQLly. |
credentials * |
CredentialDocument |
Documento de Credencial
Um documento de credenciais SQLly (no mesmo formato de Arquivo → Importar Conexões do SQLly). Chaves desconhecidas são erros, então erros de digitação são relatados em vez de ignorados. Referência completa: sqlly.app/docs (Formato de arquivo de credenciais).
| Campo | Tipo | Descrição |
|---|---|---|
format * |
sqlly-credentials |
|
version * |
1 |
|
clients |
Label[] |
|
projects |
Label[] |
|
environments |
Label[] |
|
sql_auth_accounts |
SharedLogin[] |
|
tunnel_profiles |
object[] |
|
connections |
Connection[] |
Rótulo
| Campo | Tipo | Descrição |
|---|---|---|
name * |
string |
|
color |
string |
#RGB, #RRGGBB ou #RRGGBBAA. |
image |
string |
Ícone como data: URI ou base64 puro (PNG, JPEG, GIF, WebP, BMP, ICO, SVG; até 1 MB). |
safety |
object |
Apenas as flags que você listar mudam. |
SharedLogin
| Campo | Tipo | Descrição |
|---|---|---|
name * |
string |
|
username * |
string |
|
password |
string |
Conexão
| Campo | Tipo | Descrição |
|---|---|---|
name * |
string |
|
engine * |
string |
Um id de GET /manage/engines. |
server * |
string |
Host, IP, host\instance, ou um caminho de arquivo para SQLite/DuckDB. |
port |
integer |
|
database |
string |
|
environment |
string |
local, dev, test, staging, production ou indefinido. |
client |
string |
O nome de um rótulo de cliente. |
project |
string |
Um nome de rótulo de projeto. |
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 |
Proxy inline, ssh e saltos do kube. |
masking |
object |
{ include: [...], exclude: [...] } Regras de mascaramento de colunas. |
Autenticação
| Campo | Tipo | Descrição |
|---|---|---|
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 |
Nome de um login compartilhado em sql_auth_accounts. |
region |
string |
|
profile |
string |
|
token |
string |
MintTokenRequest
| Campo | Tipo | Descrição |
|---|---|---|
user * |
string |
O ID estável do usuário (sem espaços). Os assentos são contados por usuário distinto. |
profile * |
string |
Um ID de perfil. |
ttlSeconds |
integer |
Tempo de vida do token; o padrão é --token-ttl-seconds (600) e é limitado a 10 s - 24 h. |
open |
LaunchTab | LaunchTab[] |
Contexto de inicialização: uma aba de consulta, ou até 8, que o SQLly abre quando a sessão começa. A primeira sessão que o token admite as recebe; recarregamentos e sessões posteriores não. Validado contra o perfil no momento da emissão (400 invalid_open). Nada é executado até que o usuário pressione Executar. Guia: sqlly.app/docs/embedded/launch-context |
LaunchTab
Uma aba de consulta de um lançamento. Precisa de um script, um connection, ou ambos.
| Campo | Tipo | Descrição |
|---|---|---|
connection |
string |
Uma conexão no perfil do token, pelo nome (não diferencia maiúsculas de minúsculas, deve ser única) ou id. Opcional quando o perfil tem uma única conexão; com várias e nenhuma nomeada, a aba abre sem vínculo. |
database |
string |
Banco de dados para o qual alternar em vez do padrão da conexão. |
title |
string |
O título da aba. |
script |
string |
O SQL a carregar, exatamente como está (no máximo 256 KiB; CRLF é convertido para LF). |
parameters |
object |
Valores para os @name parâmetros, chaveados pelo nome (com ou sem @). O tipo de um valor simples é inferido (número inteiro int, outro número decimal, booleano bool, texto text, nulo empty); use { type, value } para escolher. Parâmetros que o script não declara recebem uma -- sqlly param: linha; os valores aparecem na faixa de parâmetros do SQLly e nunca são inseridos pelo seu aplicativo. |
cursor |
LaunchCursor |
LaunchParameterValue
| Campo | Tipo | Descrição |
|---|---|---|
type |
text | int | decimal | bool | date | datetime | time | uuid | json | binary |
|
value |
string | number | boolean |
LaunchCursor
Posição do cursor em script, iniciando em 1; a coluna conta os caracteres e pode estar um além do final da linha.
| Campo | Tipo | Descrição |
|---|---|---|
line |
integer |
|
column |
integer |
MintedToken
| Campo | Tipo | Descrição |
|---|---|---|
token |
string |
|
expiresAt |
string (date-time) |
|
proxyUrl |
string |
|
user |
string |
|
profile |
string |
|
seatsUsed |
integer |
Assentos em uso incluindo este usuário. |
seats |
integer |
|
openTabs |
integer |
Quantas abas a sessão vai abrir (0 sem contexto de inicialização). |
SeatsReport
| Campo | Tipo | Descrição |
|---|---|---|
seats |
integer |
|
seatsUsed |
integer |
|
users |
UserSeat[] |
AssentoDoUsuário
| Campo | Tipo | Descrição |
|---|---|---|
user |
string |
|
activeSessions |
integer |
|
tokens |
integer |
Tokens de inicialização não expirados. |
since |
string (date-time) |
TestConnectionRequest
| Campo | Tipo | Descrição |
|---|---|---|
credentials * |
CredentialDocument |
TestOutcome
| Campo | Tipo | Descrição |
|---|---|---|
ok |
boolean |
|
elapsedMs |
integer |
|
message |
string |
A própria mensagem do mecanismo, sucesso ou falha. |
QueryStatus
running até que o motor responda; então completed, failed (veja error) ou cancelled (pelo usuário, ou session closed).
Um de: running completed failed cancelled
QueryEntry
Uma solicitação auditada.
| Campo | Tipo | Descrição |
|---|---|---|
id |
string |
O id da solicitação do mecanismo, exclusivo dentro da própria sessão. |
sessionId |
integer |
O id da ponte para a sessão do navegador. |
kind |
query | row-edit |
|
at |
string (date-time) |
Quando a solicitação alcançou a ponte. |
user |
string |
O id do usuário do token de lançamento. |
profile |
string |
O id do perfil do token de lançamento. |
profileName |
string |
|
connection |
string |
O nome da conexão no perfil. |
server |
string |
|
database |
string? |
O banco de dados do perfil quando ele fixa um, senão o banco de dados nomeado na requisição. |
engine |
string |
O nome de exibição do mecanismo. |
sql |
string |
O texto SQL, ou row edit: <op> para uma edição de linha. Limitado a 64 KiB. |
sqlTruncated |
boolean |
|
status |
QueryStatus |
|
durationMs |
integer? |
Nulo enquanto estiver em execução. |
error |
string? |
O erro do mecanismo para failed; session closed para uma requisição interrompida pelo término da sessão. |
QueryListing
| Campo | Tipo | Descrição |
|---|---|---|
enabled |
boolean |
Falso quando a ponte roda com --query-log false; então queries está sempre vazio. |
queries |
QueryEntry[] |
Do mais novo para o mais antigo. |
total |
integer |
Entradas que correspondem aos filtros antes de limit foi aplicado. |
limit |
integer |
O tamanho de página aplicado (1-1000). |
CreateLinkRequest
| Campo | Tipo | Descrição |
|---|---|---|
name |
string |
Exibido ao proprietário na página de aprovação e em sua página incorporada. |
hostname |
string |
|
appVersion |
string |
CreateLinkResponse
| Campo | Tipo | Descrição |
|---|---|---|
linkId |
string |
|
code |
string |
Mostre isso ao proprietário para que ele possa verificar se corresponde. |
secret |
string |
Manter no lado do servidor; ele coleta a chave. |
linkUrl |
string |
Abra isso para o proprietário aprovar. |
expiresAt |
string (date-time) |
|
pollIntervalSeconds |
integer |
LinkTokenRequest
| Campo | Tipo | Descrição |
|---|---|---|
linkId * |
string |
|
secret * |
string |
LinkPending
| Campo | Tipo | Descrição |
|---|---|---|
status |
pending |
|
expiresAt |
string (date-time) |
LinkApproved
| Campo | Tipo | Descrição |
|---|---|---|
status |
approved |
|
licenseKey |
string |
Retornado exatamente uma vez. Passe-o para o PUT /manage/license. |
keyId |
string |
|
licenseId |
string |
|
plan |
string |
ID do plano, ou custom. |
planName |
string |
|
accountEmail |
string |
* obrigatório