Last updated: 2026-07-26

Connections

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

Supported Databases

Jam SQL Studio supports six database engines:

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)
• Limit connection to selected database - Scopes the whole app to that one database (see below). Every engine except SQLite.
• Authentication - Choose your authentication method

Several fields (Server/Host, Username, Database) fill a sensible per-engine default when you press Tab out of them while empty — for example localhost for PostgreSQL or localhost\\SQLEXPRESS for SQL Server. If you press Save with a required field still empty, Jam scrolls to it, focuses it, and shows a “Press Tab to fill” hint naming that default.

Limit Connection to Selected Database

Servers with hundreds of databases make every tree and dropdown noisy when you only ever work in one of them. Below the Database field (every engine except SQLite, which has no database selector), a Limit connection to selected database checkbox scopes the connection inside Jam SQL Studio to that one database. The checkbox stays disabled until a database is actually selected — scoping to “the selected database” means nothing while the field is blank — and the ⓘ next to it explains the rule in place: hover it, or click it to keep the explanation open while you read.

What the limit covers once it is on:

• Object Explorer lists only that database, with no System Databases folder — even when the database is itself system-named, like master.
• Every database picker and dropdown in the app offers only that database — including Schema Compare, Data Compare, migration, and Clone dialogs.
• The Job Scheduler step-database dropdown (SQL Server) offers only that database.
• AI workspace schema export exports only that database, so agents never see the rest of the server.

Database names are matched case-insensitively, so typing sales for a server that reports Sales still resolves. Turn the limit off the same way you turned it on — open Edit Connection and untick the box.

Changing the checkbox on an existing connection takes effect immediately in the database pickers, which re-read the list every time they open. An Object Explorer tree that is already expanded keeps its cached children, so right-click the connection and choose Refresh to make the tree match the new setting.

Related: even without the limit, each database dropdown in the Schema Compare, Data Compare, and migration dialogs defaults to that connection's saved database rather than the first one alphabetically, so you usually just confirm it before comparing.

Paste a Connection String

Already have a working connection string — from an app config, a teammate’s message, or a cloud console’s “connect” page? Paste it instead of re-typing every field. A Paste a connection string box sits at the top of the New Connection dialog. On paste it detects the format, switches the engine, and fills every field it can, then reports exactly which fields it filled in a confirmation line. Nothing is auto-connected — you review the form and hit Test Connection / Save as usual.

Need to inspect or translate a connection string outside the app? The free in-browser Connection String Converter parses the same formats and converts between them.

You can also run New Connection from Clipboard from the command palette (Cmd/Ctrl+K): it reads your clipboard, opens the dialog, and prefills it in one step.

Supported Formats

• ADO.NET / SqlClient (SQL Server) — Server=tcp:host,1433;Database=db;User Id=sa;Password=…;Encrypt=True. Recognises Server/Data Source, Database/Initial Catalog, User Id/UID, Password/PWD, Encrypt, TrustServerCertificate, and Integrated Security/Trusted_Connection (→ Windows authentication).
• URL style (PostgreSQL / MySQL) — postgres://user:pass@host:5432/db?sslmode=require, mysql://root:[email protected]:3306/shop. URL-encoded credentials (%40 → @) are decoded.
• libpq keywords (PostgreSQL) — host=host port=5432 dbname=db user=app sslmode=require.
• JDBC (all four network engines) — jdbc:sqlserver://…, jdbc:postgresql://…, jdbc:mysql://…, and jdbc:oracle:thin:@//host:1521/SERVICE (service name) or @host:1521:SID (SID).
• Oracle EZConnect — user/pass@host:1521/SERVICE or a bare host:1521/SERVICE.
• SQLite path / URL — an absolute file path ending in .db, .sqlite, or .sqlite3, or a file:///… / sqlite:///… URL.

A partial parse fills what it recognises and names any keys it couldn’t map, so you can finish the rest by hand. A password-less *.database.windows.net host prompts a Microsoft Entra suggestion. Passwords prefill masked and are only stored when you save, through the usual encrypted path — the pasted string itself is never logged, saved, or sent anywhere.

Import Connections from Other Tools

Already have your databases set up in another tool? Jam SQL Studio reads its saved connections directly and imports them in one click — no field-by-field re-entry. Start an import three ways:

• Start page — when a tool’s saved connections are detected, an Import from… card appears; click Review & import.
• Command palette (Cmd/Ctrl+Shift+P) — run Import Connections from… for the tool you want.
• Manage Connections — open the Import… dropdown in the Saved Connections dialog and pick a source. Sources with a saved store on this machine are highlighted.

Jam SQL Studio can import from:

• Database tools — Azure Data Studio, Visual Studio Code (the mssql & PostgreSQL extensions), SQL Server Management Studio, DBeaver, DataGrip and other JetBrains IDEs, TablePlus, MySQL Workbench, Navicat, and pgAdmin.
• Standard config files — Oracle tnsnames.ora, PostgreSQL pg_service.conf, MySQL .my.cnf, and ODBC data sources.
• Your Azure account — the Azure (signed-in account) source lists every ADX cluster, App Insights component, Log Analytics workspace, Azure SQL server/managed instance, and PostgreSQL flexible server your signed-in account can reach. See Browse Azure below.

The review dialog groups connections the way the source tool did (server groups, folders). Tick the ones to import (duplicates you already added are pre-unchecked), then click Import. Nothing auto-connects — import only saves the connections.

Your passwords stay put. Jam SQL Studio never reads another app’s operating-system keychain and never decrypts another tool’s stored passwords. Passwords are only pre-filled from files that are documented as plain text (.pgpass, .my.cnf, pg_service.conf); everywhere else you re-enter them inline in the dialog or on first connect.

Importing from another machine or from an export file? Use Can’t find your file? Browse… inside the dialog to point at the exported file — for example an ADS settings.json, a Navicat .ncx, or a pgAdmin servers.json. Coming specifically from Azure Data Studio? See the full walkthrough: Migrate from Azure Data Studio.

Exporting and Importing Your Own Connections

Moving to a new machine, or handing a teammate the same set of connections? Settings → Backup & Transfer → Saved connections exports the connections you tick to a single file. By default the file holds no passwords — just server, port, database, username, and any SSH bastion, in plain text, so you can open and read exactly what you are about to share. Tick Include saved passwords, protected by a passphrase to also carry your saved passwords and SSH secrets, encrypted with a key derived from a passphrase you type twice (scrypt, then AES-256-GCM) — they are never written to the file in plain text, and there is no recovery if you forget the passphrase.

The exported file can be read back two ways: through Manage Connections → Import… → Jam SQL Studio export (endpoints only, alongside every other import source on this page), or through Settings → Backup & Transfer itself, which is the only path that can also restore the passphrase-protected passwords. Imported connections are always added alongside your existing ones, never merged over them. When the file carries passphrase-protected passwords, those passwords are cryptographically tied to the settings that decide where each credential goes — so a file edited after export (a repointed server, a changed authentication mode, TLS switched off) fails to open rather than silently importing the edit. An endpoints-only export carries no passwords and so no such seal, and neither does a sealed file imported without its passphrase: review what you are importing before you commit. Full details, including what the review list shows: see Moving your saved connections in Getting Started.

Detect Local Databases

Running your development databases in Docker — or, on Windows, a native SQL Server instance? Jam SQL Studio can find them for you. On an explicit click it asks the local Docker Engine which containers are running, recognizes the database ones by image, and reads the host port and credentials straight from each container’s environment. On Windows it also checks the registry for installed SQL Server engine instances (the default instance and named instances such as SQLEXPRESS) and asks SqlLocalDB.exe for LocalDB instances. Both results are offered together as ready connections. Nothing is scanned in the background — detection only ever runs when you click, and it re-queries fresh every time (no caching, no watching, no port-scanning, no network scanning for the native leg either — it only reads the local registry and calls the LocalDB CLI).

Native SQL Server detection only runs on Windows, where the Detect local databases button stays enabled even when Docker isn’t running — the native probe finds instances independently of it. On macOS and Linux, detection covers Docker containers only, and the button is disabled (with an explanatory tooltip) when no Docker socket is available.

Start detection four ways:

• New Connection dialog — click Detect local databases next to the connection-string paste field. This is the primary home. On macOS/Linux, if Docker isn’t running the button is disabled and its tooltip explains why; on Windows the button stays enabled regardless of Docker, since native SQL Server instances are detected independently of it.
• Command palette (Cmd/Ctrl+Shift+P) — run Detect Local Databases (searching for “docker” still finds it).
• Manage Connections — click Detect local databases in the Saved Connections dialog footer, next to the Azure Data Studio import link.
• Start page — when a Docker socket is present and you have no saved connections, a slim Running databases in Docker? link appears under the connect cards.

Jam SQL Studio recognizes these official Docker image families (registry prefixes and tags are handled):

• PostgreSQL — postgres; user from POSTGRES_USER (default postgres), password POSTGRES_PASSWORD, database POSTGRES_DB.
• MySQL / MariaDB — mysql, mariadb; user/password from MYSQL_USER/MYSQL_PASSWORD, otherwise root + MYSQL_ROOT_PASSWORD; database MYSQL_DATABASE.
• SQL Server — mcr.microsoft.com/mssql/server and Azure SQL Edge; user sa, password MSSQL_SA_PASSWORD or SA_PASSWORD.
• Oracle — gvenzl/oracle-* and Oracle’s own registry; user from APP_USER/APP_USER_PASSWORD, otherwise system + ORACLE_PASSWORD; service name XEPDB1 or FREEPDB1.

The results dialog lists every candidate with a Docker or Local badge showing where it came from, plus a credentials badge: credentials in container env when a Docker container’s password was found in its environment, or password asked on connect when it wasn’t (compose secrets, hardened images, or a manually-set SA password). Native Windows instances connect with Windows authentication, so no password badge is shown for them and none is ever asked. Click Add to save a connection — nothing auto-connects. A candidate that matches a connection you already saved shows an already added badge with a disabled Add. Docker containers without a published host port are skipped (they aren’t reachable from your machine), and only running containers with recognized database images are listed — start your database in Docker first, then detect again. When no password is found for a Docker candidate, the connection saves without one and the on-connect prompt collects it the first time you connect.

Browse Azure

Pick Azure-hosted resources straight from your signed-in Azure account instead of hand-typing cluster URLs or server hostnames. Browse Azure… opens a picker — a subscription → resource kind → resource tree with live search — and filling in a resource never auto-saves or auto-connects; you still review, test, and save the connection yourself. This section is a summary — the dedicated Browse Azure guide covers the workflow, identities, and troubleshooting in full.

From Add Connection

On the Azure Data Explorer and SQL Server connection forms, a labeled Browse Azure button sits next to the server field. On the PostgreSQL form the same action is a subtle icon-only button with a “Browse Azure…” tooltip (other engines don’t show it). The picker is filtered to that form’s engine; picking a resource and clicking Use resource fills the server, port, database, authentication, and SSL fields that resource implies.

From Import Connections

The Import… menu also lists an Azure (signed-in account) source (see Import Connections above). Choosing it opens the same picker in multi-select mode, unfiltered by engine, with cascading checkboxes at the subscription and resource-kind level. Resources you already saved show as muted and pre-unchecked. Confirming sends your picks through the normal import review dialog.

Azure identity

A chip at the top of the picker shows which identity discovery is using, switchable between:

• Azure CLI — reuses whatever account you’re logged into via az login; account changes happen in a terminal and are picked up on the picker’s Refresh.
• Microsoft Entra ID — an interactive browser sign-in, with Sign in with a different account… and Sign out available from the identity menu.

Jam SQL Studio detects the Azure CLI first and falls back to Entra sign-in when it isn’t available; whichever you pick explicitly is remembered as the default next time. Enumeration only covers subscriptions visible to your active identity’s home tenant — cross-tenant guest accounts are a known limitation, called out in the picker’s empty state rather than silently omitted.

Supported resource kinds

Browse Azure never reads or writes a password — PostgreSQL and SQL Server Authentication logins are always entered by you, the same as a hand-typed connection.

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.

SSH host key trust

The first time you open a tunnel to a bastion, Jam SQL Studio records that server’s host key so it can warn you if the key ever changes. Those pins are stored in ~/.ssh/jam_known_hosts — a Jam-managed file next to your OpenSSH one.

• Jam SQL Studio never edits ~/.ssh/known_hosts. Your own host keys stay exactly as OpenSSH wrote them, so ssh-keygen -R and ssh-keygen -H keep working normally. (Older versions did write into that file; upgrading moves those entries out automatically.)
• Deleting ~/.ssh/jam_known_hosts is safe at any time — each bastion is simply trusted again on the next connect.
• If a bastion’s key legitimately changes (a rebuilt jumphost, for example), the connection is blocked with an explicit error. Use Forget saved host key in the SSH Tunnel section to clear the old pin and accept the new one.
• Bastions you already trust from plain ssh are honoured too — Jam SQL Studio reads your existing ~/.ssh/known_hosts entries rather than asking you to trust the same machine twice.

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