Skip to main content

Share templates across a team

Templates live inside your workspace, which means you already have a distribution mechanism: the same version control repository your SQL scripts live in. This guide shows the recommended layout, how to point a workspace at it, and a couple of patterns for larger teams.

The short version​

  • Put templates in a folder under your workspace (e.g. templates/).
  • Declare the folder in workspace.json.
  • Commit everything to the same repo as your components.
  • Teammates who clone the repo get the templates automatically; no install step.
repo-root/
├── .ds/
│   └── workspace.json
├── components/           ← generated SQL lives here
│   ├── Tables/
│   ├── Views/
│   └── …
├── templates/            ← templates live here
│   ├── currencies.xml
│   ├── functions.xml
│   ├── views.xml
│   └── scripts/
│       ├── disable-fk.sql
│       └── enable-fk.sql
└── …

Keep templates and their associated static scripts together; when someone looks at a template that references templates/scripts/disable-fk.sql, the file should be next to it.

Wiring up the workspace​

workspace.json (or Workspace Settings → Paths in the UI) declares which folders hold templates:

{
  "paths": {
    "templates": [
      "templates"
    ]
  }
}

Paths are relative to the workspace root. Multiple folders are allowed; every .xml file in any listed folder is loaded.

What happens on git pull​

  • DataStar watches template folders, so changes from git pull take effect without restarting.
  • If a template is renamed or deleted, components it generated via a dynamic query disappear on next reload.
  • If a template is modified, subsequent extracts use the new version; existing generated components stay in place until re-extracted.

Patterns for larger teams​

Shared templates in a monorepo​

Several workspaces under one repo (for instance, one per service) can share a top-level templates/ folder. Each workspace's workspace.json references the shared folder with a relative path:

{
  "paths": {
    "templates": [
      "templates",
      "../shared/templates"
    ]
  }
}

Changes to the shared set affect every workspace on next reload.

Git submodule for cross-repo sharing​

If your templates need to be shared across repositories, pull them in via a submodule:

git submodule add ../templates-repo.git templates

Lock the submodule to a specific ref so updates are intentional:

cd templates && git checkout v2.1.0 && cd ..
git add templates && git commit -m "Pin templates to v2.1.0"

Versioning a template set​

For governed templates (think enterprise schema standards), tag releases:

git tag -a templates/v1.3.0 -m "Templates 1.3.0: adds DDL-trigger extraction"

Consumers update at their own pace by bumping the submodule ref or copying in a newer snapshot.

Conventions worth agreeing on​

When more than one person writes templates, agree on:

  • Weights. A conventional scheme (tables 100, functions 200, views 300, triggers 400, data 500) keeps deployments ordered correctly.
  • Option defaults. Standardise Permissions, Indexes, and CreateOrAlter across templates so generated scripts look consistent.
  • Dynamic-query filters. If a query should exclude system objects, write the filter once, in a comment, as the canonical WHERE …, and reuse it.
  • Static-script naming. verb-object.sql (for example, disable-order-fk.sql, rebuild-indexes.sql) so a diff is readable without opening the file.

When a template breaks​

If a teammate's git pull produces a broken workspace:

  1. Check the status bar for template-load errors; DataStar reports them individually.
  2. Open the XML file in an editor with XSD validation to catch malformed attributes.
  3. Revert the offending template with git log / git revert while the author investigates.

A broken template stops its own components from loading but doesn't affect the rest of the workspace.

See also​

Last updated on