Skip to main content
Zequel allows you to create and manage connections to multiple database types with support for SSL/TLS encryption, SSH tunneling, and connection organization.

​
Supported Databases

Zequel supports 9 database types:
  • PostgreSQL - Full-featured relational database
  • MySQL - Popular open-source relational database
  • MariaDB - MySQL fork with enhanced features
  • SQL Server - Microsoft’s enterprise database
  • SQLite - Embedded file-based database
  • DuckDB - In-process analytical database
  • ClickHouse - Column-oriented OLAP database
  • MongoDB - Document-oriented NoSQL database
  • Redis - In-memory key-value store

​
Creating a Connection

Connections are created and stored in Zequel’s local SQLite database. Each connection configuration includes:

​
Basic Configuration

​
name
string
required
Display name for the connection
​
type
DatabaseType
required
Database type (postgresql, mysql, mariadb, sqlserver, sqlite, duckdb, clickhouse, mongodb, redis)
​
host
string
Database server hostname or IP address (not required for SQLite/DuckDB)
​
port
number
Database server port. Defaults:
  • PostgreSQL: 5432
  • MySQL/MariaDB: 3306
  • SQL Server: 1433
  • MongoDB: 27017
  • Redis: 6379
  • ClickHouse: 8123
​
database
string
Database/schema name to connect to
​
username
string
Authentication username
​
password
string
Authentication password (stored securely)

​
File-Based Databases

For SQLite and DuckDB:
​
filepath
string
required
Absolute path to the database file

​
Security Options

​
ssl
boolean
Enable SSL/TLS encryption (see SSL/TLS Configuration)
​
ssh
SSHConfig
SSH tunnel configuration (see SSH Tunneling)
​
trustServerCertificate
boolean
SQL Server only: Accept self-signed certificates

​
Connection Management

​
Saving Connections

Connections are persisted using the ConnectionsService: 
interface SavedConnection {
  id: string
  name: string
  type: DatabaseType
  host: string | null
  port: number | null
  database: string
  username: string | null
  filepath: string | null
  ssl: boolean
  sslConfig: SSLConfig | null
  ssh: SSHConfig | null
  color: string | null
  environment: ConnectionEnvironment | null
  folder: string | null
  trustServerCertificate: boolean
  sortOrder: number
  createdAt: string
  updatedAt: string
  lastConnectedAt: string | null
}

​
Organizing Connections

Connections can be organized with:
1

Folders

Group connections into named folders for better organization
// Get all folder names
const folders = connectionsService.getFolders()

// Move connection to folder
connectionsService.updateFolder(connectionId, 'Production')

// Rename folder
connectionsService.renameFolder('Old Name', 'New Name')
2

Environment Labels

Tag connections with environment types:
  • development
  • staging
  • production
  • testing
3

Custom Colors

Assign color codes for visual identification
4

Sort Order

Manually arrange connections with drag-and-drop
connectionsService.updatePositions([
  { id: 'conn1', sortOrder: 0, folder: 'Production' },
  { id: 'conn2', sortOrder: 1, folder: 'Production' }
])

​
Connection Sessions

When you connect to a database, Zequel creates a session with a unique ID separate from the saved connection ID: 
// Connect and get session ID
const sessionId = await connectionManager.connect(config)

// Session tracks:
// - Active database driver instance
// - SSH tunnel (if configured)
// - Health check interval
// - Connection configuration

​
Session Management

The ConnectionManager handles:
  • Health Checks - Automatic ping every 30 seconds (PostgreSQL, MySQL, MariaDB, SQL Server, MongoDB, Redis)
  • Auto-Reconnect - Up to 5 reconnection attempts with exponential backoff (1s, 2s, 4s, 8s, 16s)
  • SSH Tunnels - Lifecycle management tied to session
  • Query Logging - All queries logged with execution time
SQLite, DuckDB, and ClickHouse skip health checks as they use different connection models

​
Connection Status Events

Zequel emits real-time connection status events: 
type ConnectionStatus = 
  | 'connected'
  | 'disconnected'
  | 'reconnecting'
  | 'error'

emitConnectionStatus({
  connectionId: sessionId,
  status: ConnectionStatusType.Connected
})

​
Testing Connections

Before saving, test the connection to verify credentials and network access: 
const result = await connectionManager.testConnection(config)

interface TestConnectionResult {
  success: boolean
  error?: string
  latency?: number          // Connection time in ms
  serverVersion?: string    // Database version
  serverInfo?: Record<string, string>
  sshSuccess?: boolean      // SSH tunnel status
  sshError?: string         // SSH error if failed
}

const result = await testConnection({
  type: DatabaseType.PostgreSQL,
  host: 'localhost',
  port: 5432,
  database: 'mydb',
  username: 'postgres',
  password: 'password'
})

// Returns server info:
// - Encoding
// - Timezone
// - Max Connections

​
Connection Lifecycle

1

Configure

Create connection configuration with credentials and optional SSH/SSL settings
2

Test

Verify connection parameters work before saving
3

Save

Persist connection to local database (passwords stored securely)
4

Connect

Establish session with database driver
  • Create SSH tunnel if configured
  • Initialize database driver (pg, mysql2, mssql, etc.)
  • Start health check interval
  • Wrap driver for query logging
5

Use

Execute queries, browse schema, manage data
6

Disconnect

Close session and cleanup resources
  • Stop health checks
  • Close database connection
  • Close SSH tunnel
  • Remove from connection pool

​
Error Handling

Connection errors are handled gracefully:
If a connection is lost, Zequel will:
  1. Emit reconnecting status event
  2. Attempt up to 5 reconnections with exponential backoff
  3. Recreate SSH tunnel if needed
  4. Emit connected on success or error if all attempts fail
To manually trigger reconnection: 
const success = await connectionManager.reconnect(sessionId)

​
Multiple Connections

You can open multiple sessions to the same saved connection: 
// Each session gets a unique ID
const session1 = await connectionManager.connect(config)
const session2 = await connectionManager.connect(config)

// Find all sessions for a saved connection
const sessions = connectionManager.getSessionsForSavedConnection(savedId)

​
Best Practices

Group connections by environment, project, or client to keep your workspace organized.
Always test connections before saving to catch configuration errors early.
Tag production databases to avoid accidental modifications.
Use SSH tunnels instead of exposing databases directly to the internet.
Enable SSL with certificate verification for production databases.

SSH Tunneling

Securely connect to remote databases through SSH

SSL/TLS Configuration

Encrypt database connections with SSL/TLS

Build docs developers (and LLMs) love

Get started for freeTalk to us