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.

Baixe o swagger.json OpenAPI 3.0 versão 1.0.0 base http://127.0.0.1:8445

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. /healthz e os endpoints de ligação do sqlly.app não precisam de nenhum.
  • Erros são { "error": "<code>", "message": "<sentence>" }. Decida com base em error; mostrar message. Documentos de credenciais inválidos adicionam problems, 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_large assim 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%2Fb libera o usuário a/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

Saúde

Verificação de atividade, sem necessidade de token.

GET /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.

GET /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"
}
POST /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_unreachable ou grant_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"
}
PUT /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-key ou --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"
}
DELETE /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-key ou --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.

GET /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.

GET /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"
}
GET /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 de A-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"
}
PUT /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 (com problems: problemas de parser, ou cada motor baseado em arquivos enquanto --allow-file-engines está desligado), ou invalid_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"
}
DELETE /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 de A-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.

POST /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-engines está desligado), ou invalid_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; problems lista cada erro com seu caminho, por exemplo open[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 é ok ou grace (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"
}
GET /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"
}
DELETE /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.

POST /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-engines está desligado (veja problems).
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.

GET /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: limit não é um número inteiro, since nã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.

GET /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.

CampoTipoDescriçã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

CampoTipoDescriçã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.

CampoTipoDescriçã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

CampoTipoDescrição
licenseKey * string Uma chave começando sqe_.

EngineInfo

CampoTipoDescriçã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

CampoTipoDescrição
id string
name string
connections integer Número de conexões no documento.
updatedAt string (date-time)

StoredProfile

CampoTipoDescrição
id string
name string
credentials CredentialDocument
updatedAt string (date-time)

PutProfileRequest

CampoTipoDescriçã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).

CampoTipoDescrição
format * sqlly-credentials
version * 1
clients Label[]
projects Label[]
environments Label[]
sql_auth_accounts SharedLogin[]
tunnel_profiles object[]
connections Connection[]

Rótulo

CampoTipoDescriçã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

CampoTipoDescrição
name * string
username * string
password string

Conexão

CampoTipoDescriçã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

CampoTipoDescriçã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

CampoTipoDescriçã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.

CampoTipoDescriçã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

CampoTipoDescriçã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.

CampoTipoDescrição
line integer
column integer

MintedToken

CampoTipoDescriçã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

CampoTipoDescrição
seats integer
seatsUsed integer
users UserSeat[]

AssentoDoUsuário

CampoTipoDescrição
user string
activeSessions integer
tokens integer Tokens de inicialização não expirados.
since string (date-time)

TestConnectionRequest

CampoTipoDescrição
credentials * CredentialDocument

TestOutcome

CampoTipoDescriçã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.

CampoTipoDescriçã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

CampoTipoDescriçã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

CampoTipoDescrição
name string Exibido ao proprietário na página de aprovação e em sua página incorporada.
hostname string
appVersion string

CreateLinkResponse

CampoTipoDescriçã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

CampoTipoDescrição
linkId * string
secret * string

LinkPending

CampoTipoDescrição
status pending
expiresAt string (date-time)

LinkApproved

CampoTipoDescriçã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