Skip to main content

Version 3.1

The 3.1 line covers all 3.1.x releases. Newest at the top.

3.1.0 (1 October 2026)​

Data as documents rather than scripts, changesets for shared tables, and a CLI that builds a deployable package straight from source control.

What's new​

  • Store data components as documents instead of scripts. A data template with OutputFormat="json" commits its rows as a .json data document and generates the MERGE when it deploys. A pull request then shows a row added and a row changed, rather than a rewritten SQL script, and two people editing different rows of the same component merge cleanly. The SQL that runs is unchanged, and a document carries the part of its template that shapes the script, so it inflates with no template folder present. See Store data as documents.

  • Deploy only your rows, with changesets. On a table several people work in at once, extracting the component gives you everyone's work in flight. A template with DeployMode="changeset" records only the rows your work item changed, as before and after pairs, and deploys only those. Each row is checked against the target before it is written, so a row somebody else has changed since stops the deployment and names the rows instead of overwriting their work. Deploying the same changeset twice changes nothing the second time, which is what makes it safe to promote from DEV through to production. See Deploy only your rows.

  • Choose what a pull compares. Pull My Changes asks where to read rows from (the current connection, another connection, a branch, or the workspace on disk) and what to compare them with (this branch without your changes, another branch, or a database such as production). Comparing against production is how you capture a change somebody made straight into a shared environment; comparing against main is how you refresh a changeset after main has moved on.

  • One table description, shared between components. A data template's table and column description is written once to definitions/<category>/<template>.<hash>.json, keyed by a hash of its content, and each document points at it rather than repeating it. This is the default for documents, so a template that generates hundreds of components produces hundreds of small files instead of hundreds of copies of the same description. Definition="inline" puts it back inside each document where you would rather they stood alone. The commit view makes sure a definition goes in with the documents that point at it. See Sharing one definition.

  • Build a deployable package from source control. datastar --command-name build reads a deployment file, fetches each item as a blob at the revision it is pinned at, inflates any data document or changeset to SQL, and writes scripts, a manifest and, if you ask, a zip or NuGet package. Nothing is checked out and no workspace is needed, and because the documents are inflated at build time the package needs no templates and no database when it lands. That lets a pipeline build once and decide afterwards which environment to deploy to. A release that bundles several work items has their changesets for a component combined into one, as the client does, so the package holds one file per component. See build.

  • DataStar.Tools installs as a .NET tool. dotnet tool install --global DataStar.Tools installs it from nuget.org and puts a datastar command on the path, per platform, alongside the existing zip and Linux tarball. The packages can also be pushed to your own NuGet feed. See Install it from your own NuGet feed.

  • Three more CLI commands. inflate turns data documents into SQL with no database and no licence; definitions lists, prunes, shares or inlines shared definitions; merge is a git merge driver that merges documents and changesets by row instead of by line. None of the three needs a licence key. See the CLI reference.

  • See both sides of a deployment item. The Deployment view gains Open Document (JSON) beside Open Script, so you can read the rows an item carries as well as the SQL it will run, and a Kind column marking each row as a changeset (CS), a data document deployed whole (SS), or a script a template triggered (TR). Add Components... gains a DataChangesets method that adds every changeset a work item keeps. Add from Basket takes a changeset-deploying component's changeset for the work item, or its whole document when there is none.

  • Run a changeset's rollback. Run Rollback SQL runs the SQL that reverses a changeset against the open connection, committing or rolling back as you choose, and defaulting to rolling back so it can be watched against a real target safely.

  • Deploy case-only changes on SQL Server. A data script compares values under the database's collation, so on a case-insensitive database a change of case alone was never deployed. ExactComparison="true" on a data template compares them exactly, so the change is deployed, and a key renamed only in case is renamed in place. It is off by default. See SQL Server: case-only changes.

  • A changeset folder in workspace settings. Changeset Location on the Paths & Filters tab says where changesets are kept; it defaults to changesets, beside the component folder.

  • Deploy a branch at one commit (Branch mode). A deployment file is now Pinned (each item as it was at the commit it is pinned to, as before) or Branch (every item as it is on the branch at one commit: HEAD when deploying from the client, the build revision when build packages it). The workspace's Deployment Mode setting picks the mode new files start in, and the toolbar switches a file between the two. In Branch mode a header above the grid shows the one commit every item is at, who made it and when, and offers Move to HEAD when the branch has moved on. See Pinned and Branch mode.

  • Deployment files as JSON. A new deployment file, or one saved fresh to a task, can be written as deployment.json instead of deployment.xml; the workspace's Deployment File Format setting chooses. A file that is opened is saved back in its own format, Save As with the other extension converts it, and build and the client read either.

  • Let an agent do a task end to end. Tell an agent which task you are working on and what to change, and four new MCP tools let it go from there to pushed changes: work_on_task puts the workspace on the task's branch, creating one when there is none; pull_task_rows takes the task's rows of a changeset component, as Pull My Changes does, against this branch or a database such as production; commit_task_changes commits with the shared definitions and changeset partners the files need; and push_task_changes pushes and settles the commits with the task tracker. Whatever is yours to decide, such as uncommitted changes, starting a changeset again, or a remote that has moved on, is refused with the question to ask, and a failure says what it left behind and why. An agent can no longer extract a changeset component whole. get_workspace_info now reports the branch, its task and the categories that deploy changesets, and extract_components returns the paths it wrote. See Working on a task.

  • Choose what a commit's task is, and link Git commits to work items. Task on Commits in workspace settings is Optional, Required or Off, replacing Require Task ID on Commits (a workspace with it ticked reads as Required). Link Commits to Work Items links each pushed Git commit that names a task to its Azure Boards work item, shown as Fixed in Commit, when the remote is Azure Repos in the same organisation. It is off by default, so nothing changes until you turn it on; Jira, or any other remote, never links; TFVC check-ins associate their work item as before, and a workspace with no task tracker records the branch's task as it always did. A version of DataStar older than 3.1 that saves the workspace settings drops both settings. Every way of pushing now handles a commit's task the same way, and the Release Workflow's own commits carry its work item. The Git commit dialog offers the task field with any task tracker, Jira included, not only Azure Boards, and under Required it shows the field even with no tracker. See Commits and Branches.

Improvements​

Changes to what 3.0 already did. Everything that is new in 3.1 is described above as it now works.

  • Workspace Settings: the General tab fits without scrolling. Its settings are grouped into Commits and Branches, Scripts, Deployment Files and Deployment History Tables, in two columns, each with its full explanation, and the window opens large enough to show them all, or as large as the screen allows. See Tab 1: General.
  • Database Snapshot says why: hover over an item's status to see why it could not be compared (not in version control at its pinned version, no DataStar header, a template that cannot be found). One such item no longer stops the whole snapshot, and anything that would stop the deployment is listed in one dialog that names each item. See Previewing before you run.
  • Compare a deployment item with more than the snapshot. A row's right-click menu gathers its compares under Compare With…, and adds the current connection, a database you pick, a branch and the remote to Latest, Workspace and DB Snapshot. A data document compared with a database, or with the last Database Snapshot, now reads as JSON: the document beside its component captured from the database, rather than the SQL each would deploy as. A changeset compares as its changeset file beside the same changes as the database holds them, both in the changeset file's JSON, and a script as SQL. See Per-row preview.
  • MCP: preview_deployment_changes reads a work item's deployment file from the work item's own branch, so an agent can answer "what would DAT-21 do to PRD?" without the branch being checked out. Every item it cannot compare says why, and scripts and diffs are capped so a large deployment fits an agent's context (detail='full' returns everything). generate_reversal_scripts works from each item at the version it deploys at rather than the workspace files, and manage_deployment reads and describes a work item's file from its branch too. extract_components into a draft reports a failed extraction as failed. The server now tells a connecting agent how to answer questions about a work item's deployment. See the MCP tool catalog.
  • The recent deployments menu lists only the open workspace's deployments, each by its path in the workspace. A folder pattern that names every file deployment.json no longer lists them all alike, and another workspace's deployment is no longer opened into this one.
  • Welcome to DataStar, started while another DataStar holds the workspace, offers Close It beside Bring to Front. The running DataStar closes as its own Exit would, asking first about unsaved changes, and the workspace it held can then be opened.
  • Adding a Git remote to an open workspace enables Pull, Push, Fetch, Prune, Outgoing and Incoming without restarting.
  • Opening a deployment file whose items' versions are repaired while it is checked marks the file as changed, so the repair can be saved or discarded rather than silently redone on every open.
  • Scratch folders written by the read-only viewers and comparisons are swept at start-up rather than accumulating.
  • Oracle: a data script whose first update column is computed or does not trigger an update no longer starts its column list with a comma (ORA-00936).
  • The About window shows the build's commit date rather than the time it was compiled.

Notes for upgrading​

  • Data templates without a Version now script as version 2 on SQL Server. Version used to default to 1 (deletes inside the MERGE, a parent's delete cascading to every joined child unless told not to). It now defaults to 2: deletes identified from the loaded rows and run at the end of the script, cascading only to tables that set DeleteCascade="true". The change takes effect the next time a component is extracted. If you rely on the older script, set Version="1" on those templates before upgrading. Oracle scripts are the same either way. See SQL Server: Version 2 templates.
  • Components without a SortOrder are extracted in key order. A data component whose template gives no SortOrder used to be extracted in whatever order the database returned, which could change from one extract to the next. It is now ordered by its keys, so the first extract after upgrading re-orders its rows once. The rows themselves are unchanged.
  • build refuses an output directory that is not empty. Everything in the output directory goes into the package, so files left by an earlier build would ship in the next. Give an empty folder, or add --clean to empty it first. An Azure DevOps $(Build.ArtifactStagingDirectory) is empty at the start of every run. A pipeline that used to write metadata.json or download the deployment file into the output folder before packaging no longer needs to: build puts both in the package itself. Anything else goes in with --include.
  • Save DB Snapshot has been removed. It wrote the last Database Snapshot to a .sql file that DataStar never read back, which left out what the deployment would create and could not be run as a rollback. To put a database back, use Export Reversal Script before deploying; to see what differs, use Compare With… on a row. See Exporting a reversal script ahead of time.
  • OutputFormat, DeployMode and Definition all default to today's behaviour, so a template that sets none of them still writes .sql and deploys a snapshot.
  • Changing a template to OutputFormat="json" changes the file its components are committed as. Extract them again so the .json is written and the .sql removed, and commit both halves together with the definitions folder. Deployment files that pin the old .sql at a commit keep building. See Migrating an existing .sql template.
  • The manage_basket MCP tool has been removed. An agent no longer stages components in the basket: it builds the task's deployment file with manage_deployment (action='build', with the components) and commits it with commit_task_changes. A saved basket.xml attachment can still be read with manage_task_attachment. Agent prompts or scripts that call manage_basket need updating. See Working on a task.
  • Everyone on the workspace needs 3.1 before documents or changesets are committed. An older DataStar cannot read a shared-definition document or a changeset, and says so rather than deploying it as something else.
  • The DataStar.Tools NuGet package is now a .NET tool. Up to 3.0 the DataStar.Tools package held DataStar.Tools.exe under content. From 3.1 it installs with dotnet tool install --global DataStar.Tools and holds no program itself: each platform package (DataStar.Tools.win-x64, DataStar.Tools.linux-x64, ...) keeps it under tools/net10.0/<platform>, built for the .NET 10 runtime. Anything that unpacked the old package and ran content/DataStar.Tools.exe should install the tool instead, or use the self-contained zip, DataStar.Tools.<version>.zip, which needs no runtime. See Installing DataStar.Tools.
  • Register the merge driver yourself. DataStar ships datastar --command-name merge but does not write your git config or .gitattributes; until it is registered, git merges documents by line, which conflicts more often than it needs to. See merge.
  • Packaging shared-definition documents without build. The release command still inflates documents at deploy time, but it finds a shared definition in a definitions folder above the document. A package laid out by GitSources.Tools or the Azure Get Sources task has none, so either switch that stage to build or copy the workspace's definitions folder into the package root.
  • Data documents and shared definitions extracted with an earlier 3.1 preview should be extracted again: what a document records about its template, and what a definition's identity covers, changed during development, and an older document carries no script surface, so it inflates only where the template can be found and reports a template change when there has been none.
Last updated on