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

JobNo aplicativo de exemploNo seu aplicativo
Autentique os usuáriosSeu próprio arquivo de usuários com senhas em scrypt (lib/auth.js)Seu login existente, SSO, sessões
Decida quem vê quais conexõesCada usuário recebe um perfilSeus papéis, equipes, locatários ou planos escolhem o id do perfil
Definir conexõesEditor 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 SQLlyGET /app/ emite um token e o injeta em index.htmlUma rota que faz o mesmo (passo 4)
Servir o pacote web/app/* com cabeçalhos de isolamentoSeu servidor de arquivos estáticos ou caminho de CDN com os mesmos cabeçalhos (passo 5)
Assentos gratuitosPágina de usuários, Liberar assentoChame-o ao sair e quando o acesso for removido (passo 6)
Mostrar o estado da licençaPágina de statusUma verificação de saúde ou widget de administração (passo 7)
Vincular a uma licençaConecte-se ao sqlly.appOpcional: 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_profile com problems listando 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-PUT perfis 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_select em um ambiente de Produção, ou confirm_data_changes em 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:

javascript (estilo express)
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 ttlSeconds entre 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 open para 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.js resolve para a sua cópia de web/.

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-origin e Cross-Origin-Embedder-Policy: require-corp na página e em cada arquivo do pacote. O SQLly precisa de SharedArrayBuffer, que os navegadores só habilitam em páginas isoladas.
  • application/wasm como 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' em script-src, a origem da ponte wss:// em connect-src, and a nonce or hash on the inline globals script (or the query-parameter form above). Large results are kept in browser storage by spill-worker.js, a worker script, which nonces don't cover: allow it with 'self' em worker-src (or in script-src, que worker-src falls 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_limit em 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/seats lista 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:

  1. POST https://sqlly.app/api/embedded/links com um nome de exibição (por exemplo "SQLly Embedded on " + hostname). Mantenha o secret retornado do lado do servidor. Mostre ao administrador o code e envie-os para linkUrl.
  2. O administrador faz login no sqlly.app, verifica se o código corresponde, escolhe uma licença e aprova.
  3. Enquanto isso, faça a verificação periódica POST https://sqlly.app/api/embedded/links/token com { linkId, secret } cada pollIntervalSeconds. Ele responde 202 enquanto pendente, então 200 uma vez com licenseKey. 410 significa recomeçar (negado, expirado ou já usado).
  4. 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 mostra license.source: "linked". Não guarde a chave por conta própria.
  5. 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_limit e license_not_ok mostrar uma mensagem humana, não um stack trace.
  • Algo observa GET /manage/status.
  • Você leu Indo para produção.