Ir para o conteúdo

Solução de problemas ​

Encontre o sintoma, leia a causa e aplique a correção. Se o seu problema não está na lista, abra uma issue com detalhes do que você fez e do que aconteceu.

Instalação e inicialização ​

SintomaCausa e solução
O app não abre em um Mac IntelA versão de macOS é compilada apenas para Apple silicon. Compile a partir do código-fonte no Intel
Os atalhos desta documentação não fazem nada no Windows ou LinuxLeia Ctrl onde está ⌘: ⌘↵ é Ctrl+Enter ali
ducklocal: command not foundA imagem de disco instala o app, não um comando. Crie um link do binário no seu PATH
O terminal fica ocupado enquanto a janela está abertaAbrir a GUI pelo terminal a executa em primeiro plano. Inicie pelos Aplicativos, ou deixe aquele terminal para ela
O histórico, as configurações ou os arquivos lembrados param de ser salvosUm segundo DuckLocal está rodando e segura o arquivo de dados do app. Saia do outro e inicie de novo
O DuckLocal saiu inesperadamente da última vezEle travou e salvou um relatório na pasta de logs. Clique em Mostrar relatório e anexe-o a uma issue — veja onde as coisas ficam guardadas
Falha na verificação de atualizaçõesPasse o mouse por cima para ver o motivo: sem conexão, um proxy, ou um download que não correspondia ao seu checksum. Clique para tentar de novo, ou baixe a versão pelo GitHub — veja Verificação de atualizações

Abrindo dados ​

SintomaCausa e solução
File not found em um caminho que você informouO caminho não existe, ou é relativo a um diretório diferente do que você imagina. Use um caminho absoluto para ter certeza
Uma pasta não informa nenhum arquivo de dadosNada dentro dela correspondia a .csv, .tsv, .txt, .parquet, .json, .ndjson, .jsonl, .xlsx, .xls, .xlsb ou .ods
Uma pasta produziu menos arquivos do que o esperadoEntradas ocultas e links simbólicos são ignorados, e um pedido de abertura anexa no máximo 256 arquivos. Abra as subpastas separadamente
Um caminho foi aberto como banco de dados sem você esperarQualquer arquivo existente que não seja um arquivo de dados é tratado como banco de dados DuckDB. Se não abrir, o DuckLocal diz por quê; na inicialização ele volta para a memória. Veja Abrindo um banco de dados
Não anexado …: o banco de dados já tem uma tabela ou view chamada …O banco de dados já contém uma tabela ou view com o mesmo nome do arquivo lembrado. O DuckLocal nunca a substitui. Renomeie ou descarte uma das duas, ou remova o arquivo de Arquivos locais e abra de novo para obter um nome novo
Não é possível restaurar o caminho relativo …Um arquivo foi lembrado por um caminho relativo, que não pode ser resolvido em uma sessão nova. Remova-o de Arquivos locais e abra de novo
Uma view mostra sales_2 em vez de salesOutro arquivo ou tabela já tinha aquele nome, então a nova recebeu um sufixo
A view de um arquivo está desatualizadaAs views leem o arquivo a cada consulta. Se as colunas de um CSV mudaram de forma, use Atualizar esquema na barra lateral

Abrindo um banco de dados ​

SintomaCausa e solução
A mensagem diz que o banco de dados foi criado por um DuckDB mais recenteO arquivo usa um formato de armazenamento mais recente do que o DuckDB embutido no DuckLocal lê. Execute as linhas ATTACH … COPY FROM DATABASE da mensagem no DuckDB que criou o arquivo, e depois abra a cópia. Veja Quando um banco de dados não abre
A mensagem diz que o banco de dados vem do DuckDB v0.9 ou anteriorExecute EXPORT DATABASE 'dir' com o DuckDB que o escreveu, e depois IMPORT DATABASE 'dir' no DuckLocal
A mensagem diz que é um banco de dados SQLiteAnexe-o com Abrir → Anexar banco de dados… em vez de abri-lo
A mensagem diz que o arquivo não é um banco de dados DuckDBA extensão dele não é uma das que o DuckLocal lê como dados, então ele foi tentado como banco de dados. Dê a ele uma extensão compatível, ou leia-o em SQL, por exemplo SELECT * FROM read_csv('export.dat')
O DuckDB diz que não conseguiu definir um bloqueio no arquivoOutro programa — outro DuckDB, um script, um segundo app — tem o banco de dados aberto para escrita, e o DuckDB permite que apenas um processo escreva em um arquivo. Feche-o lá e abra o arquivo de novo
O DuckDB diz que a permissão foi negadaSua conta não pode ler o arquivo, ou não pode escrever nele: o banco de dados principal é aberto para escrita. Corrija as permissões do arquivo, ou anexe-o com Somente leitura marcado
Uma abertura de banco de dados falhou e nada mudouÉ o esperado enquanto o DuckLocal está rodando: uma abertura com falha mantém o espaço de trabalho que você tinha. Leia a notificação para saber o motivo
A dica da barra de status diz legível pelo DuckDB v1.x+ e um colega não consegue abrir o arquivoO DuckDB dele é anterior a essa versão. Ele precisa atualizar, ou você copia o arquivo com um STORAGE_VERSION anterior — veja Qual DuckDB consegue ler um banco de dados

Bancos de dados anexados ​

SintomaCausa e solução
Um banco de dados anexado desaparece depois de reiniciarO arquivo dele não estava no caminho lembrado na inicialização, então foi ignorado. O registro é mantido; devolva o arquivo ao lugar e ele volta na próxima conexão
Este banco de dados já está aberto, como …O arquivo já é o banco de dados principal, ou está anexado com esse nome. Consulte-o por esse nome
Não foi possível anexar …: o nome … está ocupado no banco de dados aberto.Outra coisa na conexão já usa o alias lembrado — por exemplo, um banco de dados que você anexou em SQL com o mesmo nome. Faça DETACH desse e depois reabra o banco de dados ou reinicie
Escrever em um banco de dados anexado falhaEle foi anexado como somente leitura, que é o padrão. Use Desanexar banco de dados na barra lateral e anexe de novo com Somente leitura desmarcado
Anexar criou um banco de dados vazioCom Somente leitura desmarcado, um caminho DuckDB que não existe é criado. Desanexe-o, apague o arquivo vazio e confira o caminho
Um nome de tabela sem banco de dados encontra a tabela erradaNomes sem banco de dados são resolvidos no banco de dados padrão. Clique com o botão direito em um banco de dados e escolha Usar como banco de dados padrão, ou escreva alias.table

Finder e Quick Look ​

Isto existe apenas no macOS.

SintomaCausa e solução
Dar duplo clique em um arquivo .parquet ou .duckdb abre outro appEsse app já é o padrão. No Finder, Obter informações → Abrir com, escolha DuckLocal e depois Alterar tudo…
Dar duplo clique em um arquivo CSV ou Excel não abre o DuckLocalÉ intencional: o DuckLocal não assume esses formatos. Use Abrir com → DuckLocal, ou arraste o arquivo sobre o ícone do Dock
O DuckLocal não aparece em Abrir com, ou Espaço não mostra uma prévia do DuckLocalO macOS ainda não registrou o app. Mova-o para Aplicativos e inicie uma vez. Para a prévia, execute depois qlmanage -r no Terminal, e confira se DuckLocal Preview está ativado em Quick Look, nas configurações de extensões das Configurações do Sistema
Um arquivo .json comum ou do Excel não mostra prévia do DuckLocalÉ intencional: esses ficam com as prévias do próprio macOS. Arquivos .jsonl e .ndjson têm prévia
A prévia mostra apenas 50 linhasÉ intencional: uma prévia nunca varre o arquivo inteiro. Abra o arquivo no DuckLocal para ver o resto
A prévia de um arquivo .duckdb mostra um erroA prévia lê o arquivo com o DuckDB do próprio DuckLocal, então um arquivo de um DuckDB mais recente também falha ali. Veja Abrindo um banco de dados

Executando consultas ​

SintomaCausa e solução
Executar não faz nadaJá há uma consulta rodando. Pressione Parar ao lado de Executar, ou ⌘., para interrompê-la
Uma consulta falhou com InterruptedAlguém pressionou Parar (ou ⌘.) enquanto ela rodava. Execute de novo
Parte do meu SQL tem um sublinhado ondulado vermelhoA última execução falhou ali. Leia a mensagem Consulta falhou; a marca desaparece na próxima execução
⌘↵ mostra o editor em vez de executarNa tela de primeiro início, ⌘↵ significa "me dê um editor". Pressione de novo para executar
Os resultados param cedo demais com um aviso de truncamentoO limite de 100.000 linhas ou 2.000.000 de células foi atingido. Restrinja a consulta; não há paginação
As datas e horas parecem deslocadasA grade renderiza datas e horas em UTC, não no horário local
Um valor TIMETZ perdeu seu deslocamento, ou um valor BIT ou BIGNUM parece bytesEsses tipos não podem ser distinguidos de valores comuns no caminho até o DuckLocal. CAST(column AS VARCHAR) em SQL mostra o valor real
Ordenar não traz linhas além da préviaA ordenação pelo cabeçalho apenas reordena as linhas carregadas. Use ORDER BY em SQL para ordenar o resultado completo antes do truncamento
Uma consulta precisa de uma extensão que não está instaladaExtensões faltantes não são mais baixadas automaticamente. Instale-a explicitamente na aba Extensões, depois carregue-a ou execute a consulta de novo
Uma consulta que funcionava antes da 0.3.0 diz que uma extensão não está instalada, ou que uma função não existeO DuckLocal 0.3.0 roda o DuckDB 2.0, que mantém as extensões instaladas por versão. Instale-as de novo na aba Extensões — veja Extensões
Um alias de coluna sem aspas como minutes provoca um erro de análiseÉ uma palavra-chave SQL. Escreva AS minutes, ou ponha entre aspas: SELECT count(*) AS "minutes" FROM events
Clicar em uma tabela ou em uma entrada do histórico apagou meu SQLEsses cliques substituem todo o buffer do editor. Use uma aba de consulta nova para rascunhos
Uma exportação substituiu um arquivo sem avisarExportar escreve no caminho que você informa sem perguntar. Escolha um nome novo

S3 ​

SintomaCausa e solução
As credenciais de S3 foram esquecidasElas duram apenas a sessão, por design, e abrir ou trocar de banco de dados as apaga. Configure o S3 de novo
Configurar o S3 falha sem conexãoO primeiro uso executa INSTALL httpfs, que baixa a extensão. Conecte-se uma vez e ela fica em cache
Credenciais temporárias (STS) são rejeitadasNenhum token de sessão é enviado. Use chaves de longa duração — veja S3 e httpfs
Um bucket parece menor do que éA listagem para em 1.000 entradas por nível. Consulte com um glob como 's3://bucket/prefix/*.parquet'

Painéis ​

SintomaCausa e solução
Um gráfico de painel diz que uma consulta precisa ser somente leituraUma consulta .dash tentou escrever (DDL, DML, COPY, ATTACH, …). Painéis executam apenas instruções somente leitura; mova a preparação para o editor SQL
Um agente não viu meus comentáriosComentários não são enviados para lugar nenhum: o agente precisa lê-los. Peça para ele executar ducklocal comments FILE, ou para "tratar os comentários de FILE" se ele tiver a skill oficial
A resposta ou a edição de um agente não apareceA janela acompanha tanto a especificação quanto FILE.comments.json em menos de um segundo. Uma especificação que não valida mais mantém o último painel que funcionava, com o motivo acima dele; abra Ver especificação para ver o arquivo
Um PIVOT em um painel é rejeitadoUm PIVOT aninhado dentro de um SELECT ou de um WITH precisa nomear seus valores. Liste-os: PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue), ou comece a consulta com o PIVOT

Aparência ​

SintomaCausa e solução
O tema volta para o claro a cada inícioO tema não é salvo entre inícios; o idioma é
O texto ou os ícones estão pequenos ou grandes demaisUse o botão Aa na barra de título, ou ⌘+ / ⌘− / ⌘0. Veja Tamanho da interface
A interface está no idioma erradoUse o botão EN / 中 na barra de título; a escolha é lembrada

Começando de novo ​

Para limpar o histórico, os arquivos lembrados, as abas abertas e as configurações, saia do DuckLocal e remova seu diretório de dados do app:

bash
rm -rf ~/Library/Application\ Support/DuckLocal

Seus arquivos de dados nunca são tocados — apenas os registros do próprio DuckLocal são removidos. Veja Configurações e dados do app para saber o que fica guardado ali.

Publicado sob a licença Apache-2.0.