Crie seu próprio app
Passo a passo: dirija a ponte SQLly Embedded a partir do seu próprio aplicativo web - armazene perfis, crie tokens de lançamento, forneça a build para o navegador, libere assentos e vincule instalações.
O aplicativo de exemplo faz o papel do seu produto. Tudo o que ele faz passa pela ponte, API de gerenciamento, então qualquer stack do lado do servidor pode substituí-lo: Node, ASP.NET, Django, Rails, Go, PHP. Esta página percorre cada tarefa que o aplicativo de exemplo executa e como fazer isso no seu próprio aplicativo. Os exemplos estão em JavaScript (Node 20+) e C# (ASP.NET Core), e as mesmas chamadas funcionam em qualquer cliente que fale HTTP e JSON.
Gere um cliente em vez de escrever um à mão. swagger.json é uma descrição OpenAPI 3.0 de toda a API de gerenciamento. Passe para o openapi-generator, NSwag, Kiota ou para a sua ferramenta HTTP preferida. O sample-app/lib/bridge.js também é um cliente completo, escrito à mão, em cerca de 120 linhas.
O que seu aplicativo assume
| Job | No aplicativo de exemplo | No seu aplicativo |
|---|---|---|
| Autentique os usuários | Seu próprio arquivo de usuários com senhas em scrypt (lib/auth.js) | Seu login existente, SSO, sessões |
| Decida quem vê quais conexões | Cada usuário recebe um perfil | Seus papéis, equipes, locatários ou planos escolhem o id do perfil |
| Definir conexões | Editor de perfil, aba Rótulos (lib/credentials.js constrói o documento) | Sua interface de administração, um arquivo de configuração ou código que constrói documentos a partir dos dados do seu locatário |
| Abrir SQLly | GET /app/ emite um token e o injeta em index.html | Uma rota que faz o mesmo (passo 4) |
| Servir o pacote web | /app/* com cabeçalhos de isolamento | Seu servidor de arquivos estáticos ou caminho de CDN com os mesmos cabeçalhos (passo 5) |
| Assentos gratuitos | Página de usuários, Liberar assento | Chame-o ao sair e quando o acesso for removido (passo 6) |
| Mostrar o estado da licença | Página de status | Uma verificação de saúde ou widget de administração (passo 7) |
| Vincular a uma licença | Conecte-se ao sqlly.app | Opcional: ou configurar uma chave ou arquivo de licença (passo 8) |
1. Execute a ponte ao lado do seu aplicativo
Sem o script de inicialização, a ponte é um comando. Gere o token de gerenciamento uma vez e forneça o mesmo valor para a ponte e seu aplicativo (uma variável de ambiente ou armazenamento de segredos, nunca seu repositório):
export SQLLY_EMBEDDED_MANAGE_TOKEN="$(openssl rand -base64 24)"
export SQLLY_EMBEDDED_LICENSE_KEY=sqe_… # or SQLLY_EMBEDDED_LICENSE_FILE, or neither and link later
./bin/sqlly-bridge embedded \
--domain portal.example.com \
--public-url wss://portal.example.com/sqlly/proxy \
--manage-bind 127.0.0.1:8445 \
--state-dir /var/lib/sqlly-embedded
Seu aplicativo se comunica com http://127.0.0.1:8445 com Authorization: Bearer $SQLLY_EMBEDDED_MANAGE_TOKEN. Os navegadores alcançam o listener do proxy (:8444) através do seu proxy reverso. Detalhes da produção.
2. Um pequeno cliente de gerenciamento
javascript (node 20+)const BRIDGE = process.env.SQLLY_BRIDGE_URL ?? 'http://127.0.0.1:8445';
const TOKEN = process.env.SQLLY_EMBEDDED_MANAGE_TOKEN;
export async function bridge(method, path, body) {
const res = await fetch(BRIDGE + path, {
method,
headers: {
authorization: `Bearer ${TOKEN}`,
...(body ? { 'content-type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
if (res.status === 204) return null;
const json = await res.json().catch(() => null);
if (!res.ok) {
// Every error is { error, message } (+ problems for invalid documents).
throw Object.assign(new Error(json?.message ?? `bridge HTTP ${res.status}`),
{ code: json?.error, status: res.status, problems: json?.problems });
}
return json;
}
c# (asp.net core)
builder.Services.AddHttpClient("sqlly-bridge", c =>
{
c.BaseAddress = new Uri(builder.Configuration["Sqlly:BridgeUrl"] ?? "http://127.0.0.1:8445");
c.DefaultRequestHeaders.Authorization =
new("Bearer", builder.Configuration["Sqlly:ManageToken"]);
});
public sealed record BridgeError(string Error, string Message, string[]? Problems);
public sealed record MintedToken(string Token, DateTimeOffset ExpiresAt, string ProxyUrl,
string User, string Profile, int SeatsUsed, int Seats);
3. Salvar perfis
Um perfil é um Documento de credencial do SQLLY mais um nome de exibição. Construa-o da maneira que for mais conveniente: a partir de linhas no seu banco de dados, a partir de um modelo por locatário ou de um formulário de administrador. GET /manage/engines lista todos os ids de mecanismo, a porta padrão de cada um e quais tipos de login ele aceita, para que um formulário nunca os fixe no código.
await bridge('PUT', '/manage/profiles/acme-analysts', {
name: 'Acme analysts',
credentials: {
format: 'sqlly-credentials',
version: 1,
clients: [{ name: 'Acme', color: '#1E88E5' }],
environments: [{ name: 'Production', safety: { only_allow_select: true } }],
sql_auth_accounts: [{ name: 'Reader', username: 'acme_ro', password: secrets.acmeReader }],
connections: [
{ name: 'Orders', engine: 'postgres', server: 'pg1.internal', database: 'orders',
environment: 'production', client: 'Acme',
authentication: { type: 'sql-login', account: 'Reader' }, tls: { mode: 'verify-full' } },
],
},
});
- Os ids de perfil são de 1 a 64 de
A-Z a-z 0-9 _ -. Use a sua própria chave estável (um id de tenant, um nome de papel). - A ponte valida o documento inteiro antes de salvar. Um documento com erros retorna como
400 invalid_profilecomproblemslistando cada erro. Chaves desconhecidas são erros, então erros de digitação nunca passam. - A ponte é o registro oficial dos segredos. Mantenha a fonte da verdade onde quiser, mas re-
PUTperfis quando ele mudar. O aplicativo de exemplo reenvia todos os perfis ao iniciar, então um diretório de estado novo se repopula automaticamente. - Use rótulos e flags de segurança.
only_allow_selectem um ambiente de Produção, ouconfirm_data_changesem uma conexão, são aplicados pelo SQLly a qualquer pessoa que abrir esse perfil.
Antes de salvar, você pode testar que a conexão funciona com POST /manage/test-connection e um documento contendo apenas essa conexão. As falhas retornam como { "ok": false, "message": "<the engine's own error>" } com HTTP 200, pronto para mostrar ao lado do formulário.
4. Inicie o SQLly para um usuário conectado
Esta é a única rota de que toda integração precisa. Quando um usuário conectado abre o SQLly, gere um token para ele e retorne, do bundle, o index.html com dois globais definidos antes as boot.js tag do módulo:
import { readFile } from 'node:fs/promises';
const ISOLATION = {
'Cross-Origin-Opener-Policy': 'same-origin',
'Cross-Origin-Embedder-Policy': 'require-corp',
};
const BOOT_TAG = '<script type="module" src="./boot.js"></script>';
// JSON for an inline script: never let a value close the tag.
const js = (v) => JSON.stringify(v).replace(/</g, '\\u003c');
app.get('/sqlly/', requireSignIn, async (req, res) => {
const profile = profileFor(req.user); // your rule: role, team, tenant…
let minted;
try {
minted = await bridge('POST', '/manage/tokens', { user: req.user.id, profile });
} catch (err) {
if (err.code === 'seat_limit') return res.status(409).send('All SQLly seats are in use right now.');
if (err.code === 'license_not_ok') return res.status(503).send(err.message);
throw err;
}
const html = (await readFile('web/index.html', 'utf8')).replace(BOOT_TAG,
`<script>globalThis.SQLLY_PROXY_URL=${js(minted.proxyUrl)};` +
`globalThis.SQLLY_PROXY_TOKEN=${js(minted.token)};</script>` + BOOT_TAG);
res.set(ISOLATION).set('Cache-Control', 'no-store').type('html').send(html);
});
c# (api mínima asp.net core)
app.MapGet("/sqlly/", async (HttpContext http, IHttpClientFactory clients, IWebHostEnvironment env) =>
{
var user = http.User.FindFirst("sub")!.Value;
var bridge = clients.CreateClient("sqlly-bridge");
var reply = await bridge.PostAsJsonAsync("/manage/tokens", new { user, profile = ProfileFor(http.User) });
if (!reply.IsSuccessStatusCode)
{
var error = await reply.Content.ReadFromJsonAsync<BridgeError>();
return Results.Text(error?.Message ?? "SQLly is unavailable.", statusCode: (int)reply.StatusCode);
}
var minted = (await reply.Content.ReadFromJsonAsync<MintedToken>())!;
const string bootTag = "<script type=\"module\" src=\"./boot.js\"></script>";
// JsonSerializer escapes < > & by default, so the values can't close the tag.
var globals = $"<script>globalThis.SQLLY_PROXY_URL={JsonSerializer.Serialize(minted.ProxyUrl)};" +
$"globalThis.SQLLY_PROXY_TOKEN={JsonSerializer.Serialize(minted.Token)};</script>";
var html = (await File.ReadAllTextAsync(Path.Combine(env.ContentRootPath, "sqlly-web", "index.html")))
.Replace(bootTag, globals + bootTag);
http.Response.Headers["Cross-Origin-Opener-Policy"] = "same-origin";
http.Response.Headers["Cross-Origin-Embedder-Policy"] = "require-corp";
http.Response.Headers.CacheControl = "no-store";
return Results.Content(html, "text/html");
}).RequireAuthorization();
- Gere no servidor, por solicitação. Nunca coloque o token de gerenciamento em uma página. O token de lançamento é seguro para entregar ao usuário para quem foi emitido: ele abre o SQLly com esse perfil apenas para esse usuário e expira (10 minutos por padrão; passe
ttlSecondsentre 10 e 86.400). - Reutilizar é aceitável. Um token vale até expirar, então recarregar a página não exige um novo. O aplicativo de exemplo guarda em cache o token de cada usuário e emite um novo um minuto antes de expirar. Emitir de novo para o mesmo usuário nunca custa outro assento.
- Abra uma consulta, não apenas o ambiente de trabalho. Adicionar
openpara a chamada mint para levar o usuário direto a uma aba de consulta com script, conexão, valores de parâmetro e cursor já definidos. Crie um token novo para cada uma dessas inicializações: as abas abrem apenas na primeira sessão que o token iniciar. Abrir o SQLly em uma consulta. - O ID do usuário é seu. Passe um ID estável e opaco. Assentos contam IDs distintos, e os IDs que ocupam assentos são reportados ao sqlly.app no check-in.
- Se você não puder editar o HTML, passe
?proxy=<url>&token=<token>na URL da página em vez disso. Injetar é melhor, porque o token permanece fora do histórico e dos logs. - Sirva a página em uma URL terminando em
/(aqui/sqlly/) para que o./boot.jsresolve para a sua cópia deweb/.
5. Sirva o pacote web
Sirva os arquivos em web/ no mesmo caminho da página de inicialização (/sqlly/boot.js, /sqlly/sqlly_browser_bg.wasm, …), com:
Cross-Origin-Opener-Policy: same-origineCross-Origin-Embedder-Policy: require-corpna página e em cada arquivo do pacote. O SQLly precisa deSharedArrayBuffer, que os navegadores só habilitam em páginas isoladas.application/wasmcomo o tipo para.wasm. Aqui a compressão ajuda muito: com Brotli ou gzip, o arquivo wasm fica várias vezes menor.- Se suas páginas enviarem uma Content-Security-Policy:
'wasm-unsafe-eval'emscript-src, a origem da pontewss://emconnect-src, and a nonce or hash on the inline globals script (or the query-parameter form above). Large results are kept in browser storage byspill-worker.js, a worker script, which nonces don't cover: allow it with'self'emworker-src(or inscript-src, queworker-srcfalls back to). If it is blocked, large results stay in memory. - O isolamento entre origens se aplica a tudo que a página carrega, então sirva o pacote do seu próprio domínio em vez de um CDN de terceiros sem cabeçalhos CORP.
Os arquivos do pacote são versionados junto com o pacote. Quando você fizer upgrade, substitua web/ e a ponte juntos.
6. Gerencie assentos
409 seat_limitem mint significa que todos os assentos estão em uso. Informe o usuário de forma clara e, para administradores, ofereça a opção de liberar um.GET /manage/seatslista quem possui os assentos e desde quando.- Liberar ao sair:
DELETE /manage/seats/{user}revoga os tokens do usuário e fecha suas abas do SQLly. Faça o mesmo quando você remover o acesso de alguém. Caso contrário, o token continuará funcionando até expirar. - Uma aba extra além
sessionsPerSeaté recusado pelo próprio bridge: o socket recebe a mensagem «<user> já tem o número máximo de sessões SQLly abertas» e é fechado com o código 4429, e o SQLly mostra essa frase.
7. Mostrar status da licença
GET /manage/status tem tudo para um widget de administração ou uma verificação de integridade:
const s = await bridge('GET', '/manage/status');
// s.license.state: ok | grace | stale | not_admitted | expired | revoked | domain_mismatch | unlicensed
// s.license.message: the sentence your users see when something is wrong
// s.license.daysRemaining, s.license.planName, s.seatsUsed / s.license.seats
const healthy = ['ok', 'grace'].includes(s.license.state);
Alerta para qualquer coisa diferente de ok, e trate grace como «renovar esta semana». POST /manage/license/checkin força um check-in (ou relê um arquivo offline), o que é útil para um Fazer check-in agora botão depois de corrigir o acesso à rede. O que cada estado significa.
8. Inclua um link para a licença na sua interface de administração (opcional)
Você pode configurar a ponte com uma chave ou arquivo de licença e pular isso. O vínculo é para produtos que instalam o SQLly Embedded para muitos clientes: o administrador de cada cliente conecta sua instalação ao próprio licença do sqlly.app com alguns cliques, e nenhuma chave é jamais copiada. Inicie a ponte sem --license-key nem --license-file, então:
POST https://sqlly.app/api/embedded/linkscom um nome de exibição (por exemplo"SQLly Embedded on " + hostname). Mantenha osecretretornado do lado do servidor. Mostre ao administrador ocodee envie-os paralinkUrl.- O administrador faz login no sqlly.app, verifica se o código corresponde, escolhe uma licença e aprova.
- Enquanto isso, faça a verificação periódica
POST https://sqlly.app/api/embedded/links/tokencom{ linkId, secret }cadapollIntervalSeconds. Ele responde202enquanto pendente, então200uma vez comlicenseKey.410significa recomeçar (negado, expirado ou já usado). - Entregue a chave diretamente à ponte:
PUT /manage/license { "licenseKey": "…" }. A ponte a verifica com sqlly.app antes de armazená-la, mantém-a durante reinicializações, e o status mostralicense.source: "linked". Não guarde a chave por conta própria. - Para desconectar,
DELETE /manage/license: a ponte libera seu slot, revoga a chave no sqlly.app e volta a estar sem licença.
O lib/sqllyapp.js e suas /admin/link implementam exatamente isso.
Antes de lançar
- O token de gerenciamento fica na configuração do lado do servidor e a API de gerenciamento está vinculada ao loopback ou a uma rede privada.
- Cada inicialização é emitida no servidor para um usuário autenticado, com um perfil escolhido pelas suas regras de autorização.
- A página e o bundle do SQLly carregam os cabeçalhos de isolamento, e o seu CSP permite a origem
wss://origem. - O logout e a remoção de acesso liberam o assento do usuário.
seat_limitelicense_not_okmostrar uma mensagem humana, não um stack trace.- Algo observa
GET /manage/status. - Você leu Indo para produção.