feature: document Kustainer emulator container-recreate reattach in azure-kusto skill - #2925
Closed
Brett Wilson (MSBrett) wants to merge 1 commit into
Closed
Conversation
…zure-kusto skill Adds a "Local Kusto Emulator (Kustainer / Docker)" section to the azure-kusto skill documenting the correct way to reattach a previously persisted database after the emulator container is stopped/removed and recreated against the same /kustodata bind mount. Root cause documented: `.create database ... persist(...)` is for first-time creation and fails with a generic, unhelpful `Internal service error` when pointed at metadata that already exists on disk (reproduced identically on both a 408KB and a 49GB database, ruling out size/resource causes). The correct reattach command is `.attach database <name> from @"<md-path>"`, which registers existing metadata in milliseconds without touching data files. Also adds a one-line pointer in "Common Issues" for discoverability. Verified via live, first-party incident reproduction: post-attach row counts matched pre-incident ground truth exactly on a 40M+ row table. Closes microsoft#2924 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Brett Wilson (MSBrett)
requested review from
Rick Winter (RickWinter) and
Sai Koumudi Kaluvakolanu (saikoumudi)
as code owners
July 21, 2026 12:44
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds documentation to the azure-kusto skill clarifying how to persist and reattach databases when using the local Azure Data Explorer Docker emulator (Kustainer), specifically addressing the common “database disappeared after container recreation” scenario.
Changes:
- Adds a new “Local Kusto Emulator (Kustainer / Docker)” section explaining persist paths and the correct
.attach database ... fromreattach workflow after container recreation. - Updates “Common Issues” with a direct pointer to use
.attach database(not.create ... persist(...)) when the emulator container is restarted/recreated.
|
|
||
| ## Local Kusto Emulator (Kustainer / Docker) | ||
|
|
||
| Azure Data Explorer ships a Docker emulator (`mcr.microsoft.com/azuredataexplorer/kustainer-linux`) for offline/local development. It exposes the same REST endpoints (`/v1/rest/query`, `/v1/rest/mgmt`) as a real cluster, but has emulator-specific lifecycle behavior that differs from a managed ADX cluster. |
There was a problem hiding this comment.
Could you please create a reference file for the local development instructions and link from here?
JasonYeMSFT (JasonYeMSFT)
requested changes
Jul 30, 2026
Contributor
|
This PR has been automatically closed because it has unresolved review comments and no new commits in the last 28 days. If you would still like to merge these changes, please:
Thank you for your contribution! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a "Local Kusto Emulator (Kustainer / Docker)" section to
plugin/skills/azure-kusto/SKILL.md, documenting how to reattach a previously-persisted database after the emulator container is stopped/removed and recreated against the same/kustodatabind mount. Also adds a one-line pointer in "Common Issues".Why
Recreating the Kustainer container (e.g. to bump
--memory) does not auto-reattach existing databases - only the empty built-inNetDefaultDBis created on engine start. The instinctive fix (re-running the canonical creation command,.create database ... persist(...)) fails with a genericInternal service errorwhen pointed at metadata that already exists on disk, which is easy to misread as data loss. The correct command is the distinct.attach database <name> from @"<md-path>", which registers existing metadata in milliseconds without touching any data files.This was root-caused via live, first-party incident reproduction: the failing
.create ... persist(...)command failed identically and near-instantly (flat CPU/memory) on both a 408KB and a 49GB database, ruling out size/resource causes;.attach database ... fromsucceeded in ~0.15s for both, and post-attach row counts matched pre-incident ground truth exactly on a 40M+ row table.Scope
Documentation only - no new MCP tools, activation triggers, or frontmatter changes.
Validation
npm run checkCopilotCliCharBudget(scripts/): passes, unaffected (description text unchanged).npm run frontmatter -- plugin/skills/azure-kusto/SKILL.md(scripts/): only the pre-existingmetadata.version "0.0.0-placeholder"notice appears, confirmed present identically on an untouched skill (azure-storage) - i.e. unrelated to this change and expected pre-build (versions are stamped by Nerdbank.GitVersioning at build time perdocs/Onboarding.md).vallyeval suite in this environment (requires live agent/Azure integration); this is a targeted textual addition to an existing skill's "Common Issues"/reference material, not a new skill or new trigger surface.Closes #2924