Skip to main content
This guide will help you connect to a database and perform your first queries in Zequel.

​
Your First Connection

1

Open Zequel

Launch Zequel from your applications folder. You’ll see the welcome screen with options to create a new connection.
2

Create a new connection

Click New Connection or press Cmd+N (macOS) / Ctrl+N (Windows/Linux).The connection dialog will appear with options for all supported database types.
3

Select your database type

Choose your database from the available options:
  • PostgreSQL - Port 5432 (default)
  • MySQL - Port 3306 (default)
  • MariaDB - Port 3306 (default)
  • SQLite - Local file-based database
  • DuckDB - Local file-based analytics database
  • MongoDB - Port 27017 (default)
  • Redis - Port 6379 (default)
  • ClickHouse - Port 8123 (default)
  • SQL Server - Port 1433 (default)
4

Enter connection details

Fill in the connection information based on your database type:

​
For Server-Based Databases (PostgreSQL, MySQL, etc.)

  • Name: A friendly name for this connection (e.g., “Production DB”)
  • Host: The server hostname or IP address
  • Port: The database port (pre-filled with defaults)
  • Database: The database name to connect to
  • Username: Your database username
  • Password: Your database password

​
For File-Based Databases (SQLite, DuckDB)

  • Name: A friendly name for this connection
  • File Path: Click Browse to select your database file, or enter a path to create a new database
For SQLite and DuckDB, if the file doesn’t exist, Zequel will create a new database at the specified path.
5

Configure advanced options (optional)

Expand the Advanced section to configure:

​
SSL/TLS Connection

  • Enable Use SSL/TLS for encrypted connections
  • Choose SSL mode: disable, prefer, require, verify-ca, or verify-full
  • Upload SSL certificates if required

​
SSH Tunnel

  • Enable Use SSH Tunnel to connect through a bastion/jump host
  • Enter SSH host, port, and username
  • Choose authentication: Password or Private Key
  • Provide credentials or upload your private key file

​
Connection Metadata

  • Environment: Tag as production, staging, development, testing, or local
  • Color: Assign a color for quick visual identification
  • Folder: Organize connections into folders
6

Test and save

Click Test Connection to verify your settings.If the test succeeds, click Save to store the connection. If it fails, check the error message and verify your credentials and network settings.
Passwords are stored securely in your operating system’s keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
7

Connect to the database

Click the connection in the sidebar to establish the connection. You’ll see the database schema browser appear with all your databases, tables, and views.

​
Quick Connection Examples

​
Local SQLite Database

1

Select SQLite

Choose SQLite as the database type
2

Create or open a file

  • To create a new database: Enter /Users/yourname/my-database.db (macOS/Linux) or C:\Users\yourname\my-database.db (Windows)
  • To open an existing database: Click Browse and select your .db file
3

Connect

Click Save and then click the connection to open it

​
Local PostgreSQL

1

Select PostgreSQL

Choose PostgreSQL as the database type
2

Enter local connection details

  • Host: localhost or 127.0.0.1
  • Port: 5432
  • Database: postgres (or your database name)
  • Username: postgres (or your username)
  • Password: Your PostgreSQL password
3

Save and connect

Click Test Connection, then Save, then click the connection to open it

​
Remote MySQL with SSH Tunnel

1

Select MySQL

Choose MySQL as the database type
2

Enter database details

  • Host: localhost (the host as seen from the SSH server)
  • Port: 3306
  • Database: Your database name
  • Username: Your MySQL username
  • Password: Your MySQL password
3

Configure SSH tunnel

In the Advanced section, enable Use SSH Tunnel:
  • SSH Host: Your bastion/jump server hostname or IP
  • SSH Port: 22
  • SSH Username: Your SSH username
  • Auth Method: Choose Password or Private Key
  • Provide your SSH credentials
4

Test and connect

Click Test Connection to verify both SSH and database connections work

​
Exploring Your Database

Once connected, you can start exploring:

​
Schema Browser

The left sidebar shows your database structure:
  • Databases: Expand to see all databases on the server
  • Tables: Click a table to view its structure and data
  • Views: Browse database views
  • Routines: View stored procedures and functions
  • Triggers: See database triggers
  • Sequences: Browse sequences (PostgreSQL)
  • Extensions: View installed extensions (PostgreSQL)
Use Cmd+L (macOS) or Ctrl+L (Windows/Linux) to quickly focus the schema search box and find tables, views, or other objects.

​
Viewing Table Data

1

Select a table

In the schema browser, click any table name
2

Browse the data grid

The main panel shows the table data with:
  • Virtual scrolling for large datasets
  • Column sorting (click column headers)
  • Column filtering (click filter icon)
  • Column resize and reorder (drag column headers)
3

Edit data in-cell

Double-click any cell to edit its value. Changes are tracked and shown in the status bar.
4

Commit or discard changes

  • Commit: Press Cmd+S (macOS) / Ctrl+S (Windows/Linux) or click the commit button
  • Discard: Press Cmd+Shift+Backspace or click the discard button

​
Running Your First Query

1

Open the query editor

Click New Query Tab or press Cmd+T (macOS) / Ctrl+T (Windows/Linux)
2

Write your SQL query

Type your query in the Monaco editor. You’ll get:
  • Syntax highlighting
  • Auto-completion for table and column names
  • SQL keyword suggestions
Example:
SELECT * FROM users WHERE created_at > '2024-01-01' LIMIT 100;
3

Execute the query

Press Cmd+Enter (macOS) / Ctrl+Enter (Windows/Linux) to run the entire query, or Cmd+Shift+Enter to run only the selected text.
4

View results

Results appear in the data grid below the editor, showing:
  • All columns and rows returned
  • Execution time
  • Number of rows affected

​
Using SQL Snippets

Zequel includes 30+ pre-built SQL snippets for each database dialect:
1

Open the query editor

Create a new query tab if you haven’t already
2

Access snippets

Start typing select, insert, create, or other SQL keywords and press Ctrl+Space to see snippet suggestions
3

Insert a snippet

Select a snippet from the auto-complete menu. Snippets include:
  • SELECT statements with common patterns
  • INSERT, UPDATE, DELETE templates
  • CREATE TABLE, CREATE INDEX examples
  • Database-specific queries (CTEs, window functions, etc.)

​
Command Palette

Access all Zequel features quickly with the command palette:
1

Open the command palette

Press Cmd+K or Cmd+P (macOS) / Ctrl+K or Ctrl+P (Windows/Linux)
2

Search for actions

Type to filter available commands:
  • Open tables, views, or other schema objects
  • Navigate to different sections
  • Execute common operations
3

Execute

Press Enter to execute the selected command

​
Keyboard Shortcuts

Master these essential shortcuts for efficient workflow:

​
Tabs

  • Cmd+T / Ctrl+T - New query tab
  • Cmd+W / Ctrl+W - Close current tab
  • Cmd+1-9 - Switch to tab 1-9
  • Cmd+] / Ctrl+Tab - Next tab
  • Cmd+[ / Ctrl+Shift+Tab - Previous tab

​
Query Editor

  • Cmd+Enter / Ctrl+Enter - Execute query
  • Cmd+Shift+Enter - Execute selection
  • Cmd+Shift+F / Ctrl+Shift+F - Format SQL
  • Cmd+S / Ctrl+S - Commit changes
  • Cmd+L / Ctrl+L - Focus sidebar search
  • Cmd+K / Ctrl+K - Open command palette
  • Cmd+R / Ctrl+R - Refresh data
Press Cmd+Shift+? (macOS) / Ctrl+Shift+? (Windows/Linux) or F1 to see all keyboard shortcuts.

​
Next Steps

Interface Overview

Learn about all UI components and features

Working with Tables

Master data grid features and table operations

Query Editor

Advanced query editor features and tips

Import & Export

Import and export data in multiple formats

Build docs developers (and LLMs) love

Get started for freeTalk to us