Last updated: 2026-04-04

Connections

Connect to SQL Server, Azure SQL, PostgreSQL, MySQL, MariaDB, Oracle, and SQLite databases with Jam SQL Studio. This guide covers supported databases, authentication methods, connection options, and managing your saved connections.

Supported Databases

Jam SQL Studio supports five major database platforms:

Creating a Connection

To create a new database connection:

1. Click the + button in the sidebar, or
2. Go to File > New Connection, or
3. Press Cmd+Shift+N (macOS) / Ctrl+Shift+N (Windows/Linux)

After you save a new connection, it appears at the top of the Recent list in the Saved Connections dialog and at the top of the connections list on the Start Page.

Connection Settings

Fill in the following fields to configure your connection:

• Connection Name - A friendly name for this connection (e.g., "Production DB", "Dev Server")
• Server/Host - The database server address (e.g., localhost, localhost\\SQLEXPRESS, 192.168.1.100, myserver.database.windows.net)
• Port - Server port (defaults: SQL Server 1433, PostgreSQL 5432, MySQL 3306, Oracle 1521). For SQL Server named instances (e.g., localhost\\SQLEXPRESS), leave Port blank to auto-resolve the instance port (requires SQL Browser).
• Database - The default database to connect to (optional)
• Authentication - Choose your authentication method

Authentication Methods

Jam SQL Studio supports multiple authentication methods depending on your database type.

SQL Server Authentication

Use a SQL Server login and password:

1. Select SQL Server Authentication from the dropdown
2. Enter your Username (e.g., sa or your login name)
3. Enter your Password
4. Check Remember Password to save credentials securely

Windows Authentication

Use your Windows credentials (available on Windows only):

1. Select Windows Authentication from the dropdown
2. Your current Windows user will be used automatically
3. No username or password required

Azure Entra ID (Azure Active Directory)

For Azure SQL Database and Azure SQL Managed Instance, Jam SQL Studio offers two Entra sign-in modes:

Microsoft Entra ID (Interactive Browser) — recommended

1. Select Microsoft Entra ID (Interactive Browser) from the Authentication dropdown
2. Click Connect — Jam SQL Studio opens your default browser to a standard Microsoft sign-in page
3. Complete the Microsoft login (including MFA if required) in your browser and return to Jam SQL Studio

Use this mode when your tenant’s Conditional Access “Authentication flows policy” blocks the Device Code flow, or when you simply prefer a normal browser sign-in.

Microsoft Entra ID (Device Code)

1. Select Microsoft Entra ID (Device Code) from the Authentication dropdown
2. Click Connect — Jam SQL Studio shows a one-time user code and verification URL
3. Open the URL in any browser, paste the code, and complete the Microsoft login

Tenant ID (optional)

For both Entra modes you can specify a Tenant ID (directory ID GUID or domain like contoso.com). Set this when you belong to multiple tenants or when signing in with a guest / personal Microsoft account — otherwise leave it empty to use common.

PostgreSQL Authentication

For PostgreSQL connections:

• Password - Standard username/password authentication
• SSL/TLS - Encrypted connections with optional client certificates

SSL Connection Options

• SSL Mode - Choose from: disable, require, verify-ca, verify-full
• CA Certificate - Path to the certificate authority file
• Client Certificate - Path to client certificate (for mutual TLS)
• Client Key - Path to client private key

MySQL / MariaDB Authentication

For MySQL and MariaDB connections:

• Password - Standard username/password authentication (default user: root)
• No Password - Connect without a password (for local development servers)

SSL Connection

Enable the SSL checkbox for encrypted connections. This is recommended for remote MySQL servers and required by many cloud-hosted MySQL services.

Oracle Authentication

For Oracle Database connections:

• Password - Standard username/password authentication (default port: 1521)
• SSL/TLS - Encrypted connections via the SSL checkbox
• Wallet (mTLS) - For Oracle Autonomous Database (ADB) cloud connections using a wallet directory

Connection String Types

Oracle supports three connection string formats:

• EZConnect (default) - Simple host:port/service_name format
• TNS Descriptor - Full TNS connection string for advanced configurations
• TNS Alias - Named alias resolved from a tnsnames.ora file

Service Name vs SID

By default, connections use a Service Name. Toggle to SID if your database uses a System Identifier instead. Modern Oracle databases (12c+) prefer service names.

Discovering Service Names (Oracle only)

If you don't know the exact service name registered with your Oracle listener, click the Discover button next to the Service Name input (EZConnect mode). Jam SQL Studio will probe the listener at the configured host and port for well-known Oracle service names — including those used by common images such as FREE / FREEPDB1 (Oracle Free 23ai), XE / XEPDB1 (Oracle XE), and ORCL / ORCLCDB / ORCLPDB1 (Enterprise/Standard) — and display any that are currently registered as clickable pills. Click a pill to fill the field.

If the listener is unreachable (firewall, wrong port, database not started), Discover surfaces a listener error instead of a service list. If the database is up but none of the well-known names match, enter your custom service name manually — you can still click Discover afterwards to verify that the listener knows it.

SQLite Connections

SQLite uses file-based storage with no authentication:

1. Select SQLite as the database type
2. Click Browse to select your .sqlite or .db file
3. Click Connect to open the database

Connection Options

Expand the Advanced Options section to configure additional settings:

General Options

• Connection Timeout - Seconds to wait before timing out (default: 15)
• Command Timeout - Seconds to wait for query execution (default: 30)

Security Options (SQL Server)

• Encrypt Connection - Use TLS encryption for data in transit (recommended)
• Trust Server Certificate - Accept self-signed certificates (development only)

Managing Connections

Jam SQL Studio saves your connections for quick access.

Saving Connections

1. Fill in all connection details
2. Enter a meaningful Connection Name
3. Click Test Connection to verify settings
4. Click Save to store the connection

Editing Connections

1. Right-click a saved connection in the sidebar
2. Select Edit Connection
3. Modify settings as needed
4. Click Save to update

Reconnecting

Right-click a connection and select Reconnect to fully rebuild it — Jam SQL Studio closes the connection's pools, resets any cached sign-in state, and connects fresh. Use it when a connection misbehaves after a network change, VPN reconnect, laptop sleep, or an expired Microsoft Entra session, instead of restarting the app.

Deleting Connections

1. Right-click a saved connection in the sidebar
2. Select Delete Connection
3. Confirm the deletion

Testing Connections

Before saving, click Test Connection to verify:

• Network connectivity to the server
• Authentication credentials are valid
• Selected database exists and is accessible

Object Explorer

Once connected, the Object Explorer shows your database structure:

Navigating the Tree

• Server - Top-level connection node showing server name
• Databases (or Schemas for Oracle) - List of databases/schemas on the server
• Tables - Database tables with column details
• Views - Database views
• Stored Procedures - Programmable database routines
• Functions - User-defined functions
• Packages, Sequences, Synonyms, DB Links, Materialized Views, Types, Directories - Oracle-specific object types

Object Actions

Right-click objects for context menu actions:

• Tables - Select Top 1000, Edit Top 200, Design Table, Script as CREATE/DROP
• Views - Select Top 1000, Script as CREATE/ALTER/DROP
• Procedures - Execute, Script as CREATE/ALTER/DROP
• Functions - Script as CREATE/ALTER/DROP

Troubleshooting

Connection Refused

• Verify the server address and port are correct
• Check that the database server is running
• Ensure firewall allows connections on the database port

SSMS connects but Jam doesn't (Windows local SQL Server)

• SSMS may be using Shared Memory / Named Pipes, while Jam’s direct Node driver connection uses TCP/IP. Jam retries some local connections via SQL Tools Service, but enabling TCP/IP for your instance in SQL Server Configuration Manager (and restarting SQL Server) is the most compatible setup.
• For named instances (e.g., localhost\\SQLEXPRESS), ensure the SQL Server Browser service is running (UDP 1434) or set the explicit TCP port in Jam.
• On Windows, Jam can retry MSSQL connections using SQL Tools Service when the direct driver connection fails, but driver-only features still require TCP/IP.

Authentication Failed

• Double-check username and password
• Verify the user has permission to connect
• For Windows Auth, ensure proper domain configuration

Oracle Connection Issues

• ORA-12541 (No Listener) - Verify the Oracle listener is running on the target host and port
• ORA-12514 (Service Not Found) - Check the service name is correct. Use lsnrctl status on the server to list available services
• ORA-01017 (Invalid Credentials) - Verify username and password. Oracle usernames are case-insensitive but passwords are case-sensitive
• TNS Alias Not Found - Ensure the TNS Admin directory path is correct and contains a valid tnsnames.ora file

Azure SQL Firewall

• Add your client IP address to the Azure SQL firewall rules
• Or enable "Allow Azure services" in the Azure portal

Connection Colors

Assign a color to each connection to visually distinguish environments at a glance — for example, red for production and green for development.

Setting a Connection Color

1. Open the connection dialog (create new or edit existing)
2. Choose from 8 preset color swatches below the connection name: red, orange, amber, green, teal, blue, indigo, purple
3. Click a swatch to select it (a checkmark appears), or click None to clear
4. Save the connection — the color persists across sessions

Where Colors Appear

• Connection card — a colored left border accent on the sidebar connection card
• Tab bar — active tabs show a 3px bottom border in the connection color; inactive tabs show a subtle 2px border
• Status bar — a very subtle background tint of the connection color behind the status bar

Colors update live — changing a connection's color immediately updates all open tabs using that connection.

When a Connection Drops

If a workspace tab's database connection goes offline, a banner appears at the top of the tab area with a Connect button. The banner shows the connection name and engine so you can tell at a glance which link is affected.

If you had just triggered an action when the connection was lost — Run Query, Refresh from DB, Sync Data, a Schema Compare or Data Compare run, or a Table Explorer save or preview — the button reads Connect and <action> and reruns the action automatically once you reconnect. No need to repeat the original gesture.

Tabs with an inactive connection also show a small amber dot next to the tab label for at-a-glance visibility across the tab strip. Dismiss the banner with the × button in the top-right corner if you don't want to reconnect right away.

SSH Tunneling

SSH tunneling routes a database connection through an SSH bastion so the database itself doesn’t need to be publicly reachable. Use it when your database sits behind a corporate firewall or cloud security group that only accepts connections from a specific jumphost.

SSH tunneling is available for all database engines except SQLite.

Enabling SSH Tunneling

1. Open the New Connection dialog (or edit an existing connection).
2. Expand the SSH Tunnel section and check Connect via SSH tunnel.
3. Fill in SSH Host, SSH Port (default 22), and SSH User.
4. Choose an Auth method and provide credentials (see below).
5. Click Test Connection to verify both the SSH and database legs before saving.

Authentication Methods

• SSH agent — uses identities already loaded in your running SSH agent (ssh-add -l). No credentials to enter; works on macOS, Linux, and Windows with a running agent.
• Private key — point to a key file (~/.ssh/id_rsa, id_ed25519, etc.). If the key has a passphrase, enter it in the Passphrase field; check Save in keychain to avoid re-entering it on every connect.
• Password — SSH password auth for servers that support it. Check Save in keychain to store it securely.

~/.ssh/config Auto-fill

Start typing a Host alias from your ~/.ssh/config file into the SSH Host field. Jam SQL Studio reads your SSH config and suggests matching aliases; selecting one auto-fills the host address, SSH user, port, and private key path. Aliases that use ProxyJump are shown as suggestions but multi-hop tunnels are not supported yet — only a single SSH bastion is followed.

Stepwise Test Connection

Clicking Test Connection when an SSH tunnel is configured runs two checks in sequence and reports each one separately:

1. SSH connection — authenticates to the bastion and opens the forwarded port.
2. Database connection — connects through the tunnel to the database server.

If the SSH leg fails (wrong host, key rejected, firewall blocking port 22), the error is shown before the database check even runs, so you can tell immediately which side needs attention.

Limitations

• Single bastion only — multi-hop tunnels (ProxyJump chains) are not supported.
• No in-app SSH key generation — generate keys with ssh-keygen and point Jam SQL Studio at the resulting file.
• The tunnel stays open for the lifetime of the connection; closing or disconnecting tears it down automatically.

Frequently asked questions