azuredatastudio/extensions/azurehybridtoolkit/notebooks/hybridbook/content/Assessments/sql-server-assessment.ipynb

{
    "metadata": {
        "kernelspec": {
            "name": "powershell",
            "display_name": "PowerShell",
            "language": "powershell"
        },
        "language_info": {
            "name": "powershell",
            "codemirror_mode": "shell",
            "mimetype": "text/x-sh",
            "file_extension": ".ps1"
        }
    },
    "nbformat_minor": 2,
    "nbformat": 4,
    "cells": [
        {
            "cell_type": "markdown",
            "source": [
                "# SQL Server Assessment Tool\n",
                "\n",
                "Performs a best-practices assessment on a local SQL Server Instance. A single assessment may take some time, so fill out the variables and execute the cell that matches the desired environment to perform the assessment needed.\n",
                "\n",
                "## Notebook Variables\n",
                "\n",
                "| Line | Variable | Description | Example |\n",
                "| --- | --- | --- | --- |\n",
                "| 1 | ServerInstance | Name of the SQL Server instance | MSSQLSERVER |\n",
                "| 2 | OutputDb | New or existing database to place assessment results in | DB1 |\n",
                "| 3 | OutputTable | Target table to place assessment results (for a clean assessment, use a new table name) | AssessmentResults |"
            ],
            "metadata": {
                "azdata_cell_guid": "86ecfb01-8c38-4a99-92a8-687d8ec7f4b0"
            }
        },
        {
            "cell_type": "code",
            "source": [
                "$ServerInstance = \"\"\r\n",
                "$OutputDb       = \"\"\r\n",
                "$OutputTable    = \"\""
            ],
            "metadata": {
                "azdata_cell_guid": "db21129e-9bda-4db9-8d61-d2b264a3cad8",
                "tags": [
                    "parameters"
                ]
            },
            "outputs": [],
            "execution_count": null
        },
        {
            "cell_type": "markdown",
            "source": [
                "## Notebook Steps\n",
                "\n",
                "1. Ensure that the proper APIs and modules are installed per the <a href=\"..\\prereqs.ipynb\">prerequisites</a> notebook\n",
                "2. Define above variables corresponding to the SQL Server instance to be assessed\n",
                "3. Run the notebook to list the Assessment rules being considered, perform the assessment, and list the results\n",
                "4. Fix any warnings and rerun Assessment API until clear by reviewing the results table"
            ],
            "metadata": {
                "azdata_cell_guid": "541f6806-f8d2-4fc5-a8fb-6d42947d1a64"
            }
        },
        {
            "cell_type": "markdown",
            "source": [
                "### Retrieve Checks for SQL Instance\n",
                "\n",
                "Pipe the output of the Get-SqlInstance cmdlet to the _Get-SqlAssessmentItem_ cmdlet to get the list of checks and their status. These results ought to display a list of rules for a default assessment."
            ],
            "metadata": {
                "azdata_cell_guid": "c6f94c36-0566-4963-acb8-4a419758d26e"
            }
        },
        {
            "cell_type": "code",
            "source": [
                "Get-SqlInstance -ServerInstance $serverInstance | Get-SqlAssessmentItem"
            ],
            "metadata": {
                "azdata_cell_guid": "420e135e-0190-476b-812d-f716ec619ed3"
            },
            "outputs": [],
            "execution_count": null
        },
        {
            "cell_type": "markdown",
            "source": [
                "### Export Assessment to SQL Table\n",
                "\n",
                "Invoke assessment for the instance and save the results to a SQL table by piping the output of the _Get-SqlInstance_ cmdlet to the _Invoke-SqlAssessment_ cmdlet. The results are piped to the _Write-SqlTableData_ cmdlet. The _Invoke-Assessment_ cmdlet is run with the -**FlattenOutput** parameter in this example. This parameter makes the output suitable for the _Write-SqlTableData_ cmdlet. The latter raises an error if the parameter is omitted."
            ],
            "metadata": {
                "azdata_cell_guid": "aeaa588a-a3a2-4bc3-9b4b-794427b77649"
            }
        },
        {
            "cell_type": "code",
            "source": [
                "Get-SqlInstance -ServerInstance $serverInstance |\r\n",
                "Invoke-SqlAssessment -FlattenOutput |\r\n",
                "Write-SqlTableData -ServerInstance $serverInstance -DatabaseName $outputDb -SchemaName Assessment -TableName $OutputTable -Force"
            ],
            "metadata": {
                "azdata_cell_guid": "28ce8df2-1da8-4462-8e91-62646642d4b1"
            },
            "outputs": [],
            "execution_count": null
        },
        {
            "cell_type": "markdown",
            "source": [
                "### Display the Results\n",
                "\n",
                "Use _Invoke-SqlCmd_ cmdlet to execute a short query to display the assessment results in this notebook in a custom format."
            ],
            "metadata": {
                "azdata_cell_guid": "44bb8b3f-b456-43b4-ba2f-ae22c715a984"
            }
        },
        {
            "cell_type": "code",
            "source": [
                "$q = \"SELECT TOP (1000) * FROM [$outputDb].[Assessment].[$OutputTable]\"\r\n",
                "$results = Invoke-SqlCmd -Query $q -ServerInstance $ServerInstance\r\n",
                "foreach ($result in $results)\r\n",
                "{\r\n",
                "    Write-Output \"----------------------------------------------------------\"\r\n",
                "    Write-Output $result.CheckName\r\n",
                "    if ($result.Severity -ne \"Information\")\r\n",
                "    {\r\n",
                "        Write-Warning $result.Message\r\n",
                "    }\r\n",
                "    else \r\n",
                "    {\r\n",
                "        Write-Output $result.Message\r\n",
                "    }\r\n",
                "    Write-Output $result.HelpLink\r\n",
                "}"
            ],
            "metadata": {
                "azdata_cell_guid": "5bab466f-2ea0-4c3a-9ac1-923ac1548dd3"
            },
            "outputs": [],
            "execution_count": null
        },
        {
            "cell_type": "markdown",
            "source": [
                "## Next Steps\n",
                "\n",
                "### Install SQL Assessment ADS Extension\n",
                "\n",
                "Consider installing the **SQL Assessment** extension for Azure Data Studio from the extensions sidebar. Like this notebook, it uses the SQL Server Assessment API to provides a mechanism to evaluate the configuration of SQL Server for best practices. Simply search the Extensions Marketplace for \"sql assessment\" to list the extension package then click the green Install link to load it into ADS."
            ],
            "metadata": {
                "azdata_cell_guid": "b3bfb32f-9dcc-49ba-bf22-670116e4a72a"
            }
        }
    ]
}