Documentation
How to use SQL Multicast, from your first run to automating it in CI.
Introduction
- Introduction SQL Multicast is a desktop tool for people who maintain more than one copy of the same database.
Install and first launch
- Install and first launch: Installing Run the installer. The application installs per user, so it needs no administrator rights, and itputs its own data under %APPDATA%\SqlMulticast (§3.9).
- Install and first launch: Updates The app checks its release feed at startup.
- Install and first launch: First launch With no workspace, the app cannot show you anything — so it asks for one before the main window isusable.
- Install and first launch: The tour and the setup wizard Two different things, and you can replay either at any time from the menu.
- Install and first launch: If you already use SQL Multi Script A first launch that finds a Red Gate installation offers to import from it.
Core concepts
- The shape of it Five objects, and the rules between them.
- Workspace A workspace is the top-level container and the unit you share.
- Connection A connection is a registered server: a host, an optional port, an optional default database, anauthentication method, and TLS settings.
- Target, and target group A target is one database on one registered server.
- Project and script A project is a set of .sql files and how to run them: which scripts, in what order, which areenabled, and the execution settings that apply to the run.
- Environment and variable The workspace says which variables exist and how each renders.
- The two questions are independent Environment and target group are deliberately unlinked.
- What a run is Targets run in parallel up to the project's limit; scripts within one target run in sequence.
- Where everything is stored Beside the workspace, and meant for git:
- Two people sharing a workspace Ana creates the workspace, registers the servers, builds the target groups, and commits:
A first run, end to end
- A first run, end to end About fifteen minutes, and it produces a real result.
The window
- The window Each rail shows one panel at a time — the rail itself is always present, and the panel beside itcan be collapsed away entirely.
Workspaces
- Workspaces: Creating one Workspace ▸ New, or the switcher in the title bar.
- Workspaces: Opening and adding Workspace ▸ Open takes a .smcworkspace path.
- Workspaces: When a workspace has moved If the file at a remembered path is gone, the app says so and offers to forget the entry rather thansilently dropping it.
- Workspaces: Sharing through git Commit the manifest, connections.json, distributionLists.json, environments.json, and yourprojects.
- Workspaces: Per-machine overrides When a shared connection needs to point somewhere else on your machine, override it locally.
- Workspaces: Edits from outside The app watches the workspace files. If you pull a branch that changes connections.json while theapp is open, the connections and target groups refresh without a restart.
Connections
- Connections: Registering a server Run ▸ Connections… opens the editor, which has two tabs: Connections and Target groups.The Registered servers panel in the right rail is a read-only view of the same list.
- Connections: Authentication Connections: Authentication
- Connections: Marking a connection production Ticking This is a production database means that any run whose targets include this connectionstops and makes you type a word to agree before a single statement is sent.
- Connections: Renaming and removing Renaming a connection is safe: target groups reference a connection by id, not by name.
Target groups
- Target groups: Building a group Run ▸ Target Groups…, or the Targets panel's own add and edit buttons.
- Target groups: Groups with several databases on one server This is the normal case, not an edge case.
- Target groups: Deleting a group Asks once, and it is safe in the sense that matters: a group is a list of references, so there are nofiles and no databases behind it to lose.
- Target groups: Long groups The app is built to run against hundreds of targets.
Projects and scripts
- Projects and scripts The left rail has two panes that look similar and are not.
- Projects and scripts: Creating and opening a project Project ▸ New (Ctrl+Shift+N) asks for a name and a location, creates a folder, and adds onestarter script.
- Projects and scripts: The Project pane Removing a script from a project deletes nothing from disk.
- Projects and scripts: The Scripts pane A folder browser with back, forward, and up; it remembers the folder you last pointed it at acrossprojects and restarts.
- Projects and scripts: Saving Ctrl+S saves the active tab, Ctrl+Shift+S saves every dirty tab.
- Projects and scripts: Deleting a project Three outcomes, not two.
- Projects and scripts: Scripts that have gone missing A script in the project whose file is no longer on disk is marked in the pane and named in thetooltip.
The editor
- The editor: Tabs Open scripts appear as tabs. Right-click one for:
- The editor: The status readout The status bar shows the active document's encoding and language alongside the run state.
- The editor: Formatting Ctrl+K formats the active script. Script ▸ Format Folder formats every .sql file in a folder,after asking:
- The editor: Error markers After a run that failed, the failing line is marked in the editor.
IntelliSense
- IntelliSense: Choosing the reference database Completion reads real object and column names from a real database — not a guess from the text infront of it.
- IntelliSense: The popup Two shapes, and Ctrl+G switches between them for the life of one popup:
- IntelliSense: Refreshing Ctrl+Shift+R re-reads the active script's target schema.
- IntelliSense: The schema cache Object and column names read from your databases are kept on disk so completion works the moment theapp opens.
- IntelliSense: Drift annotations If you have run a coverage scan (§16) against the active target group, completion items can carry adrift note — "missing on 6 of 12 scanned".
Variables and environments
- Variables and environments: The four types Write {{name}} anywhere in a script. Substitution happens once, at pre-flight, before a singlestatement is sent.
- Variables and environments: Overriding a type at one site {{name|literal}}, {{name|ident}}, {{name|number}}, {{name|raw}} override the declaration forthat one usage.
- Variables and environments: The variable editor Ctrl+Shift+B opens it as a tab, not a dialog, so you can keep a script visible beside it.
- Variables and environments: Built-in variables Always available, cannot be declared, and resolved per target:
- Variables and environments: Seeing what resolved The Variables panel in the left rail shows what each variable is worth under the selectedenvironment, for the first target.
- Variables and environments: Failures Variables and environments: Failures
Running scripts
- Running scripts: Preview first Ctrl+Shift+V shows the exact SQL one target will receive, after substitution.
- Running scripts: What happens when you press F5 1. Unsaved changes. A run executes the files on disk, so anything unsaved has to be writtenfirst:
- Running scripts: On-error policy Set on the project, and overridable per run from the command bar.
- Running scripts: Batches A script is split on GO into batches, and the error policy acts at batch granularity.
- Running scripts: Parallelism and timeouts Set per project (§17): how many databases execute at once (default 4), and the command timeout(default 300 seconds).
- Running scripts: Canceling Alt+Break, or the Cancel button. Batches already sent finish or are aborted by the server;databases not yet started never begin.
- Running scripts: Re-running what failed Run ▸ Re-run failed runs the same scripts against only the targets that failed last time:
- Running scripts: Transactions There is no ambient transaction wrapped around a run.
Results
- Results: The grouped list Every cell is one script on one database.
- Results: The detail pane Check several rows to see a union across them; This database only narrows back to one.
- Results: All Servers The combined view: one grid across every target that ran the selected script, with a source columnnaming the database each row came from.
- Results: Truncation warnings The live pane holds every row. The stored run log holds a sample.
- Results: Export Export acts on what is in the pane, so it is not subject to the history row limit.
Run history
- Run history The History tab lists past runs, newest first.
Schema coverage scan
- Schema coverage scan: Running it Finds what differs across the databases in the selected target group: objects missing from some,columns typed differently on some.
- Schema coverage scan: Reading the findings Findings surface as annotations in IntelliSense (§11) and are reported with their denominator:
- Schema coverage scan: What a scan does and does not prove The denominator is the check. "Missing from 3" is not something you can act on — three of five isa mistake, three of forty is a rollout half done.
- Schema coverage scan: Fixing what it finds Write a script that adds what is missing, run it across the group (§13), and scan again.
Settings
- Settings: Application Tools ▸ Settings.
- Settings: Project Applies to the open project and is saved in its .smcproj.
- Settings: Run history Settings: Run history
- Settings: IntelliSense Settings: IntelliSense
- Settings: Shortcuts Buttons to open the workspace folder and the log folder in Explorer.
- Settings: What lives where Everything under Application, Run history and IntelliSense is per machine, insettings.json.
Importing from Red Gate SQL Multi Script
- Importing from Red Gate SQL Multi Script: What comes across Export the lists from SQL Multi Script first.
- Importing from Red Gate SQL Multi Script: Running the import Offered on a first launch that finds an installation.
- Importing from Red Gate SQL Multi Script: What is not imported Importing from Red Gate SQL Multi Script: What is not imported
Keyboard and the command palette
- Keyboard and the command palette Ctrl+Shift+P opens the palette and searches every command by name.
- Keyboard and the command palette: Commands with no shortcut, deliberately F2 and Delete are scoped to the pane that actually has focus rather than bound window-wide — awindow-wide Delete would fire whenever focus sat somewhere that does not consume the key itself.
Beyond the desktop app
- Beyond the desktop app The headless faces have their own documents.
Troubleshooting
- Troubleshooting A target did not answer at pre-flight.The message names the database and carries the server's own error.
Glossary
- Glossary Plain definitions of the terms SQL Multicast uses, from connection and target to drift and run.
Appendices
- File formats Scope: for people who read the JSON, and for anyone generating it.
- Error codes Scope: the codes an automated caller branches on, with the message each face renders.
- Known limitations Known limitations
Command line (sqlmc)
- What sqlmc is sqlmc is SQL Multicast without a window. It is not a reimplementation: every verb is a thinadapter — parse arguments, make one call into the shared operations layer, render the answer.
- What sqlmc is: Getting it sqlmc comes with the installer, and is also a standalone zip for Microsoft Store installs and build agents.
- What ships today Two things. The rest of the verb surface is §8.
- Finding a workspace No verb opens a dialog and no verb creates a workspace.
- Finding a workspace: Why the directory walk matters The index and settings.json live under %APPDATA%, per user.
- Output and exit codes: Two shapes, one decision Human-readable text by default; --json for a versioned envelope.
- Output and exit codes: Where output goes Output and exit codes: Where output goes
- Output and exit codes: Exit codes The 1 / 2 distinction is the one that matters most.
- sqlmc list coverage: Synopsis sqlmc list coverage: Synopsis
- sqlmc list coverage: What it does Opens one connection per database in the named target group, reads its schema, and reports whatdiffers between them: objects missing from some, and columns typed differently on some.
- sqlmc list coverage: Options sqlmc list coverage: Options
- sqlmc list coverage: Production consent A group holding a production database is refused before any connection is opened.
- sqlmc list coverage: Reading the report Every count is rendered against the number of databases actually read.
- sqlmc list coverage: Failure and cancellation sqlmc list coverage: Failure and cancellation
- sqlmc list coverage: The JSON payload sqlmc list coverage: The JSON payload
- sqlmc list coverage: Recipes Fail a build when the estate drifts.
- Credentials No password in argv, ever. There is no --password.
- Use from CI Find the workspace by walking, not by the index.
- Planned verbs Verb grammar. sqlmc <noun> <verb> [args] [--flags], nouns singular: workspace, project,script, connection, list, env, var, run, preview, format, history, settings,mcp.
- Error codes errors[].code is an OperationErrorCode name.
- Environment variables Environment variables
MCP server
- What this is sqlmc mcp exposes SQL Multicast's engine to an agent over the Model Context Protocol.
- Running the server sqlmc ships in the installer and as a standalone zip. The command is sqlmc mcp; see the CLI reference, §1 for where it lives.
- Running the server: Wiring it into a client Claude Code — .mcp.json in the project, or the user-level equivalent:
- Running the server: What the server runs as It reads credentials from the Windows credential store of the user that launched it (§7).
- Finding a workspace Identical to the CLI — see the CLI reference, §3 for theresolution order and the two rules about named paths and ambiguous folders.
- The tools Both are annotated honestly, and a client that respects annotations can rely on them: neither toolwrites to a database or to a file.
- sqlmc_script_complete: What it answers What can be written at a position in a T-SQL script: keywords, snippets, workspace variables, and —when a reference database is named — its schemas, tables, views, routines and col…
- sqlmc_script_complete: Parameters maxItems has a default because a caret at the start of a statement offers the whole dialect —hundreds of keywords — and everything past the first screenful is noise an agent pays for by thetoken.
- sqlmc_script_complete: It degrades rather than refusing With no workspace, no reference database, or a database that cannot be reached, it answers with ashorter list and says so in errors.
- sqlmc_script_complete: Result Three of those carry design intent an agent author should not have to infer.
- sqlmc_script_complete: Item kinds items[].kind is one of the engine's kinds: Keyword, Snippet, Variable, Schema, Table,View, Column, StoredProcedure, Function.
- sqlmc_script_complete: Drift notes on items An item may carry a drift note — what a coverage scan of the target group named indistributionList observed about that name:
- sqlmc_script_complete: Worked exchange totalItems is 11 and two came back, because maxItems was 5 and the cap applied after ranking —read the count, not the length.
- sqlmc_list_coverage: What it answers The same scan as sqlmc list coverage: what differs acrossthe databases in a target group.
- sqlmc_list_coverage: It asks before it connects This is the part an agent author must get right.
- sqlmc_list_coverage: Parameters sqlmc_list_coverage: Parameters
- sqlmc_list_coverage: Result One shape for both halves of the call. A tool has one output schema, and two tools would let a callerreach the second without ever seeing the first.
- sqlmc_list_coverage: What a finding may and may not claim The most important section in this document.
- sqlmc_list_coverage: Progress and long calls The scan reports MCP progress notifications — completed, total, and the database currently beingread.
- sqlmc_list_coverage: Worked exchange Call 1 — plan.
- sqlmc_list_coverage: Using the two tools together Scan a group, then complete against a database you now know differs.
- Security and what the agent can reach The page a reviewer will want before approving this server.
- Planned What the MCP server does not do yet: tools that are designed but not built.
Licensing
- Which tier am I? The test is what the work is for, not how much you use.
- What the tiers actually differ on Every tier gets the same software through the same three faces: the desktop app, sqlmc, and theMCP server.
- How does the Pro trial work? When you first sign in the app asks whether this is personal use or for work.
- What happens if I cancel? Nothing you built goes away. Workspaces, projects, scripts, distribution lists and run history are allstill there, and the app keeps running.
- Do I have to sign in? Once, and it is one trip to your browser.
- What if I cannot sign in — expired license, no network, corporate proxy? The app keeps working at the Community tier's limits.
- Air-gapped machines and CI agents Machines with no route out are licensed with a signed file rather than a sign-in:
- Seats A seat is one named person, on as many machines as they use.
- Can I evaluate it before buying? Pro: yes. Choose "for work" at first sign-in and the 30-day trial is a full Pro license from the firstminute, with no card.
- What do you collect? Your name, email and organization. Nothing about your databases — not server names, not connectionstrings, not script content, not results.
- Several accounts on one machine Settings → Account lists every account remembered on this machine.
All topics, A to Z
- A first run, end to end A first run, end to end
- Air-gapped machines and CI agents Licensing
- Beyond the desktop app Beyond the desktop app
- Can I evaluate it before buying? Licensing
- Connection Core concepts
- Connections: Authentication Connections
- Connections: Marking a connection production Connections
- Connections: Registering a server Connections
- Connections: Renaming and removing Connections
- Credentials Command line (sqlmc)
- Do I have to sign in? Licensing
- Environment and variable Core concepts
- Environment variables Command line (sqlmc)
- Error codes Appendices
- Error codes Command line (sqlmc)
- File formats Appendices
- Finding a workspace Command line (sqlmc)
- Finding a workspace MCP server
- Finding a workspace: Why the directory walk matters Command line (sqlmc)
- Glossary Glossary
- How does the Pro trial work? Licensing
- Importing from Red Gate SQL Multi Script: Running the import Importing from Red Gate SQL Multi Script
- Importing from Red Gate SQL Multi Script: What comes across Importing from Red Gate SQL Multi Script
- Importing from Red Gate SQL Multi Script: What is not imported Importing from Red Gate SQL Multi Script
- Install and first launch: First launch Install and first launch
- Install and first launch: If you already use SQL Multi Script Install and first launch
- Install and first launch: Installing Install and first launch
- Install and first launch: The tour and the setup wizard Install and first launch
- Install and first launch: Updates Install and first launch
- IntelliSense: Choosing the reference database IntelliSense
- IntelliSense: Drift annotations IntelliSense
- IntelliSense: Refreshing IntelliSense
- IntelliSense: The popup IntelliSense
- IntelliSense: The schema cache IntelliSense
- Introduction Introduction
- Keyboard and the command palette Keyboard and the command palette
- Keyboard and the command palette: Commands with no shortcut, deliberately Keyboard and the command palette
- Known limitations Appendices
- Output and exit codes: Exit codes Command line (sqlmc)
- Output and exit codes: Two shapes, one decision Command line (sqlmc)
- Output and exit codes: Where output goes Command line (sqlmc)
- Planned MCP server
- Planned verbs Command line (sqlmc)
- Project and script Core concepts
- Projects and scripts Projects and scripts
- Projects and scripts: Creating and opening a project Projects and scripts
- Projects and scripts: Deleting a project Projects and scripts
- Projects and scripts: Saving Projects and scripts
- Projects and scripts: Scripts that have gone missing Projects and scripts
- Projects and scripts: The Project pane Projects and scripts
- Projects and scripts: The Scripts pane Projects and scripts
- Results: All Servers Results
- Results: Export Results
- Results: The detail pane Results
- Results: The grouped list Results
- Results: Truncation warnings Results
- Run history Run history
- Running scripts: Batches Running scripts
- Running scripts: Canceling Running scripts
- Running scripts: On-error policy Running scripts
- Running scripts: Parallelism and timeouts Running scripts
- Running scripts: Preview first Running scripts
- Running scripts: Re-running what failed Running scripts
- Running scripts: Transactions Running scripts
- Running scripts: What happens when you press F5 Running scripts
- Running the server MCP server
- Running the server: What the server runs as MCP server
- Running the server: Wiring it into a client MCP server
- Schema coverage scan: Fixing what it finds Schema coverage scan
- Schema coverage scan: Reading the findings Schema coverage scan
- Schema coverage scan: Running it Schema coverage scan
- Schema coverage scan: What a scan does and does not prove Schema coverage scan
- Seats Licensing
- Security and what the agent can reach MCP server
- Settings: Application Settings
- Settings: IntelliSense Settings
- Settings: Project Settings
- Settings: Run history Settings
- Settings: Shortcuts Settings
- Settings: What lives where Settings
- Several accounts on one machine Licensing
- sqlmc list coverage: Failure and cancellation Command line (sqlmc)
- sqlmc list coverage: Options Command line (sqlmc)
- sqlmc list coverage: Production consent Command line (sqlmc)
- sqlmc list coverage: Reading the report Command line (sqlmc)
- sqlmc list coverage: Recipes Command line (sqlmc)
- sqlmc list coverage: Synopsis Command line (sqlmc)
- sqlmc list coverage: The JSON payload Command line (sqlmc)
- sqlmc list coverage: What it does Command line (sqlmc)
- sqlmc_list_coverage: It asks before it connects MCP server
- sqlmc_list_coverage: Parameters MCP server
- sqlmc_list_coverage: Progress and long calls MCP server
- sqlmc_list_coverage: Result MCP server
- sqlmc_list_coverage: Using the two tools together MCP server
- sqlmc_list_coverage: What a finding may and may not claim MCP server
- sqlmc_list_coverage: What it answers MCP server
- sqlmc_list_coverage: Worked exchange MCP server
- sqlmc_script_complete: Drift notes on items MCP server
- sqlmc_script_complete: It degrades rather than refusing MCP server
- sqlmc_script_complete: Item kinds MCP server
- sqlmc_script_complete: Parameters MCP server
- sqlmc_script_complete: Result MCP server
- sqlmc_script_complete: What it answers MCP server
- sqlmc_script_complete: Worked exchange MCP server
- Target groups: Building a group Target groups
- Target groups: Deleting a group Target groups
- Target groups: Groups with several databases on one server Target groups
- Target groups: Long groups Target groups
- Target, and target group Core concepts
- The editor: Error markers The editor
- The editor: Formatting The editor
- The editor: Tabs The editor
- The editor: The status readout The editor
- The shape of it Core concepts
- The tools MCP server
- The two questions are independent Core concepts
- The window The window
- Troubleshooting Troubleshooting
- Two people sharing a workspace Core concepts
- Use from CI Command line (sqlmc)
- Variables and environments: Built-in variables Variables and environments
- Variables and environments: Failures Variables and environments
- Variables and environments: Overriding a type at one site Variables and environments
- Variables and environments: Seeing what resolved Variables and environments
- Variables and environments: The four types Variables and environments
- Variables and environments: The variable editor Variables and environments
- What a run is Core concepts
- What do you collect? Licensing
- What happens if I cancel? Licensing
- What if I cannot sign in — expired license, no network, corporate proxy? Licensing
- What ships today Command line (sqlmc)
- What sqlmc is Command line (sqlmc)
- What sqlmc is: Getting it Command line (sqlmc)
- What the tiers actually differ on Licensing
- What this is MCP server
- Where everything is stored Core concepts
- Which tier am I? Licensing
- Workspace Core concepts
- Workspaces: Creating one Workspaces
- Workspaces: Edits from outside Workspaces
- Workspaces: Opening and adding Workspaces
- Workspaces: Per-machine overrides Workspaces
- Workspaces: Sharing through git Workspaces
- Workspaces: When a workspace has moved Workspaces