COLIBRI SQL — Manual de usuario
Versión 1.4 · Un producto de LiVnet - RELV - 2026
COLIBRI SQL es un cliente ligero de SQL Server, al estilo de SSMS, para Linux (también en equipos ARM como la Surface RT) y Windows. Permite conectarse a uno o varios servidores, escribir y ejecutar consultas, explorar los objetos de cada base, trabajar con scripts versionados en git y usar herramientas como comparar, clonar, respaldar o programar tareas.
1. Primeros pasos
Instalación
-
Linux (Debian, Raspbian, Ubuntu): instala el paquete
colibri-sql_1.4-1_all.deb(sudo apt install ./colibri-sql_1.4-1_all.deb). Aparece en el menú de aplicaciones como «COLIBRI SQL». -
Windows: ejecuta
COLIBRI-SQL-1.4-instalador.exe(se instala solo para tu usuario, sin permisos de administrador) o descomprime la versión portable (COLIBRI-SQL-1.4-portable.zip) donde quieras, incluso en una memoria USB: los perfiles y ajustes viajan con el programa (carpetadatos).
Idioma
El programa está en español, inglés y portugués. Se elige en ☰ → Idioma (o «Automático», el del sistema) y queda guardado; se aplica al volver a abrir el programa. En Windows el instalador también pregunta el idioma.
Licencia y prueba gratuita
- Al abrirlo por primera vez, COLIBRI SQL pide al servidor de licencias una prueba gratuita de 30 días (necesita internet esa vez). Es una por PC: reinstalar o borrar la configuración no la reinicia. Arriba a la derecha se ve «Prueba: N d» con los días que quedan. Si el servidor de licencias no responde (sin internet), hay 7 días de prueba local desde la primera vez que se abrió; cuando el servidor responda, empieza la prueba de 30 días.
- Beta gratuita: mientras dure la beta pública, la prueba no termina a los 30 días sino el último día de la beta, y arriba se ve «Beta: N d». Quien la usa tiene precio de fundador (la mitad, mientras renueve cada año) si compra hasta 30 días después de que termine; la ventana de licencia muestra hasta qué fecha. El programa consulta una vez al día si la prueba cambió (sin internet, la que hay sigue igual).
-
Para activar una licencia: ☰ → Licencia… (o clic en ese botón), pega el código que te llegó (empieza con
CSQL1.) y pulsa Activar en esta PC. Necesita internet una vez; después funciona sin internet hasta 30 días y se renueva sola cada 7 días. - Una licencia vale para una PC (o las que diga tu licencia). Para pasarla a otra computadora, pulsa Liberar esta PC en la de antes y actívala en la nueva.
- Sin licencia ni prueba vigente, el programa queda en modo limitado: puedes abrir, editar y guardar scripts y ver el explorador, pero no ejecutar consultas, el asistente ni las herramientas (clonar, respaldar, tareas…). El botón Activar licencia queda a la vista.
- Versión nueva: una vez al día el programa pregunta si hay otra versión; si la hay, aparece un ícono de actualización junto al botón de la licencia con las novedades y el enlace de descarga. También: ☰ → Buscar versión nueva.
- Se envía solo el código, un resumen del identificador de la PC, el nombre del equipo y la versión del programa; nunca datos de tus bases.
La ventana
- Inicio: sin pestañas abiertas se ve la pestaña «Inicio», con un colibrí de fondo y los primeros pasos.
- Arriba: los botones de la ventana (panel lateral, Conectar, Nueva consulta, Abrir, Guardar, Historial, Registro de conexiones), las pestañas y el menú ☰.
- A la izquierda: el panel lateral con Conexiones (explorador de objetos), Proyecto (carpeta de scripts con git) y Abiertas (lista de pestañas). Se muestra u oculta con Ctrl+B.
- En cada pestaña de consulta: la barra de botones, el editor y, abajo, los resultados y mensajes.
2. Conectarse a un servidor
Al abrir el programa (o con el botón Conectar, o Ctrl+Shift+N) aparece la pestaña Conectar: a la izquierda tus perfiles guardados (el último usado arriba) y a la derecha el formulario. Doble clic o Enter en un perfil conecta. Mientras conecta puedes seguir usando el programa, y el botón Conectar se cambia por Cancelar conexión (si te equivocaste de servidor o de datos, no hay que esperar): corrige y vuelve a conectar. Si mientras conecta eliges otro perfil (doble clic) o presionas Enter, se cancela el intento y se conecta con los datos nuevos.
Datos del perfil
- Nombre del perfil, servidor y puerto (1433 por defecto), base predeterminada.
- Autenticación: usuario de SQL Server, o cuenta de dominio de Windows (DOMINIO\usuario, por NTLM).
- Color: verde (desarrollo), amarillo (pruebas), rojo (producción)… Se ve como una franja en las pestañas y la consulta. Las conexiones rojas empiezan en modo de transacción Manual y piden confirmación antes de ejecutar cambios.
- Cifrado (TLS) y túnel SSH: si el servidor solo se alcanza a través de otra máquina, COLIBRI SQL abre el túnel por ti (con llave SSH o contraseña).
El cuadro de estado va mostrando cada paso (túnel, servidor, usuario) y los errores con una pista de la causa. Todo queda en el Registro de conexiones (botón de la barra superior).
Conexiones abiertas
En el explorador, clic derecho en un servidor: Editar conexión…, Monitor del servidor…, Trabajos del SQL Server Agent…, Restaurar una base…, Color de la conexión y Desconectar. Al desconectar, las pestañas de ese servidor no se cierran: quedan sin conexión, con su texto.
3. Pestañas de consulta
- Nueva consulta: Ctrl+N (en la conexión actual). Abrir un .sql: Ctrl+O. Guardar: Ctrl+S; Guardar como: Ctrl+Shift+S.
- Sin conexión: un archivo se abre aunque no estés conectado; la barra muestra «○ Sin conexión ▾». Puedes leer, editar y guardar; al ejecutar, el programa te pide elegir una conexión.
- Cambiar la conexión de una pestaña (como en SSMS): clic en el rótulo «● servidor · usuario ▾» de la barra y elige otra conexión abierta u Otra conexión….
- Sesión: al cerrar el programa se recuerdan las pestañas con su texto; se reabren al conectar a cada servidor (las sin conexión, al abrir).
Muchas pestañas
Tres ayudas, que se activan en ☰ → Pestañas:
- Botón ▾ al final de la fila de pestañas (o Ctrl+Shift+A): lista de todas, con buscador, agrupadas por conexión.
- Panel «Abiertas» en el lado izquierdo.
- Varias filas (como SSMS): las solapas bajan a varias filas; viene apagada porque quita alto al editor.
Cerrar: con la ×, con el botón del medio del mouse o con clic derecho en una solapa: cerrar, cerrar las demás, las de la izquierda, las de la derecha, todas, las de esta conexión o las que no tienen cambios. Si varias tienen cambios sin guardar, pregunta una sola vez. Si la pestaña está guardada en un archivo, el mismo menú tiene Mostrar en el panel Proyecto (si el archivo es de la carpeta abierta en «Proyecto»: abre el panel, sus carpetas y lo deja seleccionado) y Abrir en el explorador de archivos (queda seleccionado en Windows y en Linux con Thunar, Nautilus, Nemo o Dolphin; PCManFM solo abre la carpeta).
4. El editor y la ejecución
La barra de la consulta
Todos los botones son íconos; al pasar el mouse se ve su nombre y atajo, y el botón ? (o F1) explica cada uno.
| Botón | Atajo | Qué hace |
|---|---|---|
| Ejecutar | F5 · Ctrl+E | Ejecuta todo el script, o la selección |
| Sentencia del cursor | F8 · Ctrl+Enter | Ejecuta solo la sentencia donde está el cursor |
| Cancelar | Esc | Detiene la ejecución |
| Plan | Ctrl+L | Plan de ejecución estimado, sin ejecutar |
| Depurar | Alt+F5 · F10 | Ejecuta paso a paso, con puntos de interrupción (F9) |
| Limpiar | Borra el editor (se deshace con Ctrl+Z) | |
| Estructura | Ctrl+Shift+O | Lotes, sentencias y CTE del script |
| Asistente | Ctrl+I | Panel del asistente de IA |
| Base | Base activa de la pestaña (USE) | |
| Candado | Abierto = Auto; cerrado = Manual (Commit / Rollback) |
Transacciones
- Auto: cada sentencia se confirma sola, como en SSMS.
- Manual: los cambios quedan en una transacción abierta hasta pulsar Commit ✓ o Rollback ↶ (el número indica cuántas hay pendientes). Si cierras la pestaña o cambias de conexión con una transacción abierta, el programa pregunta qué hacer.
Ayudas al escribir
-
Autocompletado (Ctrl+Espacio): tablas, columnas por alias, JOIN con su ON según las llaves foráneas. Tab expande
*en columnas o un fragmento (ssf,sst,itc…; se editan en ☰ → Editar fragmentos). - Formatear SQL: Ctrl+K (opciones en ☰ → Opciones de formato de SQL…).
-
Lo igual a la selección: al seleccionar algo (doble clic en una palabra, una parte o una letra), todo lo igual se resalta en naranja; lo que se busca con Ctrl+F va en verde. Con una palabra entera, solo esa palabra (
@idno marca@id_ups); con una parte o una letra, dondequiera que aparezca. No distingue mayúsculas. Se apaga con «Resaltar en naranja lo igual a la selección» en el menú del editor. -
Edición en columna: Shift+Alt+flechas o Shift+Alt+arrastrar el mouse marcan un bloque (un rectángulo, o un cursor alto en varias líneas). Lo que escribes va en todas esas líneas a la vez (por ejemplo, agregar
c.delante de varias columnas); si el bloque tiene ancho, lo reemplaza. Retroceso y Supr borran en todas; Ctrl+C copia el bloque; Ctrl+V pega una línea en todas. Las líneas más cortas se rellenan con espacios. Esc o un clic lo quitan. - Buscar y reemplazar: Ctrl+F; escribe y presiona Enter (F3 / Shift+F3: siguiente / anterior). Mientras escribes no se busca, así el editor no salta a otra parte; con el botón a→ de la barra se busca letra por letra (se recuerda). Al volver a Ctrl+F, el texto anterior queda seleccionado: si escribes, lo reemplazas; con Fin o una flecha lo conservas. Si en el editor hay algo seleccionado (una línea), se busca eso. Ir a línea: Ctrl+G. Ir a objeto: Ctrl+P.
- Ir a la definición del objeto bajo el cursor: F12. Dónde se usa: Alt+F7. Documentación rápida: Ctrl+Q.
-
Parámetros: escribe
:nombreen el SQL (por ejemploWHERE fecha >= :desde); al ejecutar se piden los valores. - Inspecciones: mientras escribes se subrayan (rojo: error; ámbar: aviso; al pasar el mouse se ve la explicación) tablas o columnas que no existen, UPDATE/DELETE sin WHERE y otros problemas.
-
Variables: en rojo, una variable declarada dos veces en el mismo lote (o que repite un parámetro del procedimiento) y una variable usada sin su
DECLARE(o antes de él); en ámbar, una variable que se declara y no se usa. Como en SQL Server, cadaGOempieza un lote nuevo. Funciona también sin conexión y en procedimientos muy largos (en los de más de 120.000 caracteres se revisan solo las variables, no tablas ni columnas). Se apagan todas con la opción «Inspecciones: subrayar problemas» del menú del editor.
5. Resultados
Cada SELECT da un resultado en su pestaña (o uno debajo de otro, con el botón Resultados apilados). Los mensajes (PRINT) y errores van en Mensajes, en el orden en que llegan, como en SSMS: cada error dice número, nivel, estado y, si viene de un procedimiento, cuál y su línea; si es del propio script, la línea del editor. Al final, la hora de finalización (también si hubo errores). Si hubo un error, se abre Mensajes, pero las filas que alcanzaron a llegar quedan en su pestaña. Ojo: si el script hizo ROLLBACK después, esas filas ya no están en la base.
-
Filtrar filas sin volver a consultar: texto (contiene),
=valor,<>valor,>100,!texto,NULL,!NULL; varias condiciones con;. El combo elige la columna. - Clic en un encabezado ordena (ascendente, descendente, original).
-
Clic derecho en una celda:
- Mostrar solo / Excluir ese valor (escribe el filtro por ti) y Quitar el filtro de filas.
- Ir a la tabla relacionada y Filas que lo referencian, por llave foránea; si la base no declara la FK, se deduce por el nombre de la columna («· por nombre de columna»).
- Copiar celda, filas, con encabezados, o Copiar como… INSERT, UPDATE, lista para IN, JSON, Markdown o HTML.
- Exportar a Excel, CSV o PDF.
- Analizar ▾: tabla dinámica, gráfico o comparar con otro resultado.
- Transponer: cada fila se muestra como una columna (cómodo para un solo registro).
- Visor: muestra completo el valor de la celda elegida (textos largos, JSON y XML con formato).
-
Descripciones (ícono de diccionario): junto a cada código que es llave muestra su nombre de la tabla relacionada, por ejemplo
1234 · Hospital X. Copiar y exportar siguen usando el código. - Al seleccionar celdas numéricas, la barra de estado muestra suma, promedio, mínimo y máximo.
6. Explorador de objetos
-
Filtrar objetos…: busca por nombre en las bases abiertas en el árbol y en la de la pestaña actual (carga las carpetas que falten). Prefijos:
t:tablas,v:vistas,p:procedimientos,f:funciones (por ejemplop:actividad). El botón de al lado busca el texto dentro del código y en nombres de columnas (Buscar en la base, Ctrl+Shift+F). - Filtro por carpeta (como SSMS): clic derecho en Tablas, Vistas, Procedimientos o Funciones → Filtrar… por nombre, esquema, fechas de creación o modificación, código o columna. Las carpetas muestran la cantidad de objetos.
- Favoritos: clic derecho en un objeto → ★ Agregar a favoritos; cada base muestra primero su carpeta ★ Favoritos.
- Clic derecho en una tabla: primeras 1000 filas, contar, scripts SELECT/INSERT/UPDATE/CREATE, Editar datos, importar CSV/Excel, generar datos de prueba, diagrama de relaciones, clonar o sincronizar, dónde se usa.
- Clic derecho en una base: nueva consulta, constructor de consultas, importar, documentar, diagrama, comparar esquema, clonar varias tablas, clonar base completa, respaldar y restaurar.
- Doble clic en una tabla: SELECT TOP 1000; en un procedimiento o función: su script ALTER.
7. Asistente de IA
Botón Asistente (Ctrl+I). Escribe, explica y corrige consultas conociendo la estructura de tu base y la conexión de la pestaña. Sus respuestas con SQL tienen el botón Insertar ▾: en el cursor, al final del editor, o limpiar el editor e insertar; antes del SQL se agrega un comentario breve con el modelo y la fecha. Todo se deshace con Ctrl+Z.
Privacidad: con modelos en la nube, el asistente no lee datos de las tablas salvo que lo actives en sus ajustes; con un modelo local siempre puede.
8. Proyecto (scripts con git)
Pestaña Proyecto del panel lateral: abre una carpeta de scripts (si es un repositorio git, muestra la rama y su estado).
- Archivos: árbol con filtro; doble clic abre el script. Clic derecho: Abrir en el explorador de archivos (también en las carpetas y en «Cambios»), historial del archivo, quién cambió cada línea (blame), ★ Agregar a favoritos. El botón ★ muestra solo los favoritos; también están en ☰ → Scripts favoritos.
- Cambios: marca los archivos, escribe el mensaje y haz Commit o Commit y Push; corregir el último commit (amend).
- Historial: commits con su detalle; crear ramas o etiquetas desde un commit.
-
Ramas: clic en el nombre de la rama: lista con buscador, las más recientes primero (según su último commit; también más antiguas o A → Z, y se recuerda), y un campo para crear una rama nueva desde donde estás (se lleva tus commits sin subir: útil si
developestá protegida; luego Push y el Merge Request en GitLab). - Pull / Push, ramas (crear, cambiar, comparar, borrar), merge, stash y acceso al servidor (token, contraseña o llave SSH) en el menú ⋮.
- El estado se revisa solo cada 20 segundos; el árbol conserva las carpetas que abriste.
9. Herramientas
- Comparar en varias bases (Ctrl+Shift+E): ejecuta una consulta en varias bases o servidores y compara.
- Comparar esquemas: diferencias de tablas, vistas, procedimientos y funciones entre dos bases, con un script de sincronización que se abre sin ejecutarse.
- Clonar / sincronizar tabla: crea la tabla en el destino y copia las filas, o la sincroniza por la clave (insertar, actualizar y, si se pide, borrar). Muestra el plan y el script antes de cambiar nada.
- Clonar varias tablas: marcas las tablas y un método por cada una (crear y copiar, solo estructura, insertar las que faltan, sincronizar, igualar al origen). Se copian de a una, las tablas padre primero; se puede pausar, detener y retomar.
- Clonar base completa: copia toda la base (esquemas, tipos, secuencias, tablas, índices, llaves, vistas, procedimientos, funciones, triggers) con los datos en partes de N filas, pausa entre partes y retomar donde quedó si se corta. La base destino se crea o debe estar vacía. No copia usuarios ni permisos.
- Respaldar (BACKUP) y Restaurar (RESTORE) una base: las rutas de los .bak son del servidor. Restaurar nunca toca las bases del sistema y, para sobrescribir una base, hay que escribir su nombre.
- Tareas programadas: ejecutar una consulta y guardar el resultado en Excel o CSV a una hora (todos los días o algunos) o cada N horas. Corren con el programa abierto; si se pasó la hora, preguntan al abrir. Instalado en Linux, también pueden correr con el programa cerrado (cron).
- Monitor del servidor, Trabajos del SQL Server Agent, Constructor de consultas, importar CSV/Excel, generar datos de prueba, documentar la base y diagramas.
10. Ajustes y archivos
-
☰ → Tema (claro, oscuro y otros) e Idioma. ☰ → Abrir ajustes muestra
ajustes.json. -
Linux: perfiles y ajustes en
~/.config/colibri-sql, historial en~/.local/share/colibri-sql, exportaciones enDocumentos/COLIBRI-SQL. -
Windows:
%APPDATA%\COLIBRI SQL(en la portable, la carpetadatosjunto al programa). -
Las contraseñas de los perfiles se guardan en
conexiones.jsoncon permisos solo para tu usuario: protege esa carpeta y sus respaldos.
11. Atajos de teclado
| Atajo | Acción |
|---|---|
| F5 · Ctrl+E | Ejecutar todo o la selección |
| F8 · Ctrl+Enter | Ejecutar la sentencia del cursor |
| Ctrl+L | Plan de ejecución |
| Esc | Cancelar la ejecución |
| Ctrl+N · Ctrl+Shift+N | Nueva consulta · Conectar |
| Ctrl+O · Ctrl+S · Ctrl+Shift+S | Abrir · Guardar · Guardar como |
| Ctrl+W | Cerrar la pestaña |
| Ctrl+Re Pág · Ctrl+Av Pág | Pestaña anterior · siguiente |
| Ctrl+Shift+A | Lista de todas las pestañas |
| Ctrl+B | Mostrar u ocultar el panel lateral |
| Ctrl+R | Mostrar u ocultar los resultados |
| Ctrl+I | Asistente de IA |
| Ctrl+Espacio · Tab | Autocompletar · expandir * o fragmento |
| Ctrl+/ | Comentar o descomentar líneas |
| Ctrl+K | Formatear SQL |
| Shift+Alt+flechas | Edición en columna (también Shift+Alt+arrastrar) |
| Ctrl+Z · Ctrl+Y | Deshacer · rehacer (también Ctrl+Shift+Z) |
| Ctrl+F · F3 | Buscar · siguiente |
| Ctrl+G · Ctrl+P | Ir a línea · Ir a objeto |
| F12 · Alt+F7 · Ctrl+Q | Definición · Dónde se usa · Documentación rápida |
| Ctrl+H | Historial de consultas |
| Ctrl+Shift+F · Ctrl+Shift+E | Buscar en la base · Comparar en varias bases |
| Ctrl+Shift+O | Estructura del script |
| F9 · F10 · Shift+F5 | Punto de interrupción · paso · detener la depuración |
| F1 | Qué hace cada botón de la barra |
12. Si algo no funciona
- No conecta: revisa el Registro de conexiones; cada paso indica dónde falló. Si el servidor está detrás de una VPN, conéctala primero.
- Túnel SSH: para que funcione sin preguntar (por ejemplo en tareas programadas) usa una llave SSH sin frase de paso.
- Login de dominio rechazado con el error 17892: el servidor tiene un trigger de inicio de sesión que rechaza la conexión; lo resuelve el administrador del servidor.
- «Base en uso» (3101) al restaurar: marca «Cerrar las conexiones abiertas» o ciérralas tú.
-
Permisos: respaldar requiere
db_backupoperator; restaurar y crear bases,dbcreatorosysadmin; clonar, permisos de lectura en el origen y de creación en el destino. -
Modo limitado o «No se pudo conectar con el servidor de licencias»: la prueba y la activación necesitan internet una vez (si usas proxy, que esté en las variables
HTTPS_PROXY). En ☰ → Licencia… pulsa Comprobar ahora. «Ya está activa en otra PC»: libérala en esa PC o escribe a soporte con el identificador que muestra la ventana. -
El programa se cierra o falla: en Linux los errores quedan en
~/.cache/colibri-sql.log.