From f5b16bbaf863e8867f632caa5c712fb42fc1fda5 Mon Sep 17 00:00:00 2001 From: Ben Martens Date: Mon, 2 Nov 2026 08:46:57 -0800 Subject: [PATCH] Simplify README --- README.md | 22 ++-------------------- 1 file changed, 2 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index b7a779d..7cfadaf 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,8 @@ The Sync Kusto tool was built to help create a maintainable development process ![Screenshot](/screenshot.png) -To regenerate this image automatically, see [Refreshing the README screenshot](CONTRIBUTING.md#refreshing-the-readme-screenshot). - ## Scope -This tool is intended specifically for the developer desktop scenario. It will not help if you need to build an automated syncing process, generate change scripts, sync policies, etc. For all of that, we recommend using [Delta Kusto](https://github.com/microsoft/delta-kusto). +This tool is intended specifically for the developer desktop scenario. It will not help if you need to build an automated syncing process, generate change scripts, sync policies, etc. For all of that, we recommend using [Delta Kusto](https://github.com/microsoft/delta-kusto) and/or [automated provisioning options](https://docs.azure.cn/en-us/data-explorer/automated-deploy-overview). ## Getting Started Assuming that the user already has a Kusto database with functions and tables, set the Kusto database as the source and the local file system as the target. Before your first comparison, open **Settings** and configure a dedicated temporary cluster and database as described below. Press the compare button and the tool will find that none of the database objects are in the target. Press the update button to download everything from Kusto to the local file system. @@ -16,25 +14,9 @@ Assuming that the user already has a Kusto database with functions and tables, s The general usage pattern on our team is to make changes in a Kusto dev database which starts with a schema that mirrors the production database. Once the developer is satisfied with the changes, they use Sync Kusto with the development database as the source and their local file system as the target. The changes are committed to source control and a pull request is sent out for review. After the request is approved and the code merges to master, the developer syncs the master branch and uses Sync Kusto to sync from their local file system to the production Kusto database. This is a more flexible/manual version of the [Azure Data Explorer task for Azure Dev Ops](https://docs.microsoft.com/en-us/azure/data-explorer/devops). We've had great success with this process and use the tool daily to help with our development and for deploying to production assets. ## Sync Kusto Binaries -The release can be downloaded from the [GitHub Releases](https://github.com/microsoft/synckusto/releases) page. Individual builds can also be found in the [GitHub Actions](https://github.com/microsoft/synckusto/actions/workflows/official.yml) page, or the repo can be cloned and built in Visual Studio. The framework-dependent Windows application requires the [.NET 10 Windows Desktop Runtime](https://dotnet.microsoft.com/download/dotnet/10.0) matching the application's architecture. +The release can be downloaded from the [GitHub Releases](https://github.com/microsoft/synckusto/releases) page. ## Settings -Changes take effect as soon as you successfully click **OK**; restarting the app is not required. If any settings changed, the previous comparison is cleared and you must click **Compare** again before **Update**. Canceling, failing validation, or declining the temporary-database warning does not save changes. Settings cannot be changed while a comparison or update is running. - -### Schema pickers and authentication -Changing an authentication mode, application ID, key, or certificate in either schema picker preserves the comparison, checked changes, and skipped-file report. **Update** uses the target's current credentials with a new Kusto client, without comparing or normalizing files again. Incomplete target credentials must be corrected before updating; the comparison is kept. Source credential edits apply the next time an operation connects to Source, such as **Compare**; Update uses the already compared source data. - -Changing a cluster, database, folder, or source type still clears the comparison and requires another **Compare**. Changes saved in the separate **Settings** dialog also still clear it. Pickers cannot be edited while an operation is running. - -**Select Folder** opens the native picker with a short "Select schema folder" title and the current folder selected. A file-backed comparison remembers its folder before loading schemas, even if a later Kusto operation fails. This is one shared last-used folder, restored into both pickers on the next launch; when both sides use files, Target is remembered last. Merely browsing, canceling, or editing an inactive folder field does not change the remembered value. - -### Kusto errors -Compare, Update, and Kusto settings-validation failures show a short operation heading with always-visible, read-only, scrollable error details. Select and copy the original Kusto diagnostics, including inner/aggregate errors and failed object names, without opening a separate Details section. Long errors stay within a resizable window. Diagnostics do not append picker credentials or settings; rejected-file input messages remain concise and do not include rejected file contents. - -File-system diagnostics distinguish missing folders/files, access denials, and wrapped I/O errors. Schema parse failures list the affected objects with guidance to correct their definitions and compare again. - -### Window icons -The main window, Kusto error details, skipped-file report, Settings, and Drop Warning use the same SyncKusto icon as the executable. Folder and certificate pickers and ordinary message boxes remain Windows-native and are owned by the calling SyncKusto window. Their APIs do not expose a custom caption-icon option: Windows controls whether they inherit the owner's icon, show a native icon, or show no caption icon. Standard error, warning, information, and question symbols in message content are unchanged. ### Temporary Databases When the local file system is selected as either the source or the target, Sync Kusto loads its schema definitions into the configured temporary database for Kusto-backed normalization. Specify both a cluster and an existing database where you have permissions to create and delete functions and tables. All selected files on both sides are read and checked before opening a temporary client or changing that database. Files rejected by the schema-command checks are skipped and reported; only accepted definitions are loaded. After checking both sides, **all existing functions and tables in the temporary database are deleted before loading each file-backed side**. If the database is not empty when you configure it, Settings asks you to confirm that it can be wiped before saving. Use a dedicated scratch database containing no valuable objects or data. Do not point it at a source or target Kusto database. If two users share a temporary database concurrently, results can be incorrect; give each user their own.