Skip to main content

Deployment files

A deployment file is the saved form of a deployment: a file you can commit to source control, attach to a task, or hand to an operator to re-run later. The Deployment tab's toolbar is the primary place you create, save, open, and run them.

Saving a deployment​

Three save options live on the Deployment tab's toolbar:

  • Save (Ctrl+S). Save to the deployment's current path. First-time saves open a file dialog so you can pick a location.
  • Save As (Ctrl+Shift+S). Save to a different path.
  • Export to Task. Attach the deployment file to a task in your task tracker (Jira or Azure Boards). You are prompted for a task ID each time and can look it up with Find to confirm it exists before exporting, so you can attach to any task, not just the one associated with the current branch. Only available when you're connected to a task tracker.

The default on-disk location and folder pattern for saved deployments are configured on the workspace's Settings → Release tab. That tab also controls whether deployments produced by the Release Workflow are stored as workspace files, attached to a task, or both.

Opening an existing deployment​

From the Deployment tab toolbar:

  • Open (Ctrl+O). Pick an existing deployment file.

From the main menu you also have:

  • Deployment → Open File…. Same as the toolbar Open.
  • Deployment → Recent Files. Pick from the recent list.
  • Deployment → Import from Task…. Load a deployment attached to a task. You're prompted for a task ID each time, so you can import from any task.
  • Deployment → Deploy from Manifest…. Load a deployment file and deploy it immediately.

Running a deployment​

Click Deploy (Ctrl+Shift+E) on the Deployment toolbar. This opens the Run Script dialog (the same dialog as the single-component Run) with a Mode picker for COMMIT vs ROLLBACK.

Pick the mode, click Run. DataStar executes every component in order; when it finishes a log tab opens showing the per-component results.

Previewing before you run​

Several toolbar actions run against the deployment without actually deploying:

  • What If. Preview of what the deployment would do.
  • Database Snapshot. Compare the deployment's items against the current database state. You're prompted for the database to compare against, and each row's status shows whether it matches, has changed, is new, or can't be compared.
  • Save DB Snapshot. Write the database-side object definitions captured by the last snapshot to a file. This is a flat, point-in-time capture of the live schema (object DDL, not row data); components that don't yet exist in the target have nothing to capture and are skipped. The action stays disabled until you've run a Database Snapshot.
  • SQL Export. Write the deployment out as a SQL script for review.
  • Export Reversal Script. Generate a rollback script for the deployment against a database you choose - no deployment or audit tables required. See Reversal → Exporting a reversal script ahead of time.
Export format: SQL Server vs Oracle

These exports are vendor-aware:

  • SQL Server produces a single .sql file with batches separated by GO.
  • Oracle lets you choose, in the save dialog's Save as type, between a single .sql file (PL/SQL blocks terminated with /) and a .zip package. The package holds each script plus a deploy.sql you can run in SQL*Plus (@deploy.sql) and a manifest.mf for re-running through DataStar. The .zip is the more robust Oracle choice (it carries SET DEFINE OFF and runs each script separately) and is portable across Windows, macOS and Linux.

Either artifact can be re-run from Deployment → Run External Script.

Suggested file names

Save DB Snapshot and Export Reversal Script pre-fill the save dialog with a descriptive name of the form {kind}_{task}_{database}_{timestamp}.{ext} - for example reversal_PROJ-123_DEV-SQL_20260628153012.sql. The task segment is included only when the deployment is attached to a task, and the timestamp is yyyyMMddHHmmss.

Reading the deployment grid​

Each row pins an item to a specific commit (the Version column). A few columns and indicators make it obvious when reality has moved on:

  • Latest Version. The newest commit where the file still exists. For a file that's been deleted upstream this is the last commit before the delete, not HEAD, so Update to Latest never tries to update to a version that doesn't contain the file.
  • Is Latest. Only ticked when the pinned version matches the latest version that contains the file.
  • Deleted-upstream rows are highlighted with a delete icon in the status column, and a banner at the top of the view tells you how many items are affected.

Per-row preview​

Right-click any row in the deployment grid for comparisons against specific targets:

  • Compare with Latest
  • Compare with Workspace
  • Compare Item with DB Snapshot
  • View History. Lists only the commits that actually changed this file. Merge commits that simply brought a branch forward are filtered out so they don't clutter the history with misleading "Modified" entries. The same rule applies wherever items get added to a deployment, including Add From Basket and the Release Workflow wizard.
  • Open Script. Opens the pinned version (not the working copy). The tab title shows the version, e.g. myscript.sql @1abb94c, and the file is read-only, but it isn't locked while you're reading it. Works the same on Git and TFVC.

Deployment history​

Deployments that ran successfully appear in Deployment → History; see the history tab for the audit log, including links back to re-run or reverse a previous deployment.

What's next​

Last updated on