Configurações e dados do app
O DuckLocal guarda um arquivo de banco de dados em disco, mais um arquivo pequeno enquanto a janela está aberta, e um arquivo de log. Se você ativar o mapa base on-line, ele também guarda tiles de mapa em cache; uma atualização baixada também espera no cache. Todo o resto fica na memória durante a sessão. Os comentários de revisão dos painéis são uma exceção: eles são guardados ao lado do arquivo do painel, não no diretório de dados do app (veja Revisar com comentários).
Onde as coisas ficam guardadas
| Plataforma | Caminho |
|---|---|
| macOS | ~/Library/Application Support/DuckLocal/history.duckdb |
| Windows | %APPDATA%\DuckLocal\data\history.duckdb |
| Linux | ~/.local/share/ducklocal/history.duckdb |
O arquivo DuckDB contém quatro tabelas: histórico de consultas, arquivos de dados registrados, bancos de dados anexados junto ao banco aberto, e uma pequena tabela de configurações chave/valor. As configurações incluem o idioma e o tamanho da interface, as abas de consulta e de painel abertas, a lista de painéis recentes, e se o mapa base e a verificação de atualizações estão ativados. Enquanto o app roda, um arquivo .wal companheiro (o log de escrita antecipada do DuckDB) fica ao lado dele.
Seus conjuntos de dados nunca são copiados para o banco de dados do aplicativo. Os arquivos registrados são guardados como caminhos de arquivo e anexados de novo automaticamente sempre que o DuckLocal é iniciado.
Ao lado dele, enquanto uma janela está aberta, gui-endpoint.json guarda a porta de loopback e o token aleatório que o ducklocal open usa para alcançar a janela. Só a sua conta consegue lê-lo, e um gui-endpoint.json antigo deixado por uma janela que já fechou é inofensivo.
A pasta logs ao lado dele guarda o log da janela, ducklocal.log (e o da execução anterior, ducklocal.previous.log). Se o DuckLocal travar, ele escreve ali primeiro um relatório crash-….log, e a próxima execução conta o que aconteceu, com Mostrar relatório. Os dez últimos relatórios são mantidos. Anexe o relatório quando você abrir uma issue. Abrir pasta de logs abre a pasta: ela está no menu DuckLocal no macOS, e no menu de contexto da versão na extremidade direita da barra de status em todas as plataformas. O comando ducklocal não escreve nenhum arquivo de log; seus erros vão para quem o chamou.
Os tiles de mapa do mapa base on-line vão para a pasta de cache da plataforma — ~/Library/Caches/DuckLocal/tiles no macOS, %LOCALAPPDATA%\DuckLocal\cache\tiles no Windows, ~/.cache/ducklocal/tiles no Linux — uma pasta por servidor de tiles. Apagá-la é inofensivo: os tiles são simplesmente baixados de novo. Uma atualização baixada espera em updates na mesma pasta de cache até ser instalada.
O que sobrevive a um reinício
| Lembrado | Onde |
|---|---|
| Arquivos de dados registrados — caminho, nome da visão, tipo | arquivo de dados do app |
| Histórico de consultas, incluindo as que falharam | arquivo de dados do app |
| Idioma da interface | arquivo de dados do app |
| Tamanho da interface | arquivo de dados do app |
| Se o guia de primeira execução já foi visto | arquivo de dados do app |
| Se a barra lateral está oculta | arquivo de dados do app |
| Bancos de dados anexados junto ao aberto, e se cada um é somente leitura | arquivo de dados do app |
| O arquivo de banco de dados aberto por último | arquivo de dados do app — reaberto na inicialização enquanto ainda existir |
| Abas de consulta abertas, com seus títulos e SQL | arquivo de dados do app |
| Abas de painel abertas, com seus títulos | arquivo de dados do app |
| Se o mapa base on-line está ativado | arquivo de dados do app |
| Se o DuckLocal verifica atualizações na inicialização | arquivo de dados do app |
| Painéis abertos recentemente (os Painéis da barra lateral) | arquivo de dados do app |
| Não lembrado | Notas |
|---|---|
| O conteúdo do painel de resultados | apenas na memória — execute a consulta de novo |
| Tabelas e visões criadas no banco de dados em memória | o app pede que você as salve ao sair ou ao abrir outro banco de dados; Salvar como banco de dados… grava tudo em um arquivo .duckdb |
| Um arquivo de banco de dados que desde então foi movido ou apagado | a próxima execução começa em memória |
| Tamanho e posição da janela | fixos em 1440×900, mínimo de 960×600 |
| Tamanhos da barra lateral e do painel de resultados | fixos por execução |
| O filtro de resultados | apenas na memória |
| O que os filtros de um painel selecionaram | apenas na memória; mantido ao recarregar a aba |
| O tema | sempre começa no claro — veja abaixo |
| Credenciais de S3 | somente da sessão, por design |
O tema é o caso à parte: o seletor de idioma persiste, o de tema não, e toda execução começa no modo claro.
Uma execução comum trabalha em memória, então as tabelas e visões que você criar ali terminariam junto com a janela. O DuckLocal pergunta antes que isso aconteça: ao sair, ao fechar a janela ou ao abrir outro banco de dados com essas tabelas no lugar, ele oferece Salvar como banco de dados…, Sair sem salvar ou Cancelar. Salvar como banco de dados… (também ⌘⇧S, ou Arquivo → Salvar como banco de dados…) copia esquemas, tabelas e linhas, visões, macros e sequências para um arquivo .duckdb e move a janela para ele, de modo que as mudanças seguintes sejam gravadas no arquivo; a próxima execução abre esse arquivo de novo. As visões que o DuckLocal cria a partir de arquivos registrados não contam — elas são criadas de novo a partir dos arquivos em cada execução.
Rede
O DuckLocal não faz nenhuma requisição de rede por conta própria até você ativar alguma. Há dois interruptores, ambos desativados no começo, além das coisas que você pede diretamente:
| Requisição | Quando | O que sai da máquina |
|---|---|---|
| Mapa base on-line | Depois de ativado, sempre que um mapa é desenhado | Quais tiles são desejados: aproximadamente a área e o zoom que estão sendo vistos |
| Verificação de atualizações | Ao clicar na versão, ou na inicialização depois de ativada | Uma requisição a dl.ducklocal.app pela versão da última release; quando há uma mais nova, o download do pacote dela |
| S3 | Ao configurar o S3 e consultá-lo | Suas requisições ao armazenamento que você configurou |
| Extensões | Ao clicar em Instalar ou Atualizar, ou ao executar INSTALL | Um download do repositório de extensões do DuckDB |
| Dados remotos em SQL | Quando o SQL nomeia https://, s3:// ou um banco de dados remoto, incluindo o SQL de um painel quando ele abre. Exige a extensão já instalada | O que o SQL pede, incluindo qualquer coisa escrita no endereço |
Não há telemetria e, exceto pelo SQL que você executa, nada disso envia uma linha dos seus dados. O SQL faz o que diz: um endereço pode levar valores das suas tabelas. Então, depois que httpfs estiver instalado, um arquivo .dash de alguém em quem você não confia pode enviar dados quando você o abrir. Rede e privacidade lista todos os caminhos e como você mesmo pode verificá-los.
Mapa base on-line
Gráficos de mapa — em um painel ou na aba Gráfico dos resultados — podem desenhar tiles do OpenStreetMap sob seus pontos. Exibir → Mapa base on-line (OpenStreetMap) ativa e desativa isso, e a escolha é lembrada (a configuração map_tiles, on ou off). Ele começa desativado. Apenas os tiles pedidos saem da máquina — aproximadamente a área e o zoom que você está vendo — nunca uma linha de dados.
A busca segue a política de tiles da OpenStreetMap Foundation: um User-Agent identificável, no máximo duas requisições por vez, tiles reaproveitados do cache por uma semana, sem pré-busca em massa, e a atribuição no mapa. Para uso mais intenso, defina map_tile_url na tabela de configurações com o modelo de URL {z}/{x}/{y} de outro servidor.
Verificação de atualizações
A barra de status termina com a versão do DuckLocal — DuckLocal 0.3.0. Clique nela para verificar em dl.ducklocal.app qual é a última release:
- Atualizado — a versão que você executa é a mais recente.
- Baixando v0.3.1… — há uma release mais nova, e o DuckLocal está baixando. O pacote é conferido contra o tamanho publicado e o SHA-256 da release — no macOS, também contra a assinatura do app que você está executando — antes de ser descompactado.
- Reinicie para atualizar para v0.3.1 — a nova versão está pronta. Clique para sair, instalar e reabrir; caso contrário, ela é instalada na próxima vez que você sair do DuckLocal.
- Atualização disponível: v0.3.1 — uma release mais nova que esta cópia não consegue instalar sozinha: uma compilação que você mesmo fez, ou um app em uma pasta onde ele não pode escrever. Clique para baixar o pacote e instale-o como você instalou este.
- Falha ao verificar atualizações — passe o cursor para ver o motivo (sem conexão, um proxy, um download que não correspondia ao checksum); clique para tentar de novo.
As atualizações vêm de dl.ducklocal.app, os mesmos pacotes da release no GitHub, servidos a partir de um espelho que também é rápido na China continental.
No macOS, o menu DuckLocal tem a mesma verificação, como Verificar atualizações…, e Verificar atualizações ao iniciar, que verifica uma vez a cada vez que o app inicia. Ela fica desativada até você ativá-la (a configuração update_check, on ou off). Até lá, o DuckLocal só verifica quando você clica.
Idioma
O botão EN / 中 na barra de título troca o idioma da interface na hora e registra a escolha.
Na primeira execução — antes que qualquer configuração seja guardada — o idioma vem da localidade do sistema: LC_ALL ou LANG contendo zh seleciona chinês, qualquer outra coisa seleciona inglês. Um valor guardado não reconhecido volta para o chinês.
Algumas strings deliberadamente não são traduzidas: DuckLocal, os rótulos dos botões S3 e EXPLAIN, o seletor EN / 中 e os espaços reservados das credenciais. Mensagens de erro do motor e da rede aparecem na íntegra e estão sempre em inglês, qualquer que seja o idioma da interface.
Temas
O botão de sol/lua alterna entre o tema claro e o escuro. Não há seletor de temas nem arquivo de tema para editar — os dois modos são o que existe.
Tamanho da interface
Texto, ícones e controles escalam juntos, em quatro passos:
| Tamanho | Texto base | Texto do editor |
|---|---|---|
| Pequeno | 13px | 12px |
| Padrão | 14px | 13px |
| Grande | 16px | 15px |
| Muito grande | 18px | 17px |
Escolha um no botão Aa da barra de título, ou percorra-os com ⌘+ (maior), ⌘− (menor) e ⌘0 (voltar ao padrão) — eles funcionam onde estiver o foco, inclusive no editor SQL. A escolha é lembrada e sobrevive à troca entre claro e escuro.
Tamanhos de painel que você arrastou, e a altura dos gráficos de um painel, ficam em pixels: são seus para ajustar, não da interface.
Redefinir
Para começar de novo — limpando o histórico, os arquivos registrados, os bancos de dados anexados, as abas lembradas e todas as configurações — saia do DuckLocal e remova o diretório de dados do app:
rm -rf ~/Library/Application\ Support/DuckLocal # macOS
rm -rf ~/.local/share/ducklocal # LinuxNo Windows, apague %APPDATA%\DuckLocal.
A próxima execução o cria do zero. Seus arquivos de dados nunca são afetados por isso, apenas os registros do próprio DuckLocal.
Solução de problemas
Sintomas, causas e correções estão reunidos na página de Solução de problemas.
