COLIBRI SQL — User manual
Version 1.4 · A LiVnet product - RELV - 2026
COLIBRI SQL is a lightweight SQL Server client, in the style of SSMS, for Linux (including ARM devices such as the Surface RT) and Windows. It connects to one or more servers, writes and runs queries, explores the objects of each database, works with scripts versioned in git and offers tools to compare, clone, back up or schedule tasks.
1. Getting started
Installation
-
Linux (Debian, Raspbian, Ubuntu): install the package
colibri-sql_1.4-1_all.deb(sudo apt install ./colibri-sql_1.4-1_all.deb). It appears in the applications menu as «COLIBRI SQL». -
Windows: run
COLIBRI-SQL-1.4-instalador.exe(it installs for your user only, without administrator rights) or unzip the portable version (COLIBRI-SQL-1.4-portable.zip) anywhere, even on a USB stick: profiles and settings travel with the program (datosfolder).
Language
The program is in Spanish, English and Portuguese. Choose it in ☰ → Language (or «Automatic», the system one); it is saved and applied the next time the program opens. On Windows the installer also asks for the language.
License and free trial
- The first time it opens, COLIBRI SQL asks the license server for a 30-day free trial (it needs internet that time). There is one per PC: reinstalling or deleting the settings does not restart it. At the top right you see «Trial: N d» with the days left. If the license server does not answer (no internet), there are 7 days of local trial from the first time it was opened; when the server answers, the 30-day trial starts.
- Free beta: while the public beta lasts, the trial does not end after 30 days but on the last day of the beta, and the top bar shows «Beta: N d». Beta users get the founder price (half, as long as they renew every year) if they buy within 30 days after it ends; the license window shows the deadline. The program checks once a day whether the trial changed (without internet, the current one stays as it is).
-
To activate a license: ☰ → License… (or click that button), paste the code you received (it starts with
CSQL1.) and click Activate on this PC. It needs internet once; then it works offline for up to 30 days and renews itself every 7 days. - A license is valid for one PC (or as many as your license says). To move it to another computer, click Release this PC on the old one and activate it on the new one.
- With no license and no valid trial, the program goes into limited mode: you can open, edit and save scripts and browse the explorer, but not run queries, the assistant or the tools (clone, back up, tasks…). The Activate license button stays visible.
- New version: once a day the program checks whether there is a newer version; if there is, an update icon appears next to the license button with what's new and the download link. Also: ☰ → Check for a new version.
- Only the code, a hash of the PC identifier, the computer name and the program version are sent; never data from your databases.
The window
- Home: with no tabs open you see the «Home» tab, with a hummingbird in the background and the first steps.
- Top: the window buttons (side panel, Connect, New query, Open, Save, History, Connection log), the tabs and the ☰ menu.
- Left: the side panel with Connections (object explorer), Project (folder of scripts with git) and Open (list of tabs). Show or hide it with Ctrl+B.
- In each query tab: the button bar, the editor and, below, the results and messages.
2. Connecting to a server
When the program opens (or with the Connect button, or Ctrl+Shift+N) the Connect tab appears: your saved profiles on the left (the last one used on top) and the form on the right. Double-click or Enter on a profile connects. While it connects you can keep using the program, and the Connect button becomes Cancel connection (if you got the server or the details wrong, no need to wait): fix them and connect again. If you choose another profile (double-click) or press Enter while it connects, the attempt is cancelled and it connects with the new details.
Profile data
- Profile name, server and port (1433 by default), default database.
- Authentication: SQL Server user, or Windows domain account (DOMAIN\user, via NTLM).
- Color: green (development), yellow (testing), red (production)… It shows as a stripe on the tabs and the query. Red connections start in Manual transaction mode and ask for confirmation before running changes.
- Encryption (TLS) and SSH tunnel: if the server can only be reached through another machine, COLIBRI SQL opens the tunnel for you (with an SSH key or password).
The status box shows each step (tunnel, server, user) and errors with a hint of the cause. Everything is kept in the Connection log (button on the top bar).
Open connections
In the explorer, right-click a server: Edit connection…, Server monitor…, SQL Server Agent jobs…, Restore a database…, Connection color and Disconnect. When disconnecting, that server's tabs are not closed: they stay without connection, with their text.
3. Query tabs
- New query: Ctrl+N (on the current connection). Open a .sql: Ctrl+O. Save: Ctrl+S; Save as: Ctrl+Shift+S.
- Without connection: a file opens even if you are not connected; the bar shows «○ No connection ▾». You can read, edit and save; when you run, the program asks you to choose a connection.
- Change a tab's connection (as in SSMS): click the «● server · user ▾» label on the bar and choose another open connection or Other connection….
- Session: when the program closes, tabs and their text are remembered; they reopen when you connect to each server (those without connection, on opening).
Many tabs
Three helpers, turned on in ☰ → Tabs:
- ▾ button at the end of the tab row (or Ctrl+Shift+A): list of all tabs, with search, grouped by connection.
- «Open» panel on the left side.
- Multiple rows (like SSMS): the tabs wrap into several rows; it is off by default because it takes height from the editor.
Close: with the ×, with the middle mouse button or with a right-click on a tab: close, close others, those to the left, those to the right, all, those of this connection or those without changes. If several have unsaved changes, it asks only once. If the tab is saved to a file, the same menu has Show in the Project panel (if the file belongs to the folder open in «Project»: it opens the panel and its folders and selects it) and Show in file manager (the file is selected on Windows and on Linux with Thunar, Nautilus, Nemo or Dolphin; PCManFM only opens the folder).
4. The editor and running queries
The query bar
All buttons are icons; hovering shows their name and shortcut, and the ? button (or F1) explains each one.
| Button | Shortcut | What it does |
|---|---|---|
| Run | F5 · Ctrl+E | Runs the whole script, or the selection |
| Statement at cursor | F8 · Ctrl+Enter | Runs only the statement where the cursor is |
| Cancel | Esc | Stops the execution |
| Plan | Ctrl+L | Estimated execution plan, without running |
| Debug | Alt+F5 · F10 | Runs step by step, with breakpoints (F9) |
| Clear | Clears the editor (undo with Ctrl+Z) | |
| Outline | Ctrl+Shift+O | Batches, statements and CTEs of the script |
| Assistant | Ctrl+I | AI assistant panel |
| Database | Active database of the tab (USE) | |
| Padlock | Open = Auto; closed = Manual (Commit / Rollback) |
Transactions
- Auto: each statement commits on its own, as in SSMS.
- Manual: changes stay in an open transaction until you press Commit ✓ or Rollback ↶ (the number shows how many are pending). If you close the tab or change connection with an open transaction, the program asks what to do.
Writing helpers
-
Autocomplete (Ctrl+Space): tables, columns by alias, JOIN with its ON from the foreign keys. Tab expands
*into columns or a snippet (ssf,sst,itc…; edit them in ☰ → Edit snippets). - Format SQL: Ctrl+K (options in ☰ → SQL formatting options…).
-
Matches of the selection: when you select something (double-click a word, part of one or a letter), every match is highlighted in orange; what you search with Ctrl+F is green. With a whole word, only that word (
@iddoes not mark@id_ups); with a part or a letter, wherever it appears. Not case-sensitive. Turn it off with «Highlight matches of the selection in orange» in the editor menu. -
Column editing: Shift+Alt+arrows or Shift+Alt+drag with the mouse mark a block (a rectangle, or a tall cursor over several lines). What you type goes into all those lines at once (for example, adding
c.before several columns); if the block has width, it replaces it. Backspace and Delete delete in all of them; Ctrl+C copies the block; Ctrl+V pastes one line into all of them. Shorter lines are padded with spaces. Esc or a click removes it. - Find and replace: Ctrl+F; type and press Enter (F3 / Shift+F3: next / previous). Nothing is searched while you type, so the editor does not jump elsewhere; with the a→ button in the bar it searches letter by letter (remembered). When you press Ctrl+F again, the previous text is selected: typing replaces it; End or an arrow keeps it. If something is selected in the editor (one line), that is searched. Go to line: Ctrl+G. Go to object: Ctrl+P.
- Go to definition of the object under the cursor: F12. Where used: Alt+F7. Quick documentation: Ctrl+Q.
-
Parameters: write
:namein the SQL (for exampleWHERE date >= :from); the values are asked when you run. - Inspections: while you type, tables or columns that do not exist, UPDATE/DELETE without WHERE and other problems are underlined (red: error; amber: warning; hover to see the explanation).
-
Variables: in red, a variable declared twice in the same batch (or one that repeats a procedure parameter) and a variable used without its
DECLARE(or before it); in amber, a variable that is declared and never used. As in SQL Server, eachGOstarts a new batch. It also works without a connection and in very long procedures (in those over 120,000 characters only variables are checked, not tables or columns). All of them are turned off with «Inspections: underline problems» in the editor menu.
5. Results
Each SELECT gives a result in its own tab (or one below the other, with the Stacked results button). Messages (PRINT) and errors go to Messages, in the order they arrive, as in SSMS: each error shows its number, level, state and, if it comes from a procedure, which one and its line; if it is from the script itself, the editor line. At the end, the completion time (also when there were errors). If there was an error, Messages opens, but the rows that arrived stay in their tab. Note: if the script did a ROLLBACK afterwards, those rows are no longer in the database.
-
Filter rows without querying again: text (contains),
=value,<>value,>100,!text,NULL,!NULL; several conditions with;. The combo chooses the column. - Click a header to sort (ascending, descending, original).
-
Right-click a cell:
- Show only / Exclude that value (it writes the filter for you) and Remove the row filter.
- Go to the related table and Rows that reference it, by foreign key; if the database does not declare the FK, it is inferred from the column name («· by column name»).
- Copy cell, rows, with headers, or Copy as… INSERT, UPDATE, list for IN, JSON, Markdown or HTML.
- Export to Excel, CSV or PDF.
- Analyze ▾: pivot table, chart or compare with another result.
- Transpose: each row is shown as a column (handy for a single record).
- Viewer: shows the full value of the selected cell (long texts, formatted JSON and XML).
-
Descriptions (dictionary icon): next to each code that is a key it shows its name from the related table, for example
1234 · Hospital X. Copy and export still use the code. - When numeric cells are selected, the status bar shows sum, average, minimum and maximum.
6. Object explorer
-
Filter objects…: searches by name in the databases open in the tree and in the current tab's database (it loads the missing folders). Prefixes:
t:tables,v:views,p:procedures,f:functions (for examplep:activity). The button next to it searches the text inside the code and in column names (Search in database, Ctrl+Shift+F). - Folder filter (like SSMS): right-click Tables, Views, Procedures or Functions → Filter… by name, schema, creation or modification dates, code or column. Folders show how many objects they have.
- Favorites: right-click an object → ★ Add to favorites; each database shows its ★ Favorites folder first.
- Right-click a table: first 1000 rows, count, SELECT/INSERT/UPDATE/CREATE scripts, Edit data, import CSV/Excel, generate test data, relationship diagram, clone or synchronize, where used.
- Right-click a database: new query, query builder, import, document, diagram, compare schema, clone several tables, clone whole database, back up and restore.
- Double-click a table: SELECT TOP 1000; a procedure or function: its ALTER script.
7. AI assistant
Assistant button (Ctrl+I). It writes, explains and fixes queries knowing your database structure and the tab's connection. Answers with SQL have the Insert ▾ button: at the cursor, at the end of the editor, or clear the editor and insert; a short comment with the model and the date is added before the SQL. Everything can be undone with Ctrl+Z.
Privacy: with cloud models the assistant does not read table data unless you enable it in its settings; with a local model it always can.
8. Project (scripts with git)
Project tab of the side panel: open a folder of scripts (if it is a git repository, it shows the branch and its state).
- Files: tree with a filter; double-click opens the script. Right-click: Show in file manager (also on folders and in «Changes»), file history, who changed each line (blame), ★ Add to favorites. The ★ button shows only favorites; they are also in ☰ → Favorite scripts.
- Changes: check the files, write the message and Commit or Commit and Push; amend the last commit.
- History: commits with their details; create branches or tags from a commit.
-
Branches: click the branch name: list with a search box, most recent first (by their last commit; also oldest first or A → Z, remembered), and a field to create a new branch from where you are (it takes your unpushed commits: useful if
developis protected; then Push and the Merge Request in GitLab). - Pull / Push, branches (create, switch, compare, delete), merge, stash and server access (token, password or SSH key) in the ⋮ menu.
- The state is checked every 20 seconds; the tree keeps the folders you opened.
9. Tools
- Compare in several databases (Ctrl+Shift+E): runs a query in several databases or servers and compares.
- Compare schemas: differences in tables, views, procedures and functions between two databases, with a synchronization script that opens without running.
- Clone / synchronize table: creates the table in the target and copies the rows, or synchronizes it by the key (insert, update and, if asked, delete). It shows the plan and the script before changing anything.
- Clone several tables: check the tables and a method for each (create and copy, structure only, insert the missing ones, synchronize, make equal to source). They are copied one at a time, parent tables first; you can pause, stop and resume.
- Clone whole database: copies the whole database (schemas, types, sequences, tables, indexes, keys, views, procedures, functions, triggers) with the data in parts of N rows, a pause between parts and resume where it left off if it is cut. The target database is created or must be empty. Users and permissions are not copied.
- Back up (BACKUP) and Restore (RESTORE) a database: the .bak paths are on the server. Restore never touches system databases and, to overwrite a database, you must type its name.
- Scheduled tasks: run a query and save the result to Excel or CSV at a time (every day or some days) or every N hours. They run with the program open; if the time passed, they ask on opening. Installed on Linux, they can also run with the program closed (cron).
- Server monitor, SQL Server Agent jobs, Query builder, import CSV/Excel, generate test data, document the database and diagrams.
10. Settings and files
-
☰ → Theme (light, dark and others) and Language. ☰ → Open settings shows
ajustes.json. -
Linux: profiles and settings in
~/.config/colibri-sql, history in~/.local/share/colibri-sql, exports inDocuments/COLIBRI-SQL. -
Windows:
%APPDATA%\COLIBRI SQL(in the portable version, thedatosfolder next to the program). -
Profile passwords are saved in
conexiones.jsonwith permissions for your user only: protect that folder and its backups.
11. Keyboard shortcuts
| Shortcut | Action |
|---|---|
| F5 · Ctrl+E | Run all or the selection |
| F8 · Ctrl+Enter | Run the statement at the cursor |
| Ctrl+L | Execution plan |
| Esc | Cancel the execution |
| Ctrl+N · Ctrl+Shift+N | New query · Connect |
| Ctrl+O · Ctrl+S · Ctrl+Shift+S | Open · Save · Save as |
| Ctrl+W | Close the tab |
| Ctrl+Page Up · Ctrl+Page Down | Previous · next tab |
| Ctrl+Shift+A | List of all tabs |
| Ctrl+B | Show or hide the side panel |
| Ctrl+R | Show or hide the results |
| Ctrl+I | AI assistant |
| Ctrl+Space · Tab | Autocomplete · expand * or snippet |
| Ctrl+/ | Comment or uncomment lines |
| Ctrl+K | Format SQL |
| Shift+Alt+arrows | Column editing (also Shift+Alt+drag) |
| Ctrl+Z · Ctrl+Y | Undo · redo (also Ctrl+Shift+Z) |
| Ctrl+F · F3 | Find · next |
| Ctrl+G · Ctrl+P | Go to line · Go to object |
| F12 · Alt+F7 · Ctrl+Q | Definition · Where used · Quick documentation |
| Ctrl+H | Query history |
| Ctrl+Shift+F · Ctrl+Shift+E | Search in database · Compare in several databases |
| Ctrl+Shift+O | Script outline |
| F9 · F10 · Shift+F5 | Breakpoint · step · stop debugging |
| F1 | What each bar button does |
12. Troubleshooting
- It does not connect: check the Connection log; each step shows where it failed. If the server is behind a VPN, connect it first.
- SSH tunnel: for it to work without asking (for example in scheduled tasks) use an SSH key without a passphrase.
- Domain login rejected with error 17892: the server has a logon trigger that rejects the connection; the server administrator solves it.
- «Database in use» (3101) when restoring: check «Close open connections» or close them yourself.
-
Permissions: backing up requires
db_backupoperator; restoring and creating databases,dbcreatororsysadmin; cloning, read permissions on the source and create permissions on the target. -
Limited mode or «Could not connect to the license server»: the trial and the activation need internet once (if you use a proxy, set it in the
HTTPS_PROXYvariables). In ☰ → License… click Check now. «Already active on another PC»: release it on that PC or write to support with the identifier shown in the window. -
The program closes or fails: on Linux errors are kept in
~/.cache/colibri-sql.log.