|
| 1 | +# SQL Assessment API |
| 2 | + |
| 3 | +SQL Assessment API provides a mechanism to evaluate the configuration of your SQL Server for best practices. The API is delivered with a ruleset containing best practice rules suggested by SQL Server Team. This ruleset is enhancing with the release of new versions but at the same time, the API is built with the intent to give a highly customizable and extensible solution. So, users can tune the default rules and create their own ones. The API can be used to assess SQL Server versions 2012 and higher and Azure SQL Database Managed Instance (more to come). |
| 4 | + |
| 5 | +Learn more about the API on the [SQL Assessment API docs page](https://docs.microsoft.com/en-us/sql/sql-assessment-api/sql-assessment-api-overview). |
| 6 | + |
| 7 | +## QuickStart.md |
| 8 | + |
| 9 | +Learn how to assess your SQL Server configuration for best practices in 2 simple steps. |
| 10 | + |
| 11 | +## config.json |
| 12 | + |
| 13 | +This is the default set of rules shipped with SQL Assessment API. Feel free to open issues to have us fix or add rules. Also, we're happy to see your pull requests to this file. |
| 14 | + |
| 15 | +## DisablingBuiltInChecks_sample.json |
| 16 | + |
| 17 | +Contains three parts. First shows how you can disable a specified rule by its ID. The second disables all the rules with the "TraceFlag" tag. The last disables to run all rules of the default ruleset (using the DefaultRuleset tag) against databases named "DBName1" and "DBName2". |
| 18 | + |
| 19 | +## MakingCustomChecks_sample.json |
| 20 | + |
| 21 | +Demonstrates how to make a custom ruleset containing two checks. The sample contains two sections: `rules` and `probes`. `Rules` is for rule (sometimes referred to as check) definitions. Usually, rules are best practices or a company's internal policies that should be applied to SQL Server configuration. Here's one of the rules from this sample with explanations for each line: |
| 22 | + |
| 23 | +```json |
| 24 | +{ |
| 25 | + "target": { //Target describes a SQL Server object the check is supposed to run against |
| 26 | + "type": "Database", //This check targets Database object |
| 27 | + "version": "[13.0,)", //Applies to SQL Server 2016 and higher |
| 28 | + //Another example: "[12.0,13.0)" reads as "any SQL Server version >= 12.0 and < 13.0" |
| 29 | + "platform": "/^(Windows|Linux)$/", //Applies to SQL Server on Windows and Linux |
| 30 | + "engineEdition": "OnPremises, ManagedInstance", //Applies to SQL on Premises and Azure SQL Managed Instance. Here you can also filter specific editions of SQL Server |
| 31 | + "name": { "not": "/^(master|tempdb|model)$/" } //Applies to any database excluding master, tempdb, and msdb |
| 32 | + }, |
| 33 | + "id": "QueryStoreOn", //Rule ID |
| 34 | + "itemType": "definition", //Can be "definition" or "override". First is to declare a rule, the latter is to override/customize an existing rule. See also DisablingBuiltInChecks_sample.json |
| 35 | + "tags": [ "CustomRuleset", "Performance", "QueryStore", "Statistics" ], //Tags combine rules in different subsets. |
| 36 | + "displayName": "Query Store should be active", //Short name for the rule |
| 37 | + "description": "The Query Store feature provides you with insight on query plan choice and performance. It simplifies performance troubleshooting by helping you quickly find performance differences caused by query plan changes. Query Store automatically captures a history of queries, plans, and runtime statistics, and retains these for your review. It separates data by time windows so you can see database usage patterns and understand when query plan changes happened on the server. While Query Store collects queries, execution plans and statistics, its size in the database grows until this limit is reached. When that happens, Query Store automatically changes the operation mode to read-only and stops collecting new data, which means that your performance analysis is no longer accurate.", |
| 38 | + //A more detailed explanation of a best practice or policy that the rule check |
| 39 | + "message": "Make sure Query Store actual operation mode is 'Read Write' to keep your performance analysis accurate", |
| 40 | + //Usually, it's for recommendation what user should do if the rule raises up an alert |
| 41 | + "helpLink": "https://docs.microsoft.com/sql/relational-databases/performance/monitoring-performance-by-using-the-query-store", |
| 42 | + //Reference material |
| 43 | + "probes": [ "Custom_DatabaseConfiguration" ], //List of probes that are used to get the required data for this check. See below to know more about probes. |
| 44 | + "condition": { //Condition object is to define "good" and "bad" state, the latter is when the rule should raise an alert. When the condition is true, it means that the checked object complies with the best practice or policy. Otherwise, the rule raises an alert (it actually adds its message to the resulting set of recommendations) |
| 45 | + "equal": [ "@query_store_state", 2 ] //It means that the variable came from the probe should be equal to 2 |
| 46 | + } |
| 47 | +} |
| 48 | + |
| 49 | +``` |
| 50 | + |
| 51 | +`Probes` describes how and where to get the required data to check compliance with a rule. You can use T-SQL queries as well as methods from some assemblies. The probe below uses a T-SQL query. |
| 52 | + |
| 53 | +```json |
| 54 | +"Custom_DatabaseConfiguration": [ //Probe name is used to reference the probe from a rule |
| 55 | + //Probe can have a few implementations that will be used for different targets |
| 56 | + //This probe has two implementations for different version of SQL Server |
| 57 | + { |
| 58 | + "type": "SQL", //Probe uses a T-SQL query to get the required data. Use 'CLR' for assemblies. |
| 59 | + "target": { //Probes have their own target, usually to separate implementation for different versions, editions, or platforms. Probe targets work the same way as rule targets do. |
| 60 | + "type": "Database", |
| 61 | + "version": "(,12.0)", //This target is for SQL Server of versions prior to 2014 |
| 62 | + "platform": "/^(Windows|Linux)$/", |
| 63 | + "engineEdition": "OnPremises, ManagedInstance" |
| 64 | + }, |
| 65 | + "implementation": { //Implementation object with a T-SQL query. This probe is used in many rules, that's why the query return so many fields |
| 66 | + "query": "SELECT db.is_auto_create_stats_on, db.is_auto_update_stats_on, 0 AS query_store_state, db.collation_name, (SELECT collation_name FROM master.sys.databases (NOLOCK) WHERE database_id = 1) AS master_collation, db.is_auto_close_on, db.is_auto_shrink_on, db.page_verify_option, db.is_db_chaining_on, NULL AS is_auto_create_stats_incremental_on, db.is_trustworthy_on, db.is_parameterization_forced FROM [sys].[databases] (NOLOCK) AS db WHERE db.[name]=@TargetName" |
| 67 | + } |
| 68 | + }, |
| 69 | + { //This implementation object is to get the required data from SQL Server 2014 (look at target.version) |
| 70 | + "type": "SQL", |
| 71 | + "target": { |
| 72 | + "type": "Database", |
| 73 | + "version": "[12.0, 13.0)", |
| 74 | + "platform": "/^(Windows|Linux)$/", |
| 75 | + "engineEdition": "OnPremises, ManagedInstance" |
| 76 | + }, |
| 77 | + "implementation": { |
| 78 | + "query": "SELECT db.is_auto_create_stats_on, db.is_auto_update_stats_on, 0 AS query_store_state, db.collation_name, (SELECT collation_name FROM master.sys.databases (NOLOCK) WHERE database_id = 1) AS master_collation, db.is_auto_close_on, db.is_auto_shrink_on, db.page_verify_option, db.is_db_chaining_on, db.is_auto_create_stats_incremental_on, db.is_trustworthy_on, db.is_parameterization_forced FROM [sys].[databases] (NOLOCK) AS db WHERE db.[name]=@TargetName" |
| 79 | + } |
| 80 | + }, |
| 81 | + { |
| 82 | + "type": "SQL", //This implementation object is to get the required data from SQL Server 2016 and up (look at target.version) |
| 83 | + "target": { |
| 84 | + "type": "Database", |
| 85 | + "version": "[13.0,)", |
| 86 | + "platform": "/^(Windows|Linux)$/", |
| 87 | + "engineEdition": "OnPremises, ManagedInstance" |
| 88 | + }, |
| 89 | + "implementation": { |
| 90 | + "useDatabase": true, //Use this key if your query requires to run on a database that is being assessed (it's a replacement for 'USE <DATABASENAME>;') |
| 91 | + "query": "SELECT db.is_auto_create_stats_on, db.is_auto_update_stats_on, (SELECT CAST(actual_state AS DECIMAL) FROM [sys].[database_query_store_options]) AS query_store_state, db.collation_name, (SELECT collation_name FROM master.sys.databases (NOLOCK) WHERE database_id = 1) AS master_collation, db.is_auto_close_on, db.is_auto_shrink_on, db.page_verify_option, db.is_db_chaining_on, db.is_auto_create_stats_incremental_on, db.is_trustworthy_on, db.is_parameterization_forced FROM [sys].[databases] (NOLOCK) AS db WHERE db.[name]=@TargetName" |
| 92 | + } |
| 93 | + } |
| 94 | +] |
| 95 | +``` |
0 commit comments