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.

Sharing across repositories​

Most teams keep templates in the same repo as their components, so the layout above is all you need. You only need this if a single template set has to be shared across separate repositories.

Keep the shared set in its own repo and bring it into each consuming workspace as a git submodule (or subtree) in its own folder - not over your local templates/:

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

Then list that folder alongside your own templates in workspace.json:

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

Pin the submodule to a tag or commit so updates are deliberate rather than automatic:

cd shared/templates && git checkout v1.3.0 && cd ..
git add shared/templates && git commit -m "Pin shared templates to v1.3.0"

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