COLIBRI SQL — Manual do usuário
Versão 1.4 · Um produto da LiVnet - RELV - 2026
O COLIBRI SQL é um cliente leve de SQL Server, no estilo do SSMS, para Linux (inclusive equipamentos ARM como o Surface RT) e Windows. Conecta-se a um ou vários servidores, escreve e executa consultas, explora os objetos de cada banco, trabalha com scripts versionados no git e oferece ferramentas para comparar, clonar, fazer backup ou agendar tarefas.
1. Primeiros passos
Instalação
-
Linux (Debian, Raspbian, Ubuntu): instale o pacote
colibri-sql_1.4-1_all.deb(sudo apt install ./colibri-sql_1.4-1_all.deb). Ele aparece no menu de aplicativos como «COLIBRI SQL». -
Windows: execute
COLIBRI-SQL-1.4-instalador.exe(instala só para o seu usuário, sem permissões de administrador) ou descompacte a versão portátil (COLIBRI-SQL-1.4-portable.zip) onde quiser, até num pendrive: perfis e ajustes viajam com o programa (pastadatos).
Idioma
O programa está em espanhol, inglês e português. Escolha em ☰ → Idioma (ou «Automático», o do sistema); fica salvo e é aplicado ao abrir o programa de novo. No Windows o instalador também pergunta o idioma.
Licença e teste gratuito
- Na primeira vez que abre, o COLIBRI SQL pede ao servidor de licenças um teste gratuito de 30 dias (precisa de internet nessa vez). É um por PC: reinstalar ou apagar a configuração não o reinicia. No canto superior direito aparece «Teste: N d» com os dias que faltam. Se o servidor de licenças não responder (sem internet), há 7 dias de teste local desde a primeira vez que foi aberto; quando o servidor responder, começa o teste de 30 dias.
- Beta gratuita: enquanto durar a beta pública, o teste não termina aos 30 dias, e sim no último dia da beta, e a barra mostra «Beta: N d». Quem a usa tem preço de fundador (a metade, enquanto renovar todo ano) se comprar até 30 dias depois do fim; a janela de licença mostra até que data. O programa consulta uma vez por dia se o teste mudou (sem internet, o atual continua igual).
-
Para ativar uma licença: ☰ → Licença… (ou clique nesse botão), cole o código que recebeu (começa com
CSQL1.) e clique em Ativar neste PC. Precisa de internet uma vez; depois funciona sem internet por até 30 dias e se renova sozinha a cada 7 dias. - Uma licença vale para um PC (ou quantos a sua licença indicar). Para passá-la a outro computador, clique em Liberar este PC no anterior e ative-a no novo.
- Sem licença nem teste vigente, o programa fica em modo limitado: você pode abrir, editar e salvar scripts e ver o explorador, mas não executar consultas, o assistente nem as ferramentas (clonar, fazer backup, tarefas…). O botão Ativar licença fica à vista.
- Versão nova: uma vez por dia o programa verifica se há outra versão; se houver, aparece um ícone de atualização ao lado do botão da licença com as novidades e o link de download. Também: ☰ → Procurar versão nova.
- São enviados só o código, um resumo do identificador do PC, o nome do computador e a versão do programa; nunca dados dos seus bancos.
A janela
- Início: sem abas abertas aparece a aba «Início», com um beija-flor ao fundo e os primeiros passos.
- Em cima: os botões da janela (painel lateral, Conectar, Nova consulta, Abrir, Salvar, Histórico, Registro de conexões), as abas e o menu ☰.
- À esquerda: o painel lateral com Conexões (explorador de objetos), Projeto (pasta de scripts com git) e Abertas (lista de abas). Mostre ou oculte com Ctrl+B.
- Em cada aba de consulta: a barra de botões, o editor e, embaixo, os resultados e mensagens.
2. Conectar a um servidor
Ao abrir o programa (ou com o botão Conectar, ou Ctrl+Shift+N) aparece a aba Conectar: à esquerda os seus perfis salvos (o último usado em cima) e à direita o formulário. Clique duplo ou Enter num perfil conecta. Enquanto conecta, você pode continuar usando o programa, e o botão Conectar vira Cancelar conexão (se errou o servidor ou os dados, não precisa esperar): corrija e conecte de novo. Se enquanto conecta você escolher outro perfil (clique duplo) ou pressionar Enter, a tentativa é cancelada e conecta com os dados novos.
Dados do perfil
- Nome do perfil, servidor e porta (1433 por padrão), banco padrão.
- Autenticação: usuário do SQL Server, ou conta de domínio do Windows (DOMÍNIO\usuário, por NTLM).
- Cor: verde (desenvolvimento), amarelo (testes), vermelho (produção)… Aparece como uma faixa nas abas e na consulta. Conexões vermelhas começam no modo de transação Manual e pedem confirmação antes de executar alterações.
- Criptografia (TLS) e túnel SSH: se o servidor só é alcançado através de outra máquina, o COLIBRI SQL abre o túnel por você (com chave SSH ou senha).
A caixa de estado mostra cada passo (túnel, servidor, usuário) e os erros com uma dica da causa. Tudo fica no Registro de conexões (botão da barra superior).
Conexões abertas
No explorador, clique direito num servidor: Editar conexão…, Monitor do servidor…, Trabalhos do SQL Server Agent…, Restaurar um banco…, Cor da conexão e Desconectar. Ao desconectar, as abas desse servidor não são fechadas: ficam sem conexão, com o seu texto.
3. Abas de consulta
- Nova consulta: Ctrl+N (na conexão atual). Abrir um .sql: Ctrl+O. Salvar: Ctrl+S; Salvar como: Ctrl+Shift+S.
- Sem conexão: um arquivo abre mesmo sem estar conectado; a barra mostra «○ Sem conexão ▾». Você pode ler, editar e salvar; ao executar, o programa pede para escolher uma conexão.
- Mudar a conexão de uma aba (como no SSMS): clique no rótulo «● servidor · usuário ▾» da barra e escolha outra conexão aberta ou Outra conexão….
- Sessão: ao fechar o programa, as abas e o seu texto são lembrados; reabrem ao conectar a cada servidor (as sem conexão, ao abrir).
Muitas abas
Três ajudas, ativadas em ☰ → Abas:
- Botão ▾ no fim da fila de abas (ou Ctrl+Shift+A): lista de todas, com busca, agrupadas por conexão.
- Painel «Abertas» do lado esquerdo.
- Várias linhas (como no SSMS): as abas descem para várias linhas; vem desligada porque tira altura do editor.
Fechar: com o ×, com o botão do meio do mouse ou com clique direito numa aba: fechar, fechar as outras, as da esquerda, as da direita, todas, as desta conexão ou as que não têm alterações. Se várias têm alterações não salvas, pergunta uma só vez. Se a aba está salva num arquivo, o mesmo menu tem Mostrar no painel Projeto (se o arquivo é da pasta aberta em «Projeto»: abre o painel e as suas pastas e o deixa selecionado) e Abrir no explorador de arquivos (o arquivo fica selecionado no Windows e no Linux com Thunar, Nautilus, Nemo ou Dolphin; o PCManFM só abre a pasta).
4. O editor e a execução
A barra da consulta
Todos os botões são ícones; ao passar o mouse aparecem o nome e o atalho, e o botão ? (ou F1) explica cada um.
| Botão | Atalho | O que faz |
|---|---|---|
| Executar | F5 · Ctrl+E | Executa todo o script, ou a seleção |
| Instrução do cursor | F8 · Ctrl+Enter | Executa só a instrução onde está o cursor |
| Cancelar | Esc | Para a execução |
| Plano | Ctrl+L | Plano de execução estimado, sem executar |
| Depurar | Alt+F5 · F10 | Executa passo a passo, com pontos de interrupção (F9) |
| Limpar | Apaga o editor (desfaz-se com Ctrl+Z) | |
| Estrutura | Ctrl+Shift+O | Lotes, instruções e CTEs do script |
| Assistente | Ctrl+I | Painel do assistente de IA |
| Banco | Banco ativo da aba (USE) | |
| Cadeado | Aberto = Auto; fechado = Manual (Commit / Rollback) |
Transações
- Auto: cada instrução é confirmada sozinha, como no SSMS.
- Manual: as alterações ficam numa transação aberta até clicar em Commit ✓ ou Rollback ↶ (o número indica quantas estão pendentes). Se você fechar a aba ou mudar de conexão com uma transação aberta, o programa pergunta o que fazer.
Ajudas ao escrever
-
Autocompletar (Ctrl+Espaço): tabelas, colunas por alias, JOIN com o seu ON segundo as chaves estrangeiras. Tab expande
*em colunas ou um fragmento (ssf,sst,itc…; editam-se em ☰ → Editar fragmentos). - Formatar SQL: Ctrl+K (opções em ☰ → Opções de formatação de SQL…).
-
O igual à seleção: ao selecionar algo (clique duplo numa palavra, uma parte ou uma letra), tudo o que for igual é destacado em laranja; o que se busca com Ctrl+F fica em verde. Com uma palavra inteira, só essa palavra (
@idnão marca@id_ups); com uma parte ou uma letra, onde quer que apareça. Não distingue maiúsculas. Desliga-se com «Destacar em laranja o igual à seleção» no menu do editor. -
Edição em coluna: Shift+Alt+setas ou Shift+Alt+arrastar o mouse marcam um bloco (um retângulo, ou um cursor alto em várias linhas). O que você digita vai em todas essas linhas ao mesmo tempo (por exemplo, colocar
c.antes de várias colunas); se o bloco tiver largura, ele é substituído. Backspace e Delete apagam em todas; Ctrl+C copia o bloco; Ctrl+V cola uma linha em todas. As linhas mais curtas são preenchidas com espaços. Esc ou um clique o removem. - Buscar e substituir: Ctrl+F; digite e pressione Enter (F3 / Shift+F3: próximo / anterior). Enquanto você digita não se busca, assim o editor não salta para outro lugar; com o botão a→ da barra busca-se letra por letra (fica lembrado). Ao voltar a Ctrl+F, o texto anterior fica selecionado: se você digitar, ele é substituído; com End ou uma seta ele é mantido. Se houver algo selecionado no editor (uma linha), busca-se isso. Ir para linha: Ctrl+G. Ir para objeto: Ctrl+P.
- Ir para a definição do objeto sob o cursor: F12. Onde é usado: Alt+F7. Documentação rápida: Ctrl+Q.
-
Parâmetros: escreva
:nomeno SQL (por exemploWHERE data >= :desde); ao executar, os valores são pedidos. - Inspeções: enquanto você digita, são sublinhadas (vermelho: erro; âmbar: aviso; ao passar o mouse aparece a explicação) tabelas ou colunas que não existem, UPDATE/DELETE sem WHERE e outros problemas.
-
Variáveis: em vermelho, uma variável declarada duas vezes no mesmo lote (ou que repete um parâmetro do procedimento) e uma variável usada sem o seu
DECLARE(ou antes dele); em âmbar, uma variável declarada e não usada. Como no SQL Server, cadaGOcomeça um lote novo. Funciona também sem conexão e em procedimentos muito longos (nos de mais de 120.000 caracteres só as variáveis são revisadas, não tabelas nem colunas). Todas são desligadas com «Inspeções: sublinhar problemas» no menu do editor.
5. Resultados
Cada SELECT gera um resultado na sua aba (ou um embaixo do outro, com o botão Resultados empilhados). Mensagens (PRINT) e erros vão para Mensagens, na ordem em que chegam, como no SSMS: cada erro mostra número, nível, estado e, se vem de um procedimento, qual e a sua linha; se é do próprio script, a linha do editor. No final, a hora de término (também se houve erros). Se houve um erro, abre Mensagens, mas as linhas que chegaram ficam na sua aba. Atenção: se o script fez ROLLBACK depois, essas linhas já não estão no banco.
-
Filtrar linhas sem consultar de novo: texto (contém),
=valor,<>valor,>100,!texto,NULL,!NULL; várias condições com;. O combo escolhe a coluna. - Clique num cabeçalho para ordenar (crescente, decrescente, original).
-
Clique direito numa célula:
- Mostrar só / Excluir esse valor (escreve o filtro por você) e Remover o filtro de linhas.
- Ir para a tabela relacionada e Linhas que o referenciam, por chave estrangeira; se o banco não declara a FK, ela é deduzida pelo nome da coluna («· pelo nome da coluna»).
- Copiar célula, linhas, com cabeçalhos, ou Copiar como… INSERT, UPDATE, lista para IN, JSON, Markdown ou HTML.
- Exportar para Excel, CSV ou PDF.
- Analisar ▾: tabela dinâmica, gráfico ou comparar com outro resultado.
- Transpor: cada linha aparece como uma coluna (prático para um só registro).
- Visualizador: mostra completo o valor da célula escolhida (textos longos, JSON e XML formatados).
-
Descrições (ícone de dicionário): ao lado de cada código que é chave mostra o seu nome da tabela relacionada, por exemplo
1234 · Hospital X. Copiar e exportar continuam usando o código. - Ao selecionar células numéricas, a barra de estado mostra soma, média, mínimo e máximo.
6. Explorador de objetos
-
Filtrar objetos…: busca por nome nos bancos abertos na árvore e no banco da aba atual (carrega as pastas que faltam). Prefixos:
t:tabelas,v:views,p:procedimentos,f:funções (por exemplop:atividade). O botão ao lado busca o texto dentro do código e em nomes de colunas (Buscar no banco, Ctrl+Shift+F). - Filtro por pasta (como no SSMS): clique direito em Tabelas, Views, Procedimentos ou Funções → Filtrar… por nome, esquema, datas de criação ou modificação, código ou coluna. As pastas mostram quantos objetos têm.
- Favoritos: clique direito num objeto → ★ Adicionar aos favoritos; cada banco mostra primeiro a sua pasta ★ Favoritos.
- Clique direito numa tabela: primeiras 1000 linhas, contar, scripts SELECT/INSERT/UPDATE/CREATE, Editar dados, importar CSV/Excel, gerar dados de teste, diagrama de relações, clonar ou sincronizar, onde é usado.
- Clique direito num banco: nova consulta, construtor de consultas, importar, documentar, diagrama, comparar esquema, clonar várias tabelas, clonar banco completo, fazer backup e restaurar.
- Clique duplo numa tabela: SELECT TOP 1000; num procedimento ou função: o seu script ALTER.
7. Assistente de IA
Botão Assistente (Ctrl+I). Escreve, explica e corrige consultas conhecendo a estrutura do seu banco e a conexão da aba. As respostas com SQL têm o botão Inserir ▾: no cursor, no final do editor, ou limpar o editor e inserir; antes do SQL é adicionado um comentário breve com o modelo e a data. Tudo se desfaz com Ctrl+Z.
Privacidade: com modelos na nuvem, o assistente não lê dados das tabelas a menos que você ative isso nos seus ajustes; com um modelo local sempre pode.
8. Projeto (scripts com git)
Aba Projeto do painel lateral: abre uma pasta de scripts (se for um repositório git, mostra o ramo e o seu estado).
- Arquivos: árvore com filtro; clique duplo abre o script. Clique direito: Abrir no explorador de arquivos (também nas pastas e em «Alterações»), histórico do arquivo, quem mudou cada linha (blame), ★ Adicionar aos favoritos. O botão ★ mostra só os favoritos; também estão em ☰ → Scripts favoritos.
- Alterações: marque os arquivos, escreva a mensagem e faça Commit ou Commit e Push; corrigir o último commit (amend).
- Histórico: commits com o seu detalhe; criar ramos ou etiquetas a partir de um commit.
-
Ramos: clique no nome do ramo: lista com busca, os mais recentes primeiro (pelo último commit; também mais antigos ou A → Z, e fica lembrado), e um campo para criar um ramo novo a partir de onde você está (leva os seus commits não enviados: útil se
developestá protegido; depois Push e o Merge Request no GitLab). - Pull / Push, ramos (criar, mudar, comparar, apagar), merge, stash e acesso ao servidor (token, senha ou chave SSH) no menu ⋮.
- O estado é revisado sozinho a cada 20 segundos; a árvore mantém as pastas que você abriu.
9. Ferramentas
- Comparar em vários bancos (Ctrl+Shift+E): executa uma consulta em vários bancos ou servidores e compara.
- Comparar esquemas: diferenças de tabelas, views, procedimentos e funções entre dois bancos, com um script de sincronização que abre sem ser executado.
- Clonar / sincronizar tabela: cria a tabela no destino e copia as linhas, ou a sincroniza pela chave (inserir, atualizar e, se pedido, apagar). Mostra o plano e o script antes de mudar algo.
- Clonar várias tabelas: marque as tabelas e um método para cada (criar e copiar, só estrutura, inserir as que faltam, sincronizar, igualar à origem). São copiadas uma por vez, as tabelas pai primeiro; é possível pausar, parar e retomar.
- Clonar banco completo: copia todo o banco (esquemas, tipos, sequências, tabelas, índices, chaves, views, procedimentos, funções, triggers) com os dados em partes de N linhas, pausa entre partes e retomar de onde parou se for interrompido. O banco de destino é criado ou deve estar vazio. Não copia usuários nem permissões.
- Fazer backup (BACKUP) e Restaurar (RESTORE) um banco: os caminhos dos .bak são do servidor. Restaurar nunca toca os bancos do sistema e, para sobrescrever um banco, é preciso escrever o seu nome.
- Tarefas agendadas: executar uma consulta e salvar o resultado em Excel ou CSV num horário (todos os dias ou alguns) ou a cada N horas. Rodam com o programa aberto; se passou a hora, perguntam ao abrir. Instalado no Linux, também podem rodar com o programa fechado (cron).
- Monitor do servidor, Trabalhos do SQL Server Agent, Construtor de consultas, importar CSV/Excel, gerar dados de teste, documentar o banco e diagramas.
10. Ajustes e arquivos
-
☰ → Tema (claro, escuro e outros) e Idioma. ☰ → Abrir ajustes mostra
ajustes.json. -
Linux: perfis e ajustes em
~/.config/colibri-sql, histórico em~/.local/share/colibri-sql, exportações emDocumentos/COLIBRI-SQL. -
Windows:
%APPDATA%\COLIBRI SQL(na versão portátil, a pastadatosjunto ao programa). -
As senhas dos perfis ficam em
conexiones.jsoncom permissões só para o seu usuário: proteja essa pasta e os seus backups.
11. Atalhos de teclado
| Atalho | Ação |
|---|---|
| F5 · Ctrl+E | Executar tudo ou a seleção |
| F8 · Ctrl+Enter | Executar a instrução do cursor |
| Ctrl+L | Plano de execução |
| Esc | Cancelar a execução |
| Ctrl+N · Ctrl+Shift+N | Nova consulta · Conectar |
| Ctrl+O · Ctrl+S · Ctrl+Shift+S | Abrir · Salvar · Salvar como |
| Ctrl+W | Fechar a aba |
| Ctrl+Page Up · Ctrl+Page Down | Aba anterior · seguinte |
| Ctrl+Shift+A | Lista de todas as abas |
| Ctrl+B | Mostrar ou ocultar o painel lateral |
| Ctrl+R | Mostrar ou ocultar os resultados |
| Ctrl+I | Assistente de IA |
| Ctrl+Espaço · Tab | Autocompletar · expandir * ou fragmento |
| Ctrl+/ | Comentar ou descomentar linhas |
| Ctrl+K | Formatar SQL |
| Shift+Alt+setas | Edição em coluna (também Shift+Alt+arrastar) |
| Ctrl+Z · Ctrl+Y | Desfazer · refazer (também Ctrl+Shift+Z) |
| Ctrl+F · F3 | Buscar · seguinte |
| Ctrl+G · Ctrl+P | Ir para linha · Ir para objeto |
| F12 · Alt+F7 · Ctrl+Q | Definição · Onde é usado · Documentação rápida |
| Ctrl+H | Histórico de consultas |
| Ctrl+Shift+F · Ctrl+Shift+E | Buscar no banco · Comparar em vários bancos |
| Ctrl+Shift+O | Estrutura do script |
| F9 · F10 · Shift+F5 | Ponto de interrupção · passo · parar a depuração |
| F1 | O que faz cada botão da barra |
12. Se algo não funcionar
- Não conecta: revise o Registro de conexões; cada passo indica onde falhou. Se o servidor está atrás de uma VPN, conecte-a primeiro.
- Túnel SSH: para funcionar sem perguntar (por exemplo em tarefas agendadas) use uma chave SSH sem frase secreta.
- Login de domínio rejeitado com o erro 17892: o servidor tem um trigger de logon que rejeita a conexão; quem resolve é o administrador do servidor.
- «Banco em uso» (3101) ao restaurar: marque «Fechar as conexões abertas» ou feche-as você.
-
Permissões: fazer backup requer
db_backupoperator; restaurar e criar bancos,dbcreatorousysadmin; clonar, permissão de leitura na origem e de criação no destino. -
Modo limitado ou «Não foi possível conectar ao servidor de licenças»: o teste e a ativação precisam de internet uma vez (se usa proxy, defina-o nas variáveis
HTTPS_PROXY). Em ☰ → Licença… clique em Verificar agora. «Já está ativa em outro PC»: libere-a nesse PC ou escreva ao suporte com o identificador que a janela mostra. -
O programa fecha ou falha: no Linux os erros ficam em
~/.cache/colibri-sql.log.