Last updated: 2026-08-04

Getting Started

Welcome to Jam SQL Studio! This guide will walk you through installing the app, connecting to your first database, and running your first query. You'll be up and running in just a few minutes.

Step 1: Install Jam SQL Studio

Download Jam SQL Studio for your operating system and follow the installation instructions.

No database handy? Explore the bundled sample

Jam SQL Studio ships with a copy of the classic Chinook music-store database (11 tables of artists, albums, tracks, and invoices) so you can try the app before connecting anything of your own. On the start page, pick Explore a sample database — or run Open Sample Database from the command palette (Cmd+Shift+P / Ctrl+Shift+P) at any time.

One click opens a query tab with a ready-made query already executed against a real local SQLite file. It's your private copy — edit rows, drop tables, experiment freely; your own databases are never involved. Everything you see in the docs below (Table Explorer, Schema Overview, execution plans, exports) works on the sample too.

Step 2: Create Your First Connection

Connect to a SQL Server, PostgreSQL, MySQL, Oracle, or SQLite database to start exploring your data. Coming from Azure Data Studio? Jam SQL Studio can import your saved ADS connections in one click instead. Running your database in Docker? Click Detect local databases to find local containers and add them with credentials read from the container environment.

Step 3: Run Your First Query

Now that you're connected, let's run a simple query to explore your data. On your very first connection, Jam SQL Studio gives you a head start automatically — it opens Table Explorer on a table from your database (or a prefilled starter query) so you see results right away, with a one-time hint pointing you at New Query for custom SQL.

SELECT TOP 10 * FROM sys.tables ORDER BY name;

Pinning Objects in the Sidebar

Once you're connected, you can pin the databases, schema containers, folders (Tables, Views, Stored Procedures, Functions), and individual objects you use most often to a list at the top of your connection — above Databases. This gives you one-click access without traversing the tree.

• Hover any pinnable row and click the small outline pin icon on the right.
• The icon becomes a filled pin that stays visible. Click it again — on the original row or the pinned copy at the top — to unpin.
• Pinned rows from the same database are grouped inside a subtle tinted "database area" with the database name printed in a tiny uppercase header above. That keeps two Tables folders pinned from different databases visually distinct without needing a per-row chip.
• Pinned rows are expandable shortcuts — click the chevron and they drill into the same children as the canonical tree (a pinned database expands into its object-type folders, a pinned Tables folder lists its tables, a pinned table opens its Columns / Keys / Indexes subfolders). Stored procedures and functions stay leaves. Expanded children render inside the same tinted area as the pinned parent.
• Hover a pinned row to reveal a grip handle on the left, then drag to reorder. Dragging a pin from one database into the middle of another database's pins is allowed — the pin keeps its database, and the visual splits into separate areas so the grouping always matches what's pinned.
• When you have one or more pins, the Databases folder no longer auto-expands on connect — the pinned area is the starting point. Click Databases any time to drill into the full schema.
• The sidebar search ignores the pinned shortcuts so a pinned table never shows up twice in your results (the canonical row under Databases is the one match).
• Pinned items appear lightly greyed when the connection is disconnected, and more strongly greyed (with a tooltip) when the underlying object is no longer present in the database.

Pins are stored per connection on disk as part of your connection's MetaInfo, so they survive app restarts and stay scoped to the connection they belong to.

Customizing the Toolbar

The toolbar ships with the actions most people reach for, and keeps the rest in More ▾. If your day revolves around something in that menu — Schema Compare, Table Designer, New Notebook — you can move it onto the bar itself in Settings → UI → Toolbar.

• Put an item on the bar — tick it in the In the More ▾ menu list. It moves up into the toolbar row.
• Reorder — drag the handle on any row in the On the toolbar list. The row holds up to nine buttons.
• Hide something you never use — click the eye icon. Hidden items leave the toolbar and the More ▾ menu. Most of them are still available from the app menu and the command palette (Cmd/Ctrl+K); three — Data Profile, Database Meta Info and Package Explorer — have no menu or palette entry and are reached by right-clicking a table or database in the Object Explorer instead. Everything hidden is listed at the bottom of the panel with a Restore button.
• Reset to defaults — one button, any time.

Some buttons only apply to certain engines — the DBA tools, Package Explorer, Notebooks. Those rows are marked Not available now when no connection that supports them is open. You can still put them on the toolbar; they simply appear once such a connection is.

Home always stays first and More ▾ always stays last, and neither can be hidden — hiding More ▾ would put everything inside it out of reach. Until you change something, the toolbar simply follows the shipped default, so improvements to it still reach you; once you have customized it, buttons added in later releases still appear.

Moving Your Settings to Another Machine

Settings → Backup & Transfer writes your preferences to a plain JSON file you can carry to a new machine, keep before a reinstall, or hand to a teammate so everyone works with the same setup.

Tick what you want to include, then click Export settings…:

• Appearance & layout — theme, tab orientation, sidebar and terminal panel sizes, grid detail preferences.
• Editor & execution — word wrap, tab size, the inline Execute/Peek bar, IntelliSense toggles, query timeout.
• AI & terminal — AI workspace, execution-history and agent-context preferences.
• Spatial maps — your basemap preference.
• Toolbar layout — your customized toolbar. Importing it replaces the toolbar on the target machine rather than blending with it.
• SQL snippets — off by default, because snippet bodies are SQL you wrote.
• Database meta info — off by default. This one can contain data, not just definitions; see the caveat below.

What is never in the file. Saved connections, passwords, SSH keys, licence keys, sign-in tokens, your sessions and your query history are never written to a settings backup — not even encrypted. The file is plain JSON, so you can open it and check before you share it. Saved connections have their own separate export. The one group that can carry data out of your database is Database meta info, which is off by default and described below.

Analytics and crash-reporting choices are also left out on purpose. Those are consent decisions, and inheriting someone else's is not something an import should do for you.

Importing. Click Choose backup file… to read a file. Nothing changes yet — you first see exactly which groups the file contains, and a note about anything the file holds that this version doesn't recognise. Tick the groups you want and click Import selected. Settings take effect immediately; there is no restart.

If the file is not a Jam SQL Studio backup, was written by a newer version, or has been hand-edited into an inconsistent state, the import stops and tells you why without changing a single setting.

Database meta info caveat. Two things worth knowing before you tick this one.

First, it is not only declarations. Alongside your loose foreign keys and JSON, enum and spatial column declarations, this group carries their caches — and those caches hold up to 200 distinct values sampled from each enum column, plus JSON paths derived from documents actually stored in your tables. If a column holds anything you would not put in a file you share, leave this group unticked.

Second, these records are stored per connection, keyed by an id generated on the machine that created the connection. Importing them onto a machine whose connections were set up separately will bring the records across, but they will stay dormant until they sit alongside connections with matching ids. If you're cloning a whole setup, import connections first.

Moving your saved connections

Saved connections are a separate file with their own rules, in the same Settings → Backup & Transfer section. Tick the connections you want and click Export connections….

By default the file contains no passwords. It lists server names, ports, database names, usernames and any SSH bastion — in plain text, on purpose, so you can open it and read exactly what you are about to share.

Including passwords. Tick Include saved passwords, protected by a passphrase and enter a passphrase twice. Your saved passwords and SSH secrets are then encrypted into the file with a key derived from that passphrase (scrypt, then AES-256-GCM). They are never written in plain text, and they are never written as your machine's own encrypted blobs either — those are tied to this machine's keychain and would be useless anywhere else.

There is no recovery and no hint stored in the file. If you lose the passphrase, the passwords in that backup are gone — keep it somewhere other than next to the file. Everything else in the export still opens without it.

Importing. Click Choose connections file…. Nothing is saved yet: you first see every connection the file offers, with the exact host and port it will connect to and the SSH bastion it would route through, if any. Connections you already have start unticked. If the file includes passwords, a passphrase box appears — leave it blank to import the connections without them and be prompted on first connect.

A wrong passphrase imports nothing at all, so you can simply retype it and try again. The same happens if the file was edited after it was exported: the encrypted passwords are cryptographically tied to the settings that decide where each credential goes, how it travels and what it may do — the server and port, the database and username, any SSH bastion, the TLS and certificate-validation flags, the authentication mode, and Oracle's TNS and wallet locations. Change any of them and the file will not open. Cosmetic edits — renaming a connection, changing its colour, reformatting the JSON — are fine.

The review list also shows you those settings, because a file that simply arrives with certificate checking switched off was never tampered with and is still worth noticing. Every connection that goes over a network shows how it protects your password, and anything short of verified TLS — no encryption, an unverified certificate, or a transport Jam SQL Studio cannot determine — is called out in amber next to the connection. SQLite databases are local files and show no transport line. Imported connections are always added alongside your existing ones, never merged over them, and nothing connects automatically.

A no-passwords export is also readable by the ordinary Import… menu in Manage Connections, listed as Jam SQL Studio export — the same place you would import from DBeaver or Azure Data Studio. That route never restores passwords, whatever the file contains.

Frequently asked questions

What's Next?

Now that you've connected and run your first query, explore more features: