Skip to main content

Cloning components

The Clone Wizard (added in 3.0.7) creates a renamed copy of a data component, optionally pulling its referenced components along for the ride. It generates the new scripts in the workspace and then lets you deploy them to one or more target databases without rerunning the wizard.

Open it from the component grid: right-click a row, then Clone Wizard. Only one component can be cloned at a time.

Data components only

The wizard clones data components (rows produced by data-component templates). Object components such as procedures, views, and functions are not supported, and the Clone Wizard menu item does not appear on them. Copy an object component the way you'd copy any source file: duplicate it in your editor, rename it, and adjust the body.

Not every data component is a good clone candidate

The wizard works well for self-contained data components whose names and alternate keys are free-text identifiers you control. It is not suitable for components whose alternate keys are system-managed identifiers, enum-bound codes, single-row configuration, or values bound to a fixed business domain. In those cases the rewritten script will either fail on deploy or quietly create rows that no application can reach.

Template authors can mark these templates explicitly with Cloneable="false" (see Disabling cloning per template). When the source or any of its dependencies sit on a non-cloneable template, the wizard refuses to clone them and flags them in the dependency list.

The four steps​

1. Identity​

Pick the new name. If the source name is composite (multiple alternate-key columns built into a single label), the wizard splits it into per-column inputs labelled with the column name from your template. Edit only the parts you actually want to change; leave parts that map to fixed-domain columns as-is.

If the template uses a <DynamicQuery> to build the name from ${...} variables, those variables are exposed here too. Variables that already feed the per-part inputs are edited above; the rest (typically GUID alternate keys) appear separately and can be regenerated with the refresh button.

Columns the template marks with OnCloneAction="EDIT" appear as their own editable cards on this step (one card per source row of each Edit-marked column). The value you type is substituted into the INSERT literal at generate time.

2. Dependencies​

Tick any referenced components you also want to clone. The parent component's lookup hashes are recomputed for cloned dependencies; un-cloned dependencies keep pointing at the existing target-database rows. Dependencies on non-cloneable templates appear in the list flagged as such, and cannot be ticked.

Detection here handles components with complex composite naming patterns, and a parent that references cloned children deploys cleanly when the children are deployed alongside it — earlier versions could miss the link and fail at deploy time.

3. Generate​

Generates the rewritten .sql files for the source and any ticked dependencies, persists the new component records to the workspace, and renames composite values everywhere they appear. Nothing has been deployed to a database at this point — the files exist in the workspace, ready for Review. The Log tab on this step shows the column-level rewrites in detail; this is the place to look when generation fails.

4. Review​

Lists every clone produced by Generate. Each row has three actions:

  • Deploy. Opens the connection picker to deploy just this clone. Pick a target connection and an execution mode: Validate (Rollback) runs the script inside a transaction that's rolled back at the end (verifies the rewrite without changing the target); Commit runs it for real.
  • Compare. Diffs the cloned file against its source.
  • Open. Opens the cloned .sql in a workspace tab.

Below the list there are three buttons that act on the whole set:

  • Deploy All runs every clone against a single target in one transactional batch, with the same Validate/Commit choice.
  • Add to basket drops the freshly-generated components straight into the deployment basket so you can deploy them later alongside other changes.
  • Close ends the wizard. Closing without deploying is fine — the files exist in the workspace already.

Per-clone deploy history is shown as coloured chips on each row, one per target (Validated / Committed / Failed) so you can tell at a glance where each component has been. A successful Commit re-extracts the cloned components against that target so their hashes match what's now in the database. Deploying to several environments in turn is straightforward; the generated files don't need to be regenerated between deploys.

References between cloned components only resolve once they reach a database, so plan to deploy them eventually.

Resuming an in-progress clone​

The wizard auto-saves your edits to a per-source-component draft, so you can step away mid-clone and come back later — across wizard tabs, app restarts, and even after a deploy.

When you re-open the wizard on a source that has a draft, an in-tab confirmation appears (no popup window):

Resume previous clone? You have an in-progress clone of 'Category/Name' from timestamp. Choose Resume to continue with your previous edits, or Discard to start over.

Resume restores your Identity edits immediately and replays the Dependencies tab selections when you reach that step. Discard wipes the saved draft and starts a fresh clone session.

The same in-tab confirmation pattern is used for the Overwrite prompt, which replaces the earlier popup dialogs.

Drafts live under <workspace>/clone-drafts/ as JSON files keyed by source component. How long they're kept is controlled by Preferences ▸ Workflow ▸ Clone Wizard ▸ Draft retention (days) (default 30; 0 disables cleanup). Stale drafts are pruned the next time the wizard opens.

How OnCloneAction controls per-column behaviour​

By default the wizard copies every column literal verbatim (KEEP). Three other behaviours can be declared on individual columns of related tables:

  • EDIT surfaces the column on the wizard's Identity step as an editable card, one per source row of the column. The user types the new value; the wizard substitutes it into the INSERT literal at generate time. Use it for columns the user should be able to override on clone — typically display names or other free-text values that don't fit the composite-name split.
  • NEW_GUID replaces the literal with a freshly-generated GUID. The wizard auto-detects the source value's GUID format (dashes, braces, parentheses) so the cloned value matches the form the extractor produced. Use NEW_GUID_D / NEW_GUID_N / NEW_GUID_B / NEW_GUID_P to force a specific format.
  • NULL replaces the literal with NULL so the deploy's key-generator step assigns a fresh value. Generator-driven primary keys get this implicitly; declare it explicitly only when overriding that behaviour or when nulling a non-PK column on clone.

These matter mainly for AlternativeKey columns on related tables, since the wizard's Identity step already exposes top-level alternate keys for the user to edit.

See data-component schema reference for the full attribute reference.

Disabling cloning per template​

Add Cloneable="false" to the root element of any template whose components should never be offered to the wizard:

<DataComponent Name="..." Category="..." Cloneable="false">
  ...
</DataComponent>

Components on a non-cloneable template:

  • Don't show Clone Wizard in their right-click menu.
  • Appear flagged in the dependency list when a different component references them, and cannot be selected for co-cloning.

Cloneable defaults to true, so existing templates need no change to opt in.

Last updated on