Merge pull request #65 from cyberious/FM2110-readme

Jean B. · Jean B. · commit ffadfd2c1b7a · 2015-01-22T10:48:37.000-08:00
FM-2110 README Predocs for sqlserver_tsql provider
diff --git a/README.md b/README.md
@@ -15,19 +15,19 @@
 
 ##Overview
 
-The sqlserver module installs and manages Microsoft SQL Server 2012 and 2014 on Windows systems. 
+The sqlserver module installs and manages Microsoft SQL Server 2012 and 2014 on Windows systems.
 
 ##Module Description
- 
-The sqlserver module adds defined types to install and manage Microsoft SQL Server 2012 and 2014 on Windows Server 2012. The module can install SQL Server clients, multiple instances, and SQL features, as well as create and manage new databases and logins. 
+
+The sqlserver module adds defined types to install and manage Microsoft SQL Server 2012 and 2014 on Windows Server 2012. The module can install SQL Server clients, multiple instances, and SQL features, as well as create and manage new databases and logins.
 
 ##Setup
 
 ###What sqlserver affects
 
 This module requires .NET 3.5 and installs it if it's not already on your system. This might require an internet connection.
 
-###Setup Requirements 
+###Setup Requirements
 
 The sqlserver module requires the following:
 
@@ -36,10 +36,10 @@ The sqlserver module requires the following:
 * .NET 3.5
 * ISO, mounted or expanded either locally or on a network share
 * Windows Server 2012 or 2012R2
-	
+
 ###Beginning with sqlserver
 
-To get started with the sqlserver module, include these settings in your manifest: 
+To get started with the sqlserver module, include these settings in your manifest:
 
 ```
 sqlserver_instance{'MSSQLSERVER':
@@ -79,7 +79,7 @@ sqlserver::database{ 'minviable':
 }
 ```
 
-###To set up a new login: 
+###To set up a new login:
 
 ```
 SQL Login
@@ -88,13 +88,43 @@ sqlserver::login{'vagrant':
 	password => 'Pupp3t1@',
 }
 
-Windows Login 
+Windows Login
 sqlserver::login{'WIN-D95P1A3V103\localAccount':
 	instance 	=> 'MSSQLSERVER',
 	login_type 	=> 'WINDOWS_LOGIN',
 }
 ```
 
+###To run custom TSQL statements
+
+To use `sqlserver_tsql` as a trigger to other defined types in order to trigger other workflows
+```
+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['To Many Fatal Errors']
+}
+```
+
+It can also be used to help clean up regular logs with conditional checks
+```
+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",
+}
+```
+
+In the event you want something to always execute you can also leave the `onlyif` parameter out and have it execute every time
+```
+sqlserver_tsql{ 'Always running':
+    instance => 'MSSQLSERVER',
+    command  => 'EXEC notified_executor()',
+}
+```
+
 #### Windows SQL Server Terms
 
 Terminology differs somewhat between various database systems; please refer to this list of terms for clarification.
@@ -114,10 +144,10 @@ Terminology differs somewhat between various database systems; please refer to t
 * `ensure`: Ensures that the resource is present. Valid values are 'present', 'absent'.
 * `features`: Specifies features to install or uninstall. The list of top-level features include IS, MDS, and Tools. The Tools feature will install Management Tools, SQL Server Data Tools, and other shared components. Valid values are 'Tools', 'BC', 'Conn', 'SSMS', 'ADV_SSMS', 'SDK', 'IS', 'MDS'.
 * `is_svc_account`: Either domain user name or system account. Defaults to 'NT AUTHORITY\NETWORK SERVICE'.
-* `is_svc_password`: Password for domain user. 
+* `is_svc_password`: Password for domain user.
 * `pid`: Specify the SQL Server product key to configure which edition you would like to use. Can be left empty for evaluation versions.
 * `provider`: The specific backend to use for this `sqlserver_features` resource. You seldom need to specify this---Puppet will usually discover the appropriate provider for your platform. Available providers are: `mssql`, `source`.
-  
+
 #### sqlserver_instance
 
 * `agt_svc_account`: Either domain user name or system account.
@@ -139,22 +169,27 @@ Terminology differs somewhat between various database systems; please refer to t
 * `sql_svc_password`: The SQL Server service password; required only for a domain account.
 * `sql_sysadmin_accounts`: The Windows or SQL account(s) to provision as SQL Server system administrators.
 
+####sqlserver_tsql
+* `command`: TSQL to execute on a potentially conditional basis
+* `onlyif`: TSQL to execute as a check to see if we should proceed and run the command parameter, should encounter a throw or error to trigger
+* `instance`: SQL Server instance that we should execute against
+
 ### Defined Types
 
 #### `sqlserver::config`
 
-Stores the config file that allows Puppet to access and modify the instance. 
+Stores the config file that allows Puppet to access and modify the instance.
 
 * `instance_name`: The instance name you want to manage.  Defaults to the name of the define.
-* `admin_user`: The SQL login with sysadmin rights on the server, can only be login of SQL_Login type. 
+* `admin_user`: The SQL login with sysadmin rights on the server, can only be login of SQL_Login type.
 * `admin_pass`: The password to access the server to be managed.
 
   ```
   sqlserver::config{'MSSQLSERVER':
     admin_user => 'sa',
     admin_pass => 'PuppetP@ssword1',
     }
-  ```  
+  ```
 
 #### `sqlserver::database`
 
@@ -165,23 +200,23 @@ Creates, destroys, or updates databases, but does not move or modify files. Requ
 * `ensure`: Ensures that the resource is present. Valid values are 'present', 'absent'. Defaults to 'present'.
 * `compatibility`: Numeric representation of the SQL Server version with which the database should be compatible. For example, 100 = SQL Server 2008 through SQL Server 2012.  For a complete list of values, refer to [http://msdn.microsoft.com/en-us/library/bb510680.aspx](http://msdn.microsoft.com/en-us/library/bb510680.aspx).
 * `collation_name`: Modifies dictionary default sort rules for the datatbase. Defaults to 'Latin1_General'. To find out what other values your system supports, run the query `SELECT * FROM sys.fn_helpcollations() WHERE name LIKE 'SQL%'`.
-* `filestream_non_transacted_access`: Specifies the level of non-transactional FILESTREAM access to the database. This parameter is affected only at creation; updates will not change this setting. Valid values are 'OFF', 'READ_ONLY', 'FULL'. Requires defined type `sqlserver::sp_configure`. 
-* `filestream_directory_name`: Accepts a Windows-compatible directory name. This name should be unique among all the Database_Directory names in the SQL Server instance. Uniqueness comparison is case-insensitive, regardless of SQL Server collation settings. This option should be set before creating a FileTable in this database. This parameter is affected only at creation; updates will not change this setting. Requires defined type `sqlserver::sp_configure`. 
-* `filespec_name`: Specifies the logical name for the file. NAME is required when FILENAME is specified, except when specifying one of the FOR ATTACH clauses. A FILESTREAM filegroup cannot be named PRIMARY. This parameter is affected only at creation; updates will not change this setting. 
-* `filespec_filename`: Specifies the operating system (physical) file name. This parameter is affected only at creation; updates will not change this setting. 
-* `filespec_size`: Specifies the size of the file. The kilobyte (KB), megabyte (MB), gigabyte (GB), or terabyte (TB) suffixes can be used. The default is MB.  Values can not be greater than 2147483647. This parameter is affected only at creation; updates will not change this setting. 
-* `filespec maxsize`: Specifies the maximum size to which the file can grow. MAXSIZE cannot be specified when the os_file_name is specified as a UNC path. This parameter is affected only at creation; updates will not change this setting. 
-* `filespec_filegrowth`: Specifies the automatic growth increment of the file. The FILEGROWTH setting for a file cannot exceed the MAXSIZE setting. FILEGROWTH cannot be specified when the os_file_name is specified as a UNC path. FILEGROWTH does not apply to a FILESTREAM filegroup. This parameter is affected only at creation; updates will not change this setting. 
-* `log_name`: Specifies the logical name for the file. NAME is required when FILENAME is specified, except when specifying one of the FOR ATTACH clauses. A FILESTREAM filegroup cannot be named PRIMARY. This parameter is affected only at creation; updates will not change this setting. 
-* `log_filename`: Specifies the operating system (physical) file name. This parameter is affected only at creation; updates will not change this setting. 
-* `log_size`: Specifies the size of the file. The kilobyte (KB), megabyte (MB), gigabyte (GB), or terabyte (TB) suffixes can be used. The default is MB.  Values can not be greater than 2147483647. This parameter is affected only at creation; updates will not change this setting. 
-* `log_maxsize`: Specifies the maximum size to which the file can grow. MAXSIZE cannot be specified when the os_file_name is specified as a UNC path. This parameter is affected only at creation; updates will not change this setting. 
-* `log_filegrowth`: Specifies the automatic growth increment of the file. The FILEGROWTH setting for a file cannot exceed the MAXSIZE setting. FILEGROWTH cannot be specified when the os_file_name is specified as a UNC path. FILEGROWTH does not apply to a FILESTREAM filegroup. This parameter is affected only at creation; updates will not change this setting. 
+* `filestream_non_transacted_access`: Specifies the level of non-transactional FILESTREAM access to the database. This parameter is affected only at creation; updates will not change this setting. Valid values are 'OFF', 'READ_ONLY', 'FULL'. Requires defined type `sqlserver::sp_configure`.
+* `filestream_directory_name`: Accepts a Windows-compatible directory name. This name should be unique among all the Database_Directory names in the SQL Server instance. Uniqueness comparison is case-insensitive, regardless of SQL Server collation settings. This option should be set before creating a FileTable in this database. This parameter is affected only at creation; updates will not change this setting. Requires defined type `sqlserver::sp_configure`.
+* `filespec_name`: Specifies the logical name for the file. NAME is required when FILENAME is specified, except when specifying one of the FOR ATTACH clauses. A FILESTREAM filegroup cannot be named PRIMARY. This parameter is affected only at creation; updates will not change this setting.
+* `filespec_filename`: Specifies the operating system (physical) file name. This parameter is affected only at creation; updates will not change this setting.
+* `filespec_size`: Specifies the size of the file. The kilobyte (KB), megabyte (MB), gigabyte (GB), or terabyte (TB) suffixes can be used. The default is MB.  Values can not be greater than 2147483647. This parameter is affected only at creation; updates will not change this setting.
+* `filespec maxsize`: Specifies the maximum size to which the file can grow. MAXSIZE cannot be specified when the os_file_name is specified as a UNC path. This parameter is affected only at creation; updates will not change this setting.
+* `filespec_filegrowth`: Specifies the automatic growth increment of the file. The FILEGROWTH setting for a file cannot exceed the MAXSIZE setting. FILEGROWTH cannot be specified when the os_file_name is specified as a UNC path. FILEGROWTH does not apply to a FILESTREAM filegroup. This parameter is affected only at creation; updates will not change this setting.
+* `log_name`: Specifies the logical name for the file. NAME is required when FILENAME is specified, except when specifying one of the FOR ATTACH clauses. A FILESTREAM filegroup cannot be named PRIMARY. This parameter is affected only at creation; updates will not change this setting.
+* `log_filename`: Specifies the operating system (physical) file name. This parameter is affected only at creation; updates will not change this setting.
+* `log_size`: Specifies the size of the file. The kilobyte (KB), megabyte (MB), gigabyte (GB), or terabyte (TB) suffixes can be used. The default is MB.  Values can not be greater than 2147483647. This parameter is affected only at creation; updates will not change this setting.
+* `log_maxsize`: Specifies the maximum size to which the file can grow. MAXSIZE cannot be specified when the os_file_name is specified as a UNC path. This parameter is affected only at creation; updates will not change this setting.
+* `log_filegrowth`: Specifies the automatic growth increment of the file. The FILEGROWTH setting for a file cannot exceed the MAXSIZE setting. FILEGROWTH cannot be specified when the os_file_name is specified as a UNC path. FILEGROWTH does not apply to a FILESTREAM filegroup. This parameter is affected only at creation; updates will not change this setting.
 * `containment`: Defaults to 'NONE'.Other possible values are 'PARTIAL'. Setting `containment` =>'PARTIAL' requires defined type `sqlserver::sp_configure`. See [http://msdn.microsoft.com/en-us/library/ff929071.aspx](http://msdn.microsoft.com/en-us/library/ff929071.aspx) for complete documentation about containment.
 * `default_fulltext_language`: Sets default fulltext language. Only applicable if `containment` => ‘PARTIAL’. Valid values are documented at [http://msdn.microsoft.com/en-us/library/ms190303.aspx](http://msdn.microsoft.com/en-us/library/ms190303.aspx). Defaults to 'us_english'.
 * `default_language`: Sets default language. Only applicable if `containment` => ‘PARTIAL’. Valid values are documented at http://msdn.microsoft.com/en-us/library/ms190303.aspx. Defaults to 'us_english'.
 * `nested_triggers`: Enables cascading triggers. Only applicable if `containment` => ‘PARTIAL’. Valid values are 'ON', 'OFF'. See [http://msdn.microsoft.com/en-us/library/ms178101.aspx](http://msdn.microsoft.com/en-us/library/ms178101.aspx) for complete documentation.
-* `transform_noise_words`: Removes noise or stop words, such as “is”, “the”, “this”. Only applicable if `containment` => ‘PARTIAL’. Valid values are 'ON', 'OFF'. 
+* `transform_noise_words`: Removes noise or stop words, such as “is”, “the”, “this”. Only applicable if `containment` => ‘PARTIAL’. Valid values are 'ON', 'OFF'.
 * `two_digit_year_cutoff`: The year at which the system will treat the year as four digits instead of two. For example, if set to '1999', 1998 would be abbreviated to '98', while 2014 would be '2014'. Only applicable if `containment` => ‘PARTIAL’. Valid values are any year between 1753 and 9999. Defaults to 2049.
 * `db_chaining`: Whether the database can be the source or target of a cross-database ownership chain. Only applicable if `containment` => ‘PARTIAL’. Valid values are 'ON', 'OFF'. Defaults to 'OFF'.
 * `trustworthy`: Whether database modules (such as views, user-defined functions, or stored procedures) that use an impersonation context can access resources outside the database. Only applicable if `containment` => ‘PARTIAL’. Valid values are 'ON', 'OFF'. Defaults to 'OFF'.
@@ -208,13 +243,13 @@ Requires defined type `sqlserver::config`.
 * `default_database`: Sets the database the login should default to when connecting. Defaults to 'master'.
 * `default_language`: Sets default language. Valid values are documented at http://msdn.microsoft.com/en-us/library/ms190303.aspx. Defaults to 'us_english'.
 * `check_expiration`: For SQL logins, checks to see if password has expired and user should be forced to change the password. Only applicable when Login_Type = 'SQL_LOGIN'. Valid values are 'true', 'false'. Default value is 'false'.
-* `check_policy`: Checks the password policy. Only applicable when Login_Type = 'SQL_LOGIN'. Valid values are 'true', 'false'. Defaults to 'true'. 
-* `disabled`: Valid values are 'true', 'false'. Defaults to 'false'. 
+* `check_policy`: Checks the password policy. Only applicable when Login_Type = 'SQL_LOGIN'. Valid values are 'true', 'false'. Defaults to 'true'.
+* `disabled`: Valid values are 'true', 'false'. Defaults to 'false'.
 
 **For more information about these settings and configuration in Microsoft SQL Server, please see:**
 
 * [Server Role Members](http://msdn.microsoft.com/en-us/library/ms186320.aspx)
-* [Create Login](http://technet.microsoft.com/en-us/library/ms189751.aspx) 
+* [Create Login](http://technet.microsoft.com/en-us/library/ms189751.aspx)
 * [Alter Login](http://technet.microsoft.com/en-us/library/ms189828.aspx)
 
 #### sqlserver::sp_configure
@@ -230,13 +265,13 @@ This defined type configures the instance to allow usage of filestream parameter
 
 **For more information about these settings and configuration in Microsoft SQL Server, please see:**
 
-* [Reconfigure](http://msdn.microsoft.com/en-us/library/ms176069.aspx) 
+* [Reconfigure](http://msdn.microsoft.com/en-us/library/ms176069.aspx)
 * [Server Configuration Options](http://msdn.microsoft.com/en-us/library/ms189631.aspx)
 
 ##Limitations
 
-This module is available only for Puppet Enterprise 3.7 and later. 
+This module is available only for Puppet Enterprise 3.7 and later.
 
 ## Development
 
-This is a proprietary module only available to Puppet Enterprise users. As such, we have no formal way for users to contribute toward development. However, we know our users are a charming collection of brilliant people, so if you have a bug you've fixed or a contribution to this module, please generate a diff and throw it into a ticket to support---they'll ensure that we get it.
+This is a proprietary module only available to Puppet Enterprise users. As such, we have no formal way for users to contribute toward development. However, we know our users are a charming collection of brilliant people, so if you have a bug you've fixed or a contribution to this module, please generate a diff and throw it into a ticket to support---they'll ensure that we get it.
