From bce72857331ef59af6a269a314748cfb2a57d1fc Mon Sep 17 00:00:00 2001 From: Garrett Guillotte Date: Wed, 31 Aug 2016 10:19:36 -0700 Subject: [PATCH] (FM-5476) (docs) Edits for docs signoff. - Clarify changelog entries regarding bugs. - Consistently capitalize ".NET" in the changelog and readme. - Make Markdown line spacing in the changelog more consistent. - Add commas to an unclear list in the changelog. - Consistently use sentence case in readme headings. - Consistently add one space between heading text and markup. - Consistently use two-space indents in Puppet code blocks. - Consistently space names from brackets in Puppet code blocks. - Consistently align hash rockets in Puppet code blocks. - Fix an unclosed Markdown code backtick. - Update a couple link URLs to more specific destinations. - Fix spelling, grammar, and spacing errors. --- CHANGELOG.md | 74 ++++++++++++++++------------ README.md | 134 +++++++++++++++++++++++++-------------------------- 2 files changed, 109 insertions(+), 99 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fcdab1b3..4370c843 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,65 +1,75 @@ ## 2016-08-31 - Supported Release 1.1.4 + ### Summary -- Small release with several bug fixes and minor feature +- Small release with several bug fixes and a minor feature. #### Features -- Added `windows_feature_source` to `sqlserver_instance` and `sqlserver_features` resources. This specifies the location of the Windows Feature source files. This may be needed to install the .Net Framework. See https://support.microsoft.com/en-us/kb/2734782 for more information. ([MODULES-3202](https://tickets.puppet.com/browse/MODULES-3202)) + +- Add `windows_feature_source` parameter to the `sqlserver_instance` and `sqlserver_features` resources. This specifies the location of the Windows Feature source files, which might be needed to install the .NET Framework. See https://support.microsoft.com/en-us/kb/2734782 for more information ([MODULES-3202](https://tickets.puppet.com/browse/MODULES-3202)). #### Bug Fixes -- Fix adding multiple SYSADMIN role accounts on instance creation ([MODULES-3427](https://tickets.puppet.com/browse/MODULES-3427)) -- Fix creation and deletion of Windows base logins ([MODULES-3256](https://tickets.puppet.com/browse/MODULES-3256)) -- Fix deleting logins ([MODULES-2323](https://tickets.puppet.com/browse/MODULES-2323)) -- Fix deleting databases ([MODULES-2554](https://tickets.puppet.com/browse/MODULES-2554)) -- Refactor acceptance tests for `sqlserver::login` resource ([MODULES-3256](https://tickets.puppet.com/browse/MODULES-3256)) -- Fix modifying server roles for an existing login ([MODULES-3083](https://tickets.puppet.com/browse/MODULES-3083)) -- Fix modifying server roles for an existing Windows user login ([MODULES-3752](https://tickets.puppet.com/browse/MODULES-3752)) + +- Fix issues when adding multiple SYSADMIN role accounts on instance creation ([MODULES-3427](https://tickets.puppet.com/browse/MODULES-3427)). +- Fix issues when creating and deleting Windows base logins ([MODULES-3256](https://tickets.puppet.com/browse/MODULES-3256)). +- Fix errors when deleting MS SQL Server logins ([MODULES-2323](https://tickets.puppet.com/browse/MODULES-2323)) and databases ([MODULES-2554](https://tickets.puppet.com/browse/MODULES-2554)). +- Refactor acceptance tests for `sqlserver::login` resource ([MODULES-3256](https://tickets.puppet.com/browse/MODULES-3256)). +- Fix issues when modifying server roles for an existing login ([MODULES-3083](https://tickets.puppet.com/browse/MODULES-3083)). +- Fix issues when modifying an existing Windows user login ([MODULES-3752](https://tickets.puppet.com/browse/MODULES-3752)). ## 2016-07-12 - Supported Release 1.1.3 + ### Summary -- Small release with several bug fixes and minor features -- Updated the supported Puppet version ranges +- Small release with several bug fixes and minor features. +- Update the supported Puppet version ranges. #### Features -- Updated documentation with more advanced SQL example -- Add Windows Based Authentication for `sqlserver::config`. Modifies the `sqlserver::config` class with an additional property called `login_type` which can be either `SQL_LOGIN` or `WINDOWS_LOGIN`, with a default of `SQL_LOGIN` + +- Update documentation with a more advanced SQL example. +- Add Windows Based Authentication for `sqlserver::config`. Modifies the `sqlserver::config` class with an additional property called `login_type` which can be either `SQL_LOGIN` or `WINDOWS_LOGIN`, with a default of `SQL_LOGIN`. #### Bug Fixes -- Fix Role Name Collisions. This fix introduces the database name into the title created for the `sqlserver_tsql` statements so that it is unique -- Minor refactoring of code which is not used or make code path more obvious -- Fix TSQL error propagation. Introduce a minor refactor so that the `returns` property captures errors properly from TSQL executions -- Emit debug output on failed `onlyif` TSQL. Previously, there was no way of getting the log output from SQL Server when executing TSQL during an `onlyif` + +- Fix Role Name Collisions. This fix introduces the database name into the title created for the `sqlserver_tsql` statements so that it is unique. +- Minor refactoring of code which is not used or makes code path more obvious. +- Fix TSQL error propagation. Introduce a minor refactor so that the `returns` property captures errors properly from TSQL executions. +- Emit debug output on failed `onlyif` TSQL. Previously, there was no way of getting the log output from SQL Server when executing TSQL during an `onlyif`. ## 2016-04-11 - Supported Release 1.1.2 -### Summary -Small release to support Puppet version ranges. +### Summary +Small release to update supported Puppet version ranges. ## 2015-12-08 - Supported Release 1.1.1 + ### Summary -Small release for support of newer PE versions. +Small release to support newer PE versions. ## 2015-09-08 - Supported Release 1.1.0 + ### Summary -User, Roles and Login as well as they permissions associated with each are now available. +User, Roles, and Login, as well as the permissions associated with each, are now available. #### Features -- `sqlserver_instance` and `sqlserver_features` have new parameter `install_switches` which takes a hash of install switches and writes them to a temp configuration file for the the install process -- Add define for permissions for Users, Roles and Logins -- `sqlserver::config` no longer writes a file to the sytem -- New `sqlserver_tsql` provider available to execute custom scripts -- Remove dependency on 'sqlcmd.exe' -- Performance discovery improvements -- Remove dependency for ACL modules + +- `sqlserver_instance` and `sqlserver_features` have new parameter `install_switches`, which takes a hash of install switches and writes them to a temporary configuration file for the install process. +- Add define for permissions for Users, Roles, and Logins. +- `sqlserver::config` no longer writes a file to the sytem. +- New `sqlserver_tsql` provider available to execute custom scripts. +- Remove dependency on 'sqlcmd.exe'. +- Performance discovery improvements. +- Remove dependency for ACL modules. #### Bug Fixes -- Munge values for instance names to always be uppercase when comparing -- Change the way we look up logins to use sys.server_principals instead of function that might not report correctly -- Fix issue with collation_name and databases where the variable was not named properly causing it to never be set + +- Munge values for instance names to always be uppercase when comparing. +- Change the way we look up logins to use sys.server_principals instead of a function that might not report correctly. +- Fix issue with `collation_name` and databases where the variable was not named properly, causing it to never be set. ## 2014-12-08 - 1.0.0 -Initial release + +Initial release. diff --git a/README.md b/README.md index c4fdd429..9cd2451c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # sqlserver -####Table of Contents +#### Table of contents 1. [Overview](#overview) 2. [Module Description - What the module does and why it is useful](#module-description) @@ -18,34 +18,34 @@ 6. [Limitations - OS compatibility, etc.](#limitations) 7. [Development - Guide for contributing to the module](#development) -##Overview +## Overview The sqlserver module installs and manages Microsoft SQL Server 2012 and 2014 on Windows systems. -##Module Description +## Module description Microsoft SQL Server is a database platform for Windows. The sqlserver module lets you use Puppet to install multiple instances of SQL Server, add SQL features and client tools, execute TSQL statements, and manage databases, users, roles, and server configuration options. -##Setup +## Setup -###Setup Requirements +### Setup requirements The sqlserver module requires the following: * Puppet Enterprise 3.7 or later. -* .NET 3.5 (installed automatically if not present. This might require an internet connection). +* .NET 3.5. (Installed automatically if not present. This might require an internet connection.) * The contents of the SQL Server ISO file, mounted or extracted either locally or on a network share. -* Windows Server 2012 or 2012R2. +* Windows Server 2012 or 2012 R2. -###Beginning with sqlserver +### Beginning with sqlserver To get started with the sqlserver module, include these settings in your manifest: ~~~puppet -sqlserver_instance{'MSSQLSERVER': - features => ['SQL'], - source => 'E:/', - sql_sysadmin_accounts => ['myuser'], +sqlserver_instance{ 'MSSQLSERVER': + features => ['SQL'], + source => 'E:/', + sql_sysadmin_accounts => ['myuser'], } ~~~ @@ -54,7 +54,7 @@ This example installs MS SQL and creates an MS SQL instance named MSSQLSERVER. I A more advanced configuration, including installer switches: ~~~puppet -sqlserver_instance{'MSSQLSERVER': +sqlserver_instance{ 'MSSQLSERVER': source => 'E:/', features => ['SQL'], security_mode => 'SQL', @@ -74,11 +74,11 @@ sqlserver_instance{'MSSQLSERVER': This example creates the same MS SQL instance as shown above with additional options: security mode (requiring password to be set) and other optional install switches. This is specified using a hash syntax. -##Usage +## Usage Note: For clarification on Microsoft SQL Server terminology, please see [Microsoft SQL Server Terms](#microsoft-sql-server-terms) below. -###Install SQL Server tools and features not specific to a SQL Server instance +### Install SQL Server tools and features not specific to a SQL Server instance ~~~puppet sqlserver_features { 'Generic Features': @@ -89,98 +89,98 @@ sqlserver_features { 'Generic Features': ~~~puppet sqlserver_features { 'Generic Features': - source => 'E:/', - features => ['ADV_SSMS', 'BC', 'Conn', 'SDK', 'SSMS'], + source => 'E:/', + features => ['ADV_SSMS', 'BC', 'Conn', 'SDK', 'SSMS'], } ~~~ -###Create a new database on an instance of SQL Server +### Create a new database on an instance of SQL Server ~~~puppet sqlserver::database{ 'minviable': - instance => 'MSSQLSERVER', + instance => 'MSSQLSERVER', } ~~~ -###Set up a new login +### Set up a new login ~~~puppet -SQL Login -sqlserver::login{'vagrant': +# SQL Login +sqlserver::login{ 'vagrant': instance => 'MSSQLSERVER', password => 'Pupp3t1@', } -Windows Login -sqlserver::login{'WIN-D95P1A3V103\localAccount': +# Windows Login +sqlserver::login{ 'WIN-D95P1A3V103\localAccount': instance => 'MSSQLSERVER', login_type => 'WINDOWS_LOGIN', } ~~~ -###Create a new login and a user for a given database +### Create a new login and a user for a given database ~~~puppet -sqlserver::login{'loggingUser': - password => 'Pupp3t1@', +sqlserver::login{ 'loggingUser': + password => 'Pupp3t1@', } -sqlserver::user{'rp_logging-loggingUser': - user => 'loggingUser', - database => 'rp_logging', - require => Sqlserver::Login['loggingUser'], +sqlserver::user{ 'rp_logging-loggingUser': + user => 'loggingUser', + database => 'rp_logging', + require => Sqlserver::Login['loggingUser'], } ~~~ -###Manage the above user's permissions +### Manage the above user's permissions ~~~puppet -sqlserver::user::permissions{'INSERT-loggingUser-On-rp_logging': - user => 'loggingUser', - database => 'rp_logging', - permissions => 'INSERT', - require => Sqlserver::User['rp_logging-loggingUser'], +sqlserver::user::permissions{ 'INSERT-loggingUser-On-rp_logging': + user => 'loggingUser', + database => 'rp_logging', + permissions => 'INSERT', + require => Sqlserver::User['rp_logging-loggingUser'], } -sqlserver::user::permissions{'Deny the Update as we should only insert': - user => 'loggingUser', - database => 'rp_logging', - permissions => 'UPDATE', - state => 'DENY', - require => Sqlserver::User['rp_logging-loggingUser'], +sqlserver::user::permissions{ 'Deny the Update as we should only insert': + user => 'loggingUser', + database => 'rp_logging', + permissions => 'UPDATE', + state => 'DENY', + require => Sqlserver::User['rp_logging-loggingUser'], } ~~~ -###Run custom TSQL statements +### Run custom TSQL statements -####Use `sqlserver_tsql` to trigger other classes or defines +#### Use `sqlserver_tsql` to trigger other classes or defines ~~~puppet sqlserver_tsql{ 'Query Logging DB Status': - instance => 'MSSQLSERVER', - onlyif => "IF (SELECT count(*) FROM myDb.dbo.logging_table WHERE - message like 'FATAL%') > 1000 THROW 50000, 'Fatal Exceptions in Logging', 10", - notify => Exec['Too Many Fatal Errors'] + instance => 'MSSQLSERVER', + onlyif => "IF (SELECT count(*) FROM myDb.dbo.logging_table WHERE + message like 'FATAL%') > 1000 THROW 50000, 'Fatal Exceptions in Logging', 10", + notify => Exec['Too Many Fatal Errors'] } ~~~ -####Clean up regular logs with conditional checks +#### Clean up regular logs with conditional checks ~~~puppet sqlserver_tsql{ 'Cleanup Old Logs': - instance => 'MSSQLSERVER', - command => "DELETE FROM myDb.dbo.logging_table WHERE log_date < '${log_max_date}'", - onlyif => "IF exists(SELECT * FROM myDb.dbo.logging_table WHERE log_date < '${log_max_date}') - THROW 50000, 'need log cleanup', 10", + instance => 'MSSQLSERVER', + command => "DELETE FROM myDb.dbo.logging_table WHERE log_date < '${log_max_date}'", + onlyif => "IF exists(SELECT * FROM myDb.dbo.logging_table WHERE log_date < '${log_max_date}') + THROW 50000, 'need log cleanup', 10", } ~~~ -####If you want your statement to always execute, leave out the `onlyif` parameter +#### Always execute a statement by omitting the `onlyif` parameter ~~~puppet sqlserver_tsql{ 'Always running': - instance => 'MSSQLSERVER', - command => 'EXEC notified_executor()', + instance => 'MSSQLSERVER', + command => 'EXEC notified_executor()', } ~~~ @@ -206,7 +206,7 @@ Installs and configures features such as SSMS and Master Data Service. * `source`: *Required.* Locates the SQL Server installer. Valid options: a string containing the path to an executable. Puppet must have permission to execute the installer. -* `windows_feature_source`: *Optional.* Specifies the location of the Windows Feature source files. This may be needed to install the .Net Framework. See https://support.microsoft.com/en-us/kb/2734782 for more information. +* `windows_feature_source`: *Optional.* Specifies the location of the Windows Feature source files, which might be needed to install the .NET Framework. See https://support.microsoft.com/en-us/kb/2734782 for more information. Please note that if an option is set in both its own specific parameter and `install_switches`, the specifically named parameter takes precedence. For example, if you set the product key in both `pid` and in `install_switches`, SQL Server honors the `pid` parameter. @@ -263,7 +263,7 @@ Installs and configures a SQL Server instance. * `sql_sysadmin_accounts`: *Required.* Specifies one or more SQL or system accounts to receive sysadmin status. Valid options: an array containing one or more valid usernames. -* `windows_feature_source`: *Optional.* Specifies the location of the Windows Feature source files. This may be needed to install the .Net Framework. See https://support.microsoft.com/en-us/kb/2734782 for more information. +* `windows_feature_source`: *Optional.* Specifies the location of the Windows Feature source files, which might be needed to install the .NET Framework. See https://support.microsoft.com/en-us/kb/2734782 for more information. Please note that if an option is set in both its own specific parameter and `install_switches`, the specifically named parameter takes precedence. For example, if you set the product key in both `pid` and in `install_switches`, SQL Server honors the `pid` parameter. @@ -272,7 +272,7 @@ For more information about installer switches and configuring SQL Server, see th * [Installer Switches](https://msdn.microsoft.com/en-us/library/ms144259.aspx) * [Configuration File](https://msdn.microsoft.com/en-us/library/dd239405.aspx) -####`sqlserver_tsql` +#### `sqlserver_tsql` Executes a TSQL query against a SQL Server instance. @@ -292,7 +292,7 @@ Requires the `sqlserver::config` define for access to the parent instance. Stores credentials for Puppet to use when managing a given SQL Server instance. -* `admin_login_type`: *Optional.* Specifies the type of login used to manage to SQL Server instace. The login type affects the `admin_user` and admin_pass` parameters which are described below. Valid options: 'SQL_LOGIN' and 'WINDOWS_LOGIN'. Default: 'SQL_LOGIN'. +* `admin_login_type`: *Optional.* Specifies the type of login used to manage to SQL Server instance. The login type affects the `admin_user` and `admin_pass` parameters which are described below. Valid options: 'SQL_LOGIN' and 'WINDOWS_LOGIN'. Default: 'SQL_LOGIN'. - When using SQL Server based authentication - `SQL_LOGIN` @@ -302,9 +302,9 @@ Stores credentials for Puppet to use when managing a given SQL Server instance. - When using Windows based authentication - `WINDOWS_LOGIN` - * `admin_pass`: *Optional.* Valid options: undefined or an empty string `''` + * `admin_pass`: *Optional.* Valid options: undefined or an empty string (`''`). - * `admin_user`: *Optional.* Valid options: undefined or an empty string `''` + * `admin_user`: *Optional.* Valid options: undefined or an empty string (`''`). * `instance_name`: *Optional.* Specifies a SQL Server instance to manage. Valid options: a string containing the name of an existing instance. Default: the title of your declared resource. @@ -549,14 +549,14 @@ Terminology differs somewhat between various database systems; please refer to t * **Role:** a database-level or server-level permissions group. * **User:** a database-level account, typically mapped to a login. -##Limitations +## Limitations -This module is available only for Windows Server 2012 or 2012R2, and works with Puppet Enterprise 3.7 and later. +This module is available only for Windows Server 2012 or 2012 R2, and works with Puppet Enterprise 3.7 and later. ## Development -This module was built by Puppet Inc specifically for use with Puppet Enterprise (PE). +This module was built by Puppet Inc. specifically for use with Puppet Enterprise (PE). If you run into an issue with this module, or if you would like to request a feature, please [file a ticket](https://tickets.puppet.com/browse/MODULES/). -If you are having problems getting this module up and running, please [contact Support](http://puppet.com/services/customer-support). +If you have problems getting this module up and running, please [contact Support](https://puppet.com/support-services/customer-support).