This C# project provides functionality to work with schemas in Azure Data Explorer (Kusto). You can load a schema from yaml files or a database to the interal data structure. This can be used for creating diffs of two databases as scripts or markdown, and also to write it back to files or update schemas in a database.
A second project "KustoSchemaToolsAction" wraps that into a CLI tool inside a docker container for usage in GitHub Actions.
The database
object holds all schema related information for a Kusto database. It can be loaded from, or written to a cluster using the KustoDatabaseHandler
which can be created by the KustoDatabaseHandlerFactory
. There are several steps involved for loading all relevant information from a kusto database into the database
object. These are covered by different plugins, which can be configured for the KustoDatabaseHandlerFactory
.
var dbFactory = new KustoDatabaseHandlerFactory(sp.GetService<ILogger<KustoDatabaseHandler>>())
.WithPlugin<KustoDatabasePrincipalLoader>()
.WithPlugin<KustoDatabaseRetentionAndCacheLoader>()
.WithPlugin<KustoTableBulkLoader>()
.WithPlugin<KustoFunctionBulkLoader>()
.WithPlugin<KustoMaterializedViewBulkLoader>()
.WithPlugin<DatabaseCleanup>()
For synchronizing it to files, the YamlDatabaseHandler
and the YamlDatabaseHandlerFactory
are the right tools. To prevent super large files, there are plugins that handle reading and writing functions, tables and materialized views to separate files and folders. They can be configured for the YamlDatabaseHandlerFactory
.
var yamlFactory = new YamlDatabaseHandlerFactory()
.WithPlugin(new TablePlugin())
.WithPlugin(new FunctionPlugin())
.WithPlugin(new MaterializedViewsPlugin())
.WithPlugin<DatabaseCleanup>();
Additional features can be added with custom plugins. A sample for table groups
, where some parts of the schema are defined once, but are applied for several tables can be found in here.
The KustoSchemaHandler
is the central place for synching schemas between yaml and a database. It offers functions for generating changes formatted in markdown, writing a database to yaml files and applying changes from yaml files to a database.
Cluster configuration changes are handled by the KustoClusterOrchestrator
. Currently, the only supported feature is Capacity Policies
. The orchestrator expects a file path to a configuration file. A key design principle is that you only need to specify the properties you wish to set or change. Any property omitted in your policy file will be ignored, preserving its current value on the cluster.
A sample file could look like this:
connections:
- name: test
url: test.eastus
capacityPolicy:
ingestionCapacity:
clusterMaximumConcurrentOperations: 512
coreUtilizationCoefficient: 0.75
extentsMergeCapacity:
minimumConcurrentOperationsPerNode: 1
maximumConcurrentOperationsPerNode: 3
extentsPurgeRebuildCapacity:
maximumConcurrentOperationsPerNode: 1
The KustoClusterOrchestrator
coordinates between cluster handlers to manage cluster configuration changes:
- Loading Configuration: Uses
YamlClusterHandler
to parse the YAML configuration file and load the desired cluster state - Reading Current State: Uses
KustoClusterHandler
to connect to each live cluster and retrieve the current capacity policy settings - Generating Changes: Compares the desired state (from YAML) with the current state (from Kusto) to identify differences
- Creating Scripts: Generates the necessary Kusto control commands (like
.alter-merge cluster policy capacity
) to apply the changes - Applying Updates: Executes the generated scripts against the live clusters to synchronize them with the desired configuration
Currently no plugins are supported. The orchestrator expects all cluster configuration in a central file.
Currently following features are supported:
- Database
- Permissions
- Default Retention
- Default Hot Cache
- Tables
- Columns
- Retention
- HotCache
- Update Policies
- Docstring
- Folder
- Functions
- Body
- Docstring
- Folder
- Preformatted
- Materialized Views
- Query
- Retention
- HotCache
- Docstring
- Folder
- Preformatted
- External Tables (managed identity/impersonation only)
- Storage / Delta / SQL
- Folder
- Docstring
- Continuous Exports
- Entity Groups
- Deleting existing items using deletions in the database definition
- Tables
- Columns
- Functions
- Materialized Views
- Extenal Tables
- Continuous Exports
The DatabaseCleanup
will remove redundant retention and hotcache definitions.
It will also pretty print KQL queries in functions (unless the preformatted
feature is used) , update policies, materialized views and continuous exports.