AKML SQL — Formatter Reference

Overview

The SQL formatter rewrites T-SQL text according to a formatting profile (.akmlstyle), preserving semantic equivalence. It runs as part of the out-of-process Engine and is invoked via the IPC API.

Formatting Pipeline

The pipeline processes SQL in sequential stages. Failures in the semantic validation stage cause the original SQL to be returned unchanged.

Input SQL
  Stage 0a: NoformatScanner      → identifies -- noformat / -- endnoformat regions
  Stage 0b: SqlcmdPreprocessor   → replaces :r / :setvar directives with placeholders
  Stage 1:  TSql170Parser        → parses into TSqlScript AST
  Stage 2:  AstAnnotator         → attaches comments to AST nodes
  Stage 3:  LayoutEngine         → produces LayoutNode list (tokens + whitespace rules)
  Stage 4:  CasingEngine         → applies keyword/identifier casing from profile
  Stage 5:  TextEmitter          → emits formatted string
  Stage 5b: SqlcmdPreprocessor   → restores SQLCMD placeholders
  Stage 6:  SemanticValidator    → re-parses both versions; normalizes and compares
  Stage 7:  IdempotencyCheck     → formats again; verifies output is identical
Output FormattedSQL

Stage details

Stage 6 failure: returns original SQL unchanged. Stage 7 failure: returns the (possibly non-idempotent) formatted SQL with a diagnostic warning appended.

noformat Regions

Wrap any block you want the formatter to skip:

-- noformat
SELECT   weird   spacing   FROM   dbo.LegacyTable
-- endnoformat

The NoformatScanner identifies these regions before parsing, so even syntactically unusual SQL is safe.

Profile Files (.akmlstyle)

Profiles are stored as JSON files:

%AppData%\AKML SQL\profiles\{name}.akmlstyle

Built-in profiles (read-only) are embedded in the extension. User profiles can be created, edited, imported, and exported via the Options UI.

Profile file structure

{
  "metadata": {
    "id": "d3b07384-d9a4-4b8b-9a1d-3b4f5c6d7e8f",
    "schemaVersion": 1,
    "name": "My Profile",
    "description": "Adapted from Default",
    "author": "Jane Dev",
    "version": "1.0.0",
    "created": "2024-06-01T12:00:00Z",
    "modified": "2024-07-15T09:30:00Z",
    "basedOn": null,
    "isBuiltIn": false,
    "skipValidation": false,
    "enableIdempotencyCheck": true
  },
  "whitespace": { ... },
  "casing": { ... },
  "list": { ... },
  "parenthesis": { ... },
  "dml": { ... },
  "join": { ... },
  "ddl": { ... },
  "controlFlow": { ... },
  "case": { ... },
  "cte": { ... },
  "expression": { ... },
  "actions": { ... }
}

Profile Options Reference

metadata

whitespace

Controls line breaks, indentation, and spacing.

casing

Controls keyword and identifier casing.

list

Controls how lists of items (SELECT columns, parameters, etc.) are laid out.

parenthesis

Controls formatting of parenthesized groups (subqueries, expressions, parameter lists).

dml

Controls DML (SELECT, INSERT, UPDATE, DELETE, MERGE) statement layout.

join

Controls JOIN clause formatting.

ddl

Controls DDL (CREATE TABLE, CREATE PROCEDURE, etc.) statement layout.

controlFlow

Controls BEGIN/END, IF/ELSE, TRY/CATCH, and WHILE formatting.

case

Controls CASE … WHEN … THEN … ELSE … END expression layout.

cte

Controls Common Table Expression (CTE) formatting.

expression

Controls expression and predicate formatting.

actions (Format Action Config)

Controls which transformations are applied during Format Document / Format Action operations.

SQL Prompt Style Interop (Spec 020)

.sqlpromptstylev2 (Redgate SQL Prompt's distributed XML format) is supported for both import and export, allowing teams to standardise across SQL Prompt and AKML installs.

Import — SqlPromptImporter.Import(xmlContent) in src/AkmlSql.Formatting/Profiles/SqlPromptImporter.cs. Handles both <Options><Option Name= Value=> and flat-element XML shapes. Returns a SqlPromptImportResult with the imported FormattingProfile plus MappedCount / UnmappedCount / UnmappedOptions[] so the editor can surface unsupported settings.

Export — SqlPromptExporter.Export(profile) in src/AkmlSql.Formatting/Profiles/SqlPromptExporter.cs. Round-trip safe: every setting in SqlPromptImporter.OptionMap has a parallel inverse getter in SqlPromptExporter.ReverseMap. Settings AKML supports but SQL Prompt has no equivalent for are omitted from the export.

Round-trip test definition (SC-007 / Q1 clarification): for each (input.sql × style.sqlpromptstylev2) pair, AKML's formatted output is compared to SQL Prompt's golden output as follows:

1. Strip trailing whitespace per line
2. Normalise line endings to \n (LF)
3. Drop UTF-8 BOM if present
4. Then require byte-exact equality

A pair passes iff the two normalised byte streams are equal. The corpus suite passes iff ≥ 95 % of pairs pass. See tests/format-parity/README.md for the corpus layout.

Format Settings Schema — the canonical descriptor consumed by the Format Styles editor lives at src/AkmlSql.Formatting/Profiles/FormatSettingSchema.cs. Built by reflection over FormattingProfile's 12 sub-category POCOs, exposed to the shell via the RequestStyleEditorSchema IPC (see doc/ipc-api.md).

Format Actions (IPC)

Format operations can target specific transformations using the FormatActionType enum:

Bulk Formatting

The BulkFormatter applies formatting to multiple files in parallel (up to Environment.ProcessorCount threads). Configuration:

• confirmBulkFormat: show confirmation dialog before starting
• createBackups: write .bak files alongside originals
• handleParseErrors: skip files with parse errors instead of aborting
• respectNoformat: honour -- noformat regions in all files

Bulk format can be cancelled mid-operation via the BulkFormatCancel IPC message.

Diagnostic Codes

The formatter may emit diagnostics alongside the formatted output: