Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

10.0 KB
Raw Blame

SQLite Runtime Resolution (Português (Portugal))

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW


O OmniRoute resolve o respetivo controlador SQLite no arranque através de uma cadeia de recurso com 5 passos:

  1. better-sqlite3 incluído (através de dependencies em package.json) — mais rápido, binário nativo, instalado por npm install quando estão presentes ferramentas de compilação.

  2. better-sqlite3 instalado em tempo de execução (em ~/.omniroute/runtime/) — instalado de forma diferida na primeira execução OU por scripts/build/postinstall.mjs → scripts/postinstall.mjs. Valida os bytes mágicos do ficheiro .node nativo (ELF / Mach-O / PE) antes do carregamento, para proteger contra binários corrompidos ou destinados à plataforma errada.

  3. node:sqlite (biblioteca padrão do Node ≥22.5) — não necessita de compilação nativa; utilizado quando ambos os caminhos de better-sqlite3 falham. Conjunto de funcionalidades limitado.

  4. sql.js (WASM) — último recurso. Funciona em qualquer ambiente, mas é mais lento e grava os dados periodicamente, em vez de o fazer de forma síncrona.

Porquê esta complexidade?

  • EBUSY no Windows: npm install -g omniroute@latest pode falhar se o better_sqlite3.node da versão anterior estiver bloqueado por um processo em execução. A instalação em tempo de execução em ~/.omniroute/runtime/ contorna a cache npm global.
  • Ausência de ferramentas de compilação: Alguns ambientes (Windows empresarial sem VS Build Tools, imagens Docker mínimas) não conseguem compilar o better-sqlite3. O instalador em tempo de execução obtém um binário pré-compilado do registo npm; os controladores alternativos garantem que o OmniRoute continua a arrancar mesmo que esse processo falhe.
  • Sistemas isolados da rede: Se o registo npm estiver inacessível, o node:sqlite ou o sql.js garantem a funcionalidade básica.

Validação de bytes mágicos

Antes de carregar um ficheiro .node instalado em tempo de execução, o OmniRoute lê os primeiros 8 bytes e compara-os com os bytes mágicos conhecidos das plataformas:

Plataforma Bytes (hex) Etiqueta
Linux 7F 45 4C 46 elf
macOS de 64 bits BE FE ED FA CF macho
macOS de 64 bits LE CF FA ED FE macho-le
macOS fat (universal) CA FE BA BE macho-fat
Windows 4D 5A (MZ) pe

Bytes mágicos incompatíveis → o ficheiro é ignorado e o processo de recurso prossegue para o passo seguinte.

Verificar o controlador ativo

import { getDriverInfo } from "@/lib/db/core";

const info = getDriverInfo();
// { source: "bundled" | "runtime" | "runtime-installed-now" | "node-sqlite" | "sql-js",
//   kind: "better-sqlite3" | "node-sqlite" | "sql-js" }

Controlo manual

# Ignorar a preparação pós-instalação (para instalações rápidas em CI)
OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute

# Forçar a reinstalação do better-sqlite3 em tempo de execução
rm -rf ~/.omniroute/runtime
omniroute  # será reinstalado no próximo arranque

# Verificar qual é o controlador ativo
omniroute config db-info  # (se o comando CLI existir)

Diagnosticar bloqueios síncronos

Com o better-sqlite3, defina OMNIROUTE_SQLITE_SLOW_MS=200 antes do arranque para ativar a medição de tempos do adaptador síncrono. Por predefinição, está desativada. Uma operação concluída que demore pelo menos esse número de milissegundos emite um aviso [SQLITE-SLOW], no máximo uma vez a cada dez segundos por adaptador. O aviso contém apenas o controlador, a classe da operação (prepare, get, all, run, exec, pragma, transação ou manutenção) e os milissegundos decorridos: não inclui SQL, parâmetros associados, linhas, caminhos ou texto de exceções.

Este é um auxiliar de diagnóstico, não um limite de tempo nem uma otimização de consultas. Não consegue comunicar uma operação que nunca devolva o controlo, distinguir processamento da CPU de esperas pelo disco, identificar o SQL exato ou observar operações efetuadas através do identificador bruto do controlador. A duração das cópias de segurança assíncronas é deliberadamente excluída; os outros controladores SQLite não são instrumentados por esta funcionalidade opcional. Desativar a variável repõe o adaptador original sem os wrappers de medição de tempo. Não existem alterações ao esquema da base de dados nem à configuração armazenada.

O aviso de atraso de /healthz comunica o pico do ciclo de eventos desde a amostra anterior, não a média de todo o período de execução. Correlacione os respetivos carimbos de data/hora com os avisos de operações lentas e com as métricas do sistema anfitrião/armazenamento antes de atribuir um bloqueio ao SQLite ou a uma falha do disco.

Referência

Implementação:

  • bin/cli/runtime/magicBytes.mjs — auxiliares de validação dos bytes mágicos de binários
  • bin/cli/runtime/sqliteRuntime.mjs — resolvedor em tempo de execução com 5 passos + instalador diferido
  • bin/cli/runtime/index.mjs — orquestrador de arranque (warmUpRuntimes())
  • scripts/postinstall.mjs — hook pós-instalação do npm (preparação não fatal)
  • src/lib/db/core.ts — exportações de ensureDbInitialized() / getDriverInfo()

Topologia de escritor único (HA não suportada)

A cadeia de controladores alternativos acima continua a ser executada num único processo. Por predefinição, o SQLite do OmniRoute tem um único escritor:

  • Não ligue duas réplicas do OmniRoute ao mesmo ficheiro storage.sqlite.
  • Um reinício do contentor, uma implementação Recreate, uma interrupção por OOM ou um reinício por HEALTHCHECK termina todas as sessões SSE em curso. Não existe qualquer drenagem de sessões no percurso padrão.
  • Uma verificação de atividade do orquestrador que interprete um /healthz lento como indisponível encerrará a única réplica. Prefira verificações de atividade por TCP + verificações de prontidão HTTP em /healthz. Consulte o Guia do Docker — disponibilidade e as recomendações de sondas do Kubernetes.