github/sql-server-samples
1
0
Fork 0
mirror of https://github.com/Microsoft/sql-server-samples.git synced 2025-12-08 14:58:54 +00:00
Code Issues Releases Wiki Activity

Update SQL Assessment APi documentation

Browse Source 
- Add descriptions for custom rule set concepts
- Addd reference docs for custom rule sets
- Update existing docs for 4-level severity
This commit is contained in:
Aleksei Guzev
2022-09-21 21:40:10 +03:00
parent f87a898006
commit 22b2374fc4
46 changed files with 2216 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
samples/manage/sql-assessment-api/docs/How-To/QuickStart.md
+64
View File
@@ -0,0 +1,64 @@
# SQL Assessment API Quick Start Guide
Assess your SQL Server configuration in 2 simple steps.
## 1. Setup
Install the [PowerShell SqlServer module](https://www.powershellgallery.com/packages/SqlServer) using the following command.
```PowerShell
Install-Module -Name SqlServer -AllowClobber
```
## 2. Invoke assessment
To invoke an assessment against a local SQL Server instance, run the following command.
```PowerShell
Get-SqlInstance -ServerInstance 'localhost' | Invoke-SqlAssessment
```
Sample result:
```PowerShell
PS:> Get-SqlInstance -ServerInstance localhost | Invoke-SqlAssessment
TargetPath: Server[@Name='LOCAL']
Sev. Message Check ID Origin
---- ------- -------- ------
Info Enable trace flag 834 to use large-page allocations to improve TF834 Microsoft Ruleset 0.1.202
analytical and data warehousing workloads.
Low Detected deprecated or discontinued feature uses: String literals DeprecatedFeatures Microsoft Ruleset 0.1.202
as column aliases, syscolumns, sysusers, SET FMTONLY ON, XP_API,
Table hint without WITH, More than two-part column name. We
recommend to replace them with features actual for SQL Server
version 14.0.1000.
Medi Amount of single use plans in cache is high (100%). Consider PlansUseRatio Microsoft Ruleset 0.1.202
enabling the Optimize for ad hoc workloads setting on heavy OLTP
ad-hoc workloads to conserve resources.
...
```
In the results, you will see that each rule has some properties (not the full list):
- Severity (info, low, medium, high)
- Message property explains the recommendation but if you need more info, there is a HelpLink property that points at documentation on the subject.
- Origin shows which ruleset and version the recommendation is coming from
See [ruleset.json](./ruleset.json) for a full list of rules and properties.
If you want to get recommendations for all databases on the local instance, run this command.
```PowerShell
Get-SqlDatabase -ServerInstance 'localhost' | Invoke-SqlAssessment
```
## Learn more about SQL Assessment API
To learn more about the SQL Assessment API such as customizing and extending rulesets, saving results to a table, etc., visit:
- Docs online page for SQL Assessment API PowerShell cmdlets: https://docs.microsoft.com/sql/sql-assessment-api/sql-assessment-api-overview
- [SQL Assessment User Guide](UserGuide/README.md)
- SQL Assessment API Tutorial notebook: [SQLAssessmentAPITutorialNotebook.ipynb](./notebooks/SQLAssessmentAPITutorialNotebook.ipynb)
- Azure Data Studio extension: https://techcommunity.microsoft.com/t5/sql-server/released-sql-server-assessment-extension-for-azure-data-studio/ba-p/1470603
samples/manage/sql-assessment-api/docs/How-To/README.md
+9
View File
@@ -0,0 +1,9 @@
# How-To
This section explains how to install and invoke assessment, use probes that are specific to VMs running in Azure environments, and how to enable probes that use non-SQL based queries to get data for assessment.
## In This Section
- [SQL Assessment API Quick Start Guide](QuickStart.md)
- [Assessment of SQL Server on Azure Virtual Machines](UsingAzureRules.md)
- [Retrieving Data from Operating System](UsingNonSQLProbes.md)
samples/manage/sql-assessment-api/docs/How-To/UsingAzureRules.md
+65
View File
@@ -0,0 +1,65 @@
# Assessment of SQL Server on Azure Virtual Machines
With SQL Assessment cmdlets, you can assess an instance of SQL Server on an Azure VM not only as on-premises SQL Server, but also with rules that are specific to Azure environments.
To use such rules, do the following:
1. Make sure that both the [Azure PowerShell module](https://aka.ms/AAbdhwk) and the [Az.ResourceGraph module](https://www.powershellgallery.com/packages/Az.ResourceGraph) are installed.
2. [Sign in with Azure PowerShell](https://aka.ms/AAbdogm) before invoking SQL Assessment against SQL Server on an Azure VM.
**NOTE:** It is possible to use Azure account connection persisted between PowerShell sessions, i.e. invoke **Connect-AzAccount** in one session and omit this command later. However, in such a scenario, SQL Assessment cmdlets need the **Az.ResourceGraph** module to be imported explicitly by running **Import-Module Az.ResourceGraph**.
## Performing Assessment
The following example shows how to invoke assessment for SQL Server on an Azure VM instance. Active Azure subscription connection enables rules that are specific to SQL Server on Azure VMs—**AzSqlVmSize** in this example:
1. Invoke the [Connect-AzAccount](https://docs.microsoft.com/powershell/module/az.accounts/connect-azaccount) cmdlet that establishes connection with the Azure account to get data from Azure Resource Graph.
```PowerShell
Connect-AzAccount
```
2. [Optional step] After invoking **Connect-AzAccount**, you can run the [Set-AzContext](https://docs.microsoft.com/powershell/module/az.accounts/set-azcontext) cmdlet.
```PowerShell
Set-AzContext My-Pay-As-You-Go
```
3. [Optional step] Invoke the [Get-Credential](https://docs.microsoft.com/powershell/module/microsoft.powershell.security/get-credential) cmdlet that creates a credential object for the specified user name and password.
```PowerShell
$cred = Get-Credential
```
4. Select SQL Server objects to assess. For example, the following command gets a SQL Server instance.
```PowerShell
$target = Get-SqlInstance -ServerInstance "Computer002\InstanceName" -Credential $cred
```
`-Credential` is an optional parameter and can be omitted.
5. Run the [Invoke-SqlAssessment](https://docs.microsoft.com/powershell/module/sqlserver/invoke-sqlassessment) cmdlet that builds a check list for each input object, runs through the list, and returns best practice recommendations.
```PowerShell
Invoke-SqlAssessment $target
```
As a result, you would get an output similar to the following one.
```
TargetPath : Server[@Name='ContosoAzureSQL']
Sev. Message Check ID Origin
---- ------- -------- ------
Medi Amount of single use plans in cache is high (100%). Consider PlansUseRatio Microsoft Ruleset 0.1.202
enabling the Optimize for ad hoc workloads setting on heavy OLTP
ad-hoc workloads to conserve resources
Low Use memory optimized virtual machine sizes for the best AzSqlVmSize Microsoft Ruleset 0.1.202
performance of SQL Server workloads
```
Here, **Server[@Name='ContosoAzureSQL']** shows the server name that hosts the assessed SQL Server instance, the **Sev.** column shows the severity level, which can be *Information*, *Medium*, *Low*, or *High*, in the **Message** column, the actual best practice recommendations are shown, the **Check ID** column shows the rule name, and the **Origin** column displays the ruleset name and version.
In this example, the **AzSqlVmSize** rule is applicable solely to the SQL Server deployed on an Azure VM; it checks whether the size of the VM is [memory-optimized](https://docs.microsoft.com/azure/virtual-machines/sizes-memory) or not.
samples/manage/sql-assessment-api/docs/How-To/UsingNonSQLProbes.md
+22
View File
@@ -0,0 +1,22 @@
# Retrieving Data from Operating System
In the SQL Assessment API, most of the probes use T-SQL to get data for assessment. However, there are probes that obtain data from the operating system not presented in SQL Server dynamic management views. In order for these probes to get data, the [xp_cmdshell](https://docs.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/xp-cmdshell-transact-sql) stored procedure and PowerShell access should be enabled on the target SQL Server. While these facilities are disabled, some checks may be ckipped.
Keep in mind that the [xp_cmdshell](https://docs.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/xp-cmdshell-transact-sql) stored procedure should be enabled temporarily as it is not recommended by the best practices; once you complete the assessment, make sure to disable it.
The following steps are required to enable [xp_cmdshell](https://docs.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/xp-cmdshell-transact-sql) and PowerShell:
1. Enable the **xp_cmdshell** stored procedure to work with T-SQL queries, as described in [xp_cmdshell configuration option](https://docs.microsoft.com/sql/database-engine/configure-windows/xp-cmdshell-server-configuration-option).
2. Enable SQL Server PowerShell on the target SQL server, as described in [SQL Server PowerShell](https://docs.microsoft.com/sql/powershell/sql-server-powershell).
3. Make sure that the SQL Server user has access to the **xp_cmdshell** stored procedure. For more information, see [xp_cmdshell (Transact-SQL)](https://docs.microsoft.com/sql/relational-databases/system-stored-procedures/xp-cmdshell-transact-sql).
4. [Perform assessment](https://docs.microsoft.com/sql/tools/sql-assessment-api/sql-assessment-api-overview?view=sql-server-ver15#get-started-using-sql-assessment-cmdlets).
5. Disable the **xp_cmdshell** stored procedure by executing the following T-SQL query on the target SQL Server.
``` sql
EXECUTE sp_configure 'xp_cmdshell', 0;
RECONFIGURE
```