From 3701553255dff98533bfd6b5dcf34ebd6f65f7eb Mon Sep 17 00:00:00 2001
From: MSBrett <223556219+Copilot@users.noreply.github.com>
Date: Tue, 21 Jul 2026 05:43:49 -0700
Subject: [PATCH] feature: document Kustainer emulator container-recreate
 reattach in azure-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 #2924

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 plugin/skills/azure-kusto/SKILL.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/plugin/skills/azure-kusto/SKILL.md b/plugin/skills/azure-kusto/SKILL.md
index 89f9fd04a..3aa0042f0 100644
--- a/plugin/skills/azure-kusto/SKILL.md
+++ b/plugin/skills/azure-kusto/SKILL.md
@@ -212,6 +212,28 @@ Switch to Azure CLI when:
 - Authentication failures with MCP tools
 - Empty response when database is known to have data
 
+## 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.
+
+**Persisting a database across container restarts** - mount a host folder to `/kustodata` and create the database with an explicit persist path:
+
+```kusto
+.create database MyDb persist (@"/kustodata/dbs/MyDb/md", @"/kustodata/dbs/MyDb/data")
+```
+
+**⚠️ Reattaching after the container is recreated** - stopping/removing and recreating the container (e.g. to change `--memory`, upgrade the image, or move hosts) against the *same* `/kustodata` bind mount does **not** auto-reattach previously-persisted databases. Only an empty built-in `NetDefaultDB` is created on every engine start - this is normal emulator behavior, not data loss.
+
+- **Symptom**: `.show databases` shows only `NetDefaultDB`; querying the expected database returns `BadRequest_EntityNotFound` - even though `/kustodata/dbs/<name>/` is fully intact on disk.
+- **Do NOT** re-run `.create database ... persist(...)` against the existing path. That command creates a *new* database; against metadata that already exists it fails instantly with a generic, unhelpful `Internal service error` regardless of database size - this is not a resource, disk-space, or size problem, it is simply the wrong command.
+- **Do** use the dedicated reattach command instead:
+
+  ```kusto
+  .attach database MyDb from @"/kustodata/dbs/MyDb/md"
+  ```
+
+  This registers existing on-disk metadata with the running engine in milliseconds. It only reads metadata - it does not move, copy, or delete extent/data files - so it's safe to run whenever you're unsure if a database is attached. Run one `.attach database` per previously-existing database after every container stop/rm/recreate before concluding data was lost.
+
 ## Common Issues
 
 - **Access Denied**: Verify database permissions (Viewer role minimum for queries)
@@ -221,6 +243,7 @@ Switch to Azure CLI when:
 - **Cluster Not Found**: Check cluster name format (exclude ".kusto.windows.net" suffix)
 - **High CPU Usage**: Query too broad - add filters, reduce time range, limit aggregations
 - **Ingestion Lag**: Streaming data may have 1-30 second delay depending on ingestion method
+- **Database Missing After Emulator Container Restart**: See "Local Kusto Emulator" above - use `.attach database <name> from @"<md-path>"`, not `.create database ... persist(...)`, to reattach existing on-disk data.
 
 ## Use Cases