AKML SQL — Configuration Guide Updated

The configuration file is stored at:

%AppData%\AKML SQL\config.json

It is created automatically on first run with all defaults. The file is written atomically (temp-file + rename) to prevent corruption.

#Full Schema

{
  "configVersion": 1,
  "autoUpdateEnabled": true,
  "telemetryEnabled": true,
  "logMinimumLevel": "Debug",
  "lastUpdateCheck": null,
  "installId": "00000000-0000-0000-0000-000000000000",
  "nativeIntelliSensePrompted": false,
  "disabledNativeIntelliSense": false,
  "installedTargets": [],

  "intelliSense": {
    "enabled": true,
    "autoTrigger": true,
    "triggerDelayMs": 0,
    "afterDot": true,
    "maxSuggestions": 50,
    "fuzzyMatch": true,
    "showDataTypes": true,
    "showNullability": true,
    "showPkFk": true,
    "autoAlias": true,
    "joinAssist": true,
    "keywordCase": "Upper",
    "disableNativeIntelliSense": true
  },

  "cache": {
    "autoRefresh": true,
    "refreshIntervalSeconds": 300,
    "detectDdl": true,
    "maxDatabases": 10,
    "lazyLoadColumns": true,
    "persistToDisk": true,
    "persistPath": ""
  },

  "formatter": {
    "enabled": true,
    "activeProfile": "Khamis Style",
    "formatOnPaste": false,
    "formatOnSave": false,
    "formatOnDelimiter": false,
    "shortcutKey": "Ctrl+K, Y",
    "showProfileInStatusBar": true,
    "confirmBulkFormat": true,
    "createBackups": true,
    "respectNoformat": true,
    "handleParseErrors": true,
    "semanticValidation": true
  },

  "snippets": {
    "enabled": true,
    "showInCompletion": true,
    "triggerKey": "Tab",
    "formatOnExpand": true,
    "personalFolder": "",
    "teamFolder": "",
    "contextFilter": true,
    "surroundShortcut": "Ctrl+K, Ctrl+S",
    "trackUsage": true
  },

  "codeAnalysis": {
    "enabled": true,
    "runOnType": true,
    "runOnSave": true,
    "autoFixOnFormat": false,
    "squiggleStyle": "underline",
    "showInErrorList": true
  },

  "refactoring": {
    "previewBeforeApply": true,
    "createBackups": true,
    "formatAfterRefactor": true,
    "renameScope": "currentScript",
    "includeCommentsInRename": true,
    "includeStringLiteralsInRename": false
  },

  "postgreSql": {
    "enabled": true
  }
}

#Top-Level Settings

#intelliSense Section

#cache Section

#formatter Section

formatSqlActions (Options › Format › When you run Format SQL, AKML SQL will:):

#tabs Section

Tab colouring by environment (Options › Queries › Color). Only the environment keys are listed here.

#snippets Section

#codeAnalysis Section

#refactoring Section

#postgreSql Section

Spec 042. PostgreSQL support in the engine and the web edition is one switchable unit.

Remembered PostgreSQL passwords (the opt-in "Remember password" per saved connection) are kept by the engine in sql-credentials.json, the same DPAPI-protected store as SQL Server logins, under the server key pg://{host}:{port} and the user name. On the web engine service (which runs as LocalSystem) this means any administrator of that machine can read them.

#ai Section

Schema information sent to a provider never includes table data rows — metadata only (FR-032). The chat panel and all AI commands bind to the active editor's connection; when no editor is connected the assistant says so instead of answering from an empty schema (FR-028).

#Multiple agents (spec 037)

ai.agents is the truth for which provider serves AI requests. The flat provider/model/apiKey/endpoint/maxTokens/temperature/timeout/retries above are a derived mirror of the active agent, rewritten by AiAgentResolver.MirrorActiveAgent on every ConfigManager.Load (inside Normalize) and every ConfigManager.Save. The mirror keeps the file downgrade-safe: an older build reads the flat fields and ignores ai.agents, so it uses the same provider the new build would. When agents is empty the flat fields are the whole configuration and are left untouched — that is the pre-migration shape the V14 migration rescues on the next load.

Each agents[] entry:

health carries status (unknown / ready / needsKey / failed — an unrecognised value loads as unknown, V20), checkedUtc, latencyMs (round trip of the last successful check) and message (≤ 500 chars, never contains a key).

Load-time migration and repairs all live in AiAgentResolver.Normalize, are idempotent, and never throw: V14 turns an empty agents list with a non-empty flat provider into exactly one agent named for the provider's display name, enabled, never health-tested, and active, copying the key verbatim; V15 drops malformed entries (empty or duplicate id) with a log warning naming the index; V21 drops entries beyond the 20th. An agent counts as usable when it is enabled, names a canonical provider, has a model, and carries every field its provider requires (key for the cloud providers, endpoint for azure/custom).

#Per-Project Settings (.casettings)

Individual rule overrides can be placed in a .casettings JSON file anywhere in the project directory hierarchy. The engine searches from the current file's directory upward.

{
  "rules": {
    "PE001": { "severity": "Warning", "enabled": true },
    "SE001": { "severity": "Error",   "enabled": true },
    "ST001": { "enabled": false }
  },
  "globalSuppressions": [
    { "ruleId": "NM002", "reason": "Legacy naming convention" }
  ]
}

#Rule severity values

"None" | "Info" | "Warning" | "Error"

#Inline suppressions

-- akml-disable PE001
SELECT * FROM dbo.Orders   -- suppressed
-- akml-enable PE001

Or single-line:

SELECT * FROM dbo.Orders  -- akml-disable-line PE001

Omit the -- akml-enable and the suppression runs to the end of the file, which is how the "Disable … in this script" quick fix works. Rule ids are comma-separated (-- akml-disable PE001, BP004); omitting them entirely suppresses every rule; trailing text is treated as a note. The directives are case-insensitive, work inside /* … */, and the original -- noqa: / -- noqa-begin / -- noqa-end forms are still honoured.

#Session-only suppressions

The quick-fix menu also offers Disable … for this session, which is held in the engine process and written nowhere. It ends when the IDE closes, or from the Restore button in Manage Code Analysis Rules. Because it is not persisted there is no config.json key for it.

#Persistence Markers (Spec 020)

Spec 020 (SQL Prompt visual parity) introduced two state files alongside config.json:

Both files are written defensively — failures are caught and logged at Debug level; they never block extension startup or editor interaction.

#Formatting Profiles (.akmlstyle)

Profiles are stored in:

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

Built-in profiles (read-only) are embedded in the extension. The profile format is a JSON file with a metadata block plus formatting option sections. See formatting.md for the full profile schema.

#Web edition: editor settings (Settings › Editor)

The web edition keeps its editor options in the browser (IndexedDB database AkmlSqlWeb, store analysisSettings, key editorSettings), not in config.json. Settings › Export carries them in the editor section.

The font and the size apply to every surface that shows SQL: the editor, its completion list and hover help, SQL History's preview, the Format styles preview, snippet bodies and AI answers. Line spacing is the theme token --akml-type-editor-line-height (1.25, from docs/theme-tokens.json), not a setting.

#Log Configuration

Logs are written to:

%AppData%\AKML SQL\logs\akmlsql-YYYYMMDD.log

• Rolling interval: daily
• Max file size: 5 MB (rolls on size limit)
• Retained files: 10
• Format: {Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}
• One file per process: the file sink holds its file exclusively, so when the SSMS extension, the engine and the updater run at the same time, each one after the first rolls to the next free name — akmlsql-YYYYMMDD_001.log, _002, … After a size or day roll a process can also append to a file another process wrote earlier and has closed. Every time a process opens a log file it first writes AKML SQL {Version} log file opened by {Process} (pid {Pid}) (ProcessHeaderHooks), which is how View Logs labels the Source of each entry; its default view merges all of the newest day's files, newest first.

To change the log level without editing JSON directly, set logMinimumLevel in config.json:

{ "logMinimumLevel": "Information" }

#Site settings (spec 038)

The product site (src/AkmlSql.Site) has its own owner-editable settings, stored in a site_settings table inside the same analytics.db the metrics use — not in appsettings.json. Writing to the deployed config file would restart the application on every settings change, turning a one-second toggle into a cold start.

Edit them at /admin/settings. Changes take effect on the next public request; no deploy, no restart.

Out-of-range values are rejected with a message naming the bound, never silently clamped — a clamp leaves the owner believing they saved something they did not.

If the settings table cannot be read at all, the site serves the documented defaults and reports the failure in the logs, on /health (settingsLoaded: false) and in the portal. It is never fatal: the download page must not break for a reason unrelated to releases.

Visibility governs advertising, not reachability. A release hidden from the page is still downloadable by a link published earlier, and still counted. /dl/{file} has no reference to the settings store at all, which is asserted structurally by a test.

#Visitor data and consent

After spec 038 the site stores, only for visitors who explicitly accept:

• the full client IP address, and
• a persistent first-party identifier in the akml.vid cookie.

For everyone else — declined, or not yet answered — both columns stay NULL and only the per-day salted hash, the truncated network prefix (/24 or /48) and the derived country are written, exactly as before. The gate is enforced in AnalyticsStore, not at the call site, so no caller can bypass it.

The consent request is shown to every visitor with no recorded choice, regardless of country, and is non-blocking — a visitor can ignore it and complete the whole download path. Silence leaves the choice unresolved and is never treated as consent; an explicit dismissal records a refusal.

Two retention boundaries apply:

• identifiable_retention_days (site setting, default 365) — ip and visitor_id are nulled in place, keeping the row, so country and version totals for old periods still reconcile.
• Analytics:RetentionDays (appsettings.json, default 400) — whole rows deleted.

Both run in the post-start maintenance service, never inline at startup.

#Geo database

Country is resolved at write time from GeoLite2-Country.mmdb. Without that file every country reads "Unknown", and installing it later cannot backfill existing rows. Obtain a MaxMind licence key and run scripts/update-geoip.ps1.