relspecgo/vscode-extension/relspec-template-editor

RelSpec Template Editor for VS Code

Visual editor and tooling for RelSpec PostgreSQL migration templates.

Features

1. Template Preview

• Command: RelSpec: Preview Template
• Shortcut: Click the preview icon in the editor title bar
• Preview your templates with sample data
• Side-by-side view of template, data, and rendered SQL

2. Syntax Validation

• Command: RelSpec: Validate Template
• Automatic validation on save (configurable)
• Highlights syntax errors inline
• Checks for unclosed template tags

3. IntelliSense

• Auto-completion for template functions
• Function signatures and documentation on hover
• Keyword completions (if, range, template, etc.)

4. Template Scaffolding

• Command: RelSpec: New Template
• Quick scaffolding for common template types:
  • DDL operations
  • Constraints
  • Indexes
  • Audit trails
  • Reusable fragments

5. Function Library

• Command: RelSpec: List Available Functions
• Browse all available template functions
• See examples and documentation
• Quick reference for template development

Installation

From Source

1. Clone the RelSpec repository
2. Navigate to the extension directory:

   cd vscode-extension
   

3. Install dependencies:

   npm install
   

4. Compile the extension:

   npm run compile
   

5. Open in VS Code:

   code .
   

6. Press F5 to launch the extension in a new window

From VSIX (when published)

code --install-extension relspec-template-editor-0.1.0.vsix

Usage

Opening Templates

1. Open your RelSpec project in VS Code
2. Navigate to pkg/writers/pgsql/templates/
3. Open any .tmpl file
4. The extension will automatically activate

Previewing Templates

1. Open a template file
2. Click the preview icon in the editor title bar OR
3. Run command: RelSpec: Preview Template (Ctrl+Shift+P)
4. The preview pane will show:
   • Your template source
   • Sample data (configurable)
   • Rendered SQL output

Configuring Sample Data

Set custom sample data for preview in settings:

{
  "relspec.previewSampleData": {
    "SchemaName": "public",
    "TableName": "users",
    "ColumnName": "email",
    "Columns": [
      {"Name": "id", "Type": "integer", "NotNull": true},
      {"Name": "email", "Type": "text"}
    ]
  }
}

Creating New Templates

1. Run command: RelSpec: New Template
2. Select template type
3. Enter template name
4. The extension creates a scaffolded template
5. Edit and customize

Using IntelliSense

Type {{ to trigger auto-completion:

{{upper  // Shows function signature and documentation
{{.     // Shows available fields from data structure

Hover over function names to see:

• Function signature
• Description
• Usage examples

Configuration

Available settings:

Setting	Type	Default	Description
relspec.templatePath	string	pkg/writers/pgsql/templates	Path to template directory
relspec.autoValidate	boolean	true	Validate templates on save
relspec.showDataStructures	boolean	true	Show data structure hints in preview
relspec.previewSampleData	object	{}	Sample JSON data for preview

Keyboard Shortcuts

Command	Shortcut	Description
Preview Template	N/A	Click preview icon in title bar
Validate Template	N/A	Use command palette
New Template	N/A	Use command palette

Template Functions Reference

The extension provides IntelliSense for all RelSpec template functions:

String Manipulation

• upper - Convert to uppercase
• lower - Convert to lowercase
• title - Title case
• snake_case - Convert to snake_case
• camelCase - Convert to camelCase

SQL Formatting

• indent - Indent text
• quote - Quote for SQL
• escape - Escape special characters
• safe_identifier - Make safe SQL identifier

Type Conversion

• goTypeToSQL - Go type → SQL type
• sqlTypeToGo - SQL type → Go type
• isNumeric - Check if numeric type
• isText - Check if text type

Collection Helpers

• first - First element
• last - Last element
• filter - Filter elements
• mapFunc - Map function
• join_with - Join with separator
• join - Join strings

See full documentation: Template Functions

Code Snippets

The extension includes snippets for common patterns:

Prefix	Description
tmpl-define	Define a new template
tmpl-template	Use a template
tmpl-block	Define a block
tmpl-if	If statement
tmpl-range	Range loop
tmpl-with	With statement

Development

Building

npm run compile

Watching

npm run watch

Linting

npm run lint

Testing

npm test

Troubleshooting

Extension Not Activating

Problem: Extension doesn't activate when opening .tmpl files

Solution:

1. Check that file has .tmpl extension
2. Reload VS Code window (Ctrl+Shift+P → "Reload Window")
3. Check extension is enabled in Extensions panel

Preview Not Working

Problem: Preview shows error or doesn't update

Solution:

1. Ensure RelSpec binary is in PATH
2. Check template syntax is valid
3. Verify sample data is valid JSON

IntelliSense Not Working

Problem: Auto-completion doesn't trigger

Solution:

1. Type {{ to trigger
2. Check language mode is set to "Go Template"
3. Reload window

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

Same as RelSpec project license.

Links

• RelSpec Documentation
• Template Documentation
• Template Inheritance
• Issue Tracker

Changelog

0.1.0 (Initial Release)

• Template preview with sample data
• Syntax validation
• IntelliSense for functions
• Template scaffolding
• Function library browser