Connection Management

Tablen provides comprehensive connection management for organizing, securing, and maintaining your database connections.

Creating a New Connection

Open the New Connection dialog using one of these methods:

Press Cmd+Shift+N
Click the "+" button in the sidebar
Use the Command Palette (Cmd+Shift+P) and search for "New Connection"
Use the URL scheme: tablen://new-connection

Connection Fields

Field	Description	Required
Name	Display name for the connection	Yes
Type	Database engine (PostgreSQL, MySQL, SQLite, etc.)	Yes
Host	Server hostname or IP address	Yes (network DBs)
Port	Server port (auto-filled with default)	Yes (network DBs)
Database	Database name	Yes (except Redis, file-based DBs)
Username	Authentication username	Depends on DB
Password	Authentication password (stored in Keychain)	Depends on DB
SSL	Enable SSL/TLS encryption	No
SSL Skip Verify	Skip certificate verification	No
Color	Connection color indicator	No
Group	Organizational group	No
Environment	DEV, STG, PROD, LOCAL, or TEST	No (defaults to DEV)
Read Only	Prevent write operations	No
Safe Mode	Require confirmation for destructive queries	No (auto-enabled for PROD)

File-Based Databases

For SQLite, libSQL, and DuckDB, the connection form shows a file picker instead of host/port fields.

Connection Groups

Groups help organize connections by project, team, or any custom category.

Creating a Group

Right-click in the sidebar connections area
Select "New Group"
Enter a group name and optional icon
Drag connections into the group

Managing Groups

Edit Group: Right-click a group header and select "Edit Group..."
Delete Group: Right-click a group header and select "Delete Group"
Reorder: Groups are sorted by their sort order
Drag and Drop: Drag connections between groups by dropping on the group header

Environment Tags

Every connection can be tagged with an environment:

Environment	Tag	Color	Safe Mode Default
Development	DEV	Green	Off
Staging	STG	Yellow	Off
Production	PROD	Red	On
Local	LOCAL	Blue	Off
Testing	TEST	Purple	Off

Production connections have Safe Mode enabled by default to prevent accidental data loss.

Safe Mode

Safe Mode adds confirmation dialogs before executing potentially destructive queries.

Activation

Per-Connection: Toggle in connection settings
Global: Enable in Settings > General > Safety for all connections
Auto: Production environment connections have Safe Mode enabled automatically

Confirmation Levels

Query Type	Confirmation
DROP, TRUNCATE, DELETE without WHERE	Type the connection name to confirm
UPDATE, ALTER, DELETE with WHERE	Simple confirm/cancel dialog
INSERT INTO...SELECT	Simple confirm/cancel dialog
CREATE, simple INSERT, SELECT	No confirmation needed

Read-Only Mode

Enable "Read Only" on a connection to completely block all write operations (INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE).

SSH Tunnel

Connect to databases behind firewalls or on private networks using SSH tunneling.

Configuration

Enable "SSH Tunnel" in the connection settings
Enter SSH host, port (default: 22), and username
Choose authentication type:
- Password: Enter your SSH password
- Key File: Select your SSH private key file (e.g., ~/.ssh/id_rsa)

How It Works

Tablen establishes an SSH connection to the specified host, then creates a local port forward to the database server. The database connection is routed through this secure tunnel.

Proxy Support

Connect through a proxy server when direct connections are not possible.

Proxy Types

None: Direct connection (default)
HTTP Proxy: Standard HTTP proxy with optional authentication
SOCKS5 Proxy: SOCKS5 proxy with optional authentication
HTTP Tunnel: HTTP CONNECT tunnel with configurable tunnel URL

Proxy Fields

Field	Description
Host	Proxy server hostname
Port	Proxy server port (default: 8080)
Username	Proxy authentication username
Password	Proxy authentication password
Tunnel URL	HTTP Tunnel endpoint URL

Connection Health Monitoring

Tablen continuously monitors the health of active connections:

Status	Indicator	Description
Healthy	Green	Connection is active and responsive
Slow	Yellow	Connection is active but has high latency (shows latency in ms)
Disconnected	Red	Connection has been lost

Health status is displayed in the sidebar next to each connected database.

Connection Import

Import connections from other SQL clients:

Open the Import dialog from the sidebar menu
Select the source application format
Choose the import file
Review and confirm the connections to import

Supported import formats depend on the source application's export format.

Connection Sharing

Share connections with team members (requires Team plan):

Right-click a connection in the sidebar
Select "Share Connection"
The connection details (excluding passwords) are shared with your team

Shared connections appear in the sidebar with a team indicator. When connecting to a shared connection, you'll be prompted to enter your own password.

Connection Duplication

Quickly duplicate an existing connection:

Right-click a connection in the sidebar
Select "Duplicate"
A new connection is created with the same settings and a "(Copy)" suffix
Modify the duplicated connection as needed

iCloud Sync

Sync connections and saved queries across your Mac devices:

Go to Settings > General > iCloud Sync
Enable "Sync connections and queries across devices"
Requires being signed into iCloud in System Settings

Important Notes

Passwords are never synced -- they remain in your local Keychain only
Conflict resolution uses the updatedAt timestamp
Manual sync is available via the "Sync Now" button
Sync status and last sync time are displayed in Settings

Password Security

All database passwords are stored in the macOS Keychain:

Passwords are never written to JSON files or UserDefaults
Each connection's password is stored as a separate Keychain item
Keychain errors are handled explicitly with user-visible error messages
The "Delete All My Data" function in Settings also clears Keychain entries

Connection Persistence

Connections are saved to:

~/Library/Application Support/DBClient/connections.json

Groups are saved to:

~/Library/Application Support/DBClient/groups.json

Connections do not auto-connect on app launch. You must manually connect by double-clicking or right-clicking a connection.

Connecting via URL Scheme

Connect to saved connections using the Tablen URL scheme:

By name: tablen://connect?name=MyDatabase
By ID: tablen://connect?id=<uuid>

See the URL Scheme documentation for more details.