Feature: get/add/remove roles

.github/workflows/ansible-test-windows.yml

@@ -47,7 +47,7 @@ jobs:
       fail-fast: false
       matrix:
         os:
-          - windows-2019
+          - windows-2022
         ansible:
           - stable-2.11
           - stable-2.12

changelogs/fragments/add_roles_module.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - New module to add/remove database role members.
+  - New module to get role member information.

plugins/modules/role_member.ps1

@@ -0,0 +1,119 @@
+#!powershell
+# -*- coding: utf-8 -*-
+
+# (c) 2022, John McCall (@lowlydba)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+#AnsibleRequires -CSharpUtil Ansible.Basic
+#AnsibleRequires -PowerShell ansible_collections.lowlydba.sqlserver.plugins.module_utils._SqlServerUtils
+#Requires -Modules @{ ModuleName="dbatools"; ModuleVersion="1.1.112" }
+
+$ErrorActionPreference = "Stop"
+
+$spec = @{
+    supports_check_mode = $true
+    options = @{
+        database = @{type = 'str'; required = $true }
+        username = @{type = 'str'; required = $true }
+        roles = @{type = 'list'; elements = 'str'; required = $false }
+        state = @{type = 'str'; required = $false; default = 'present'; choices = @('present', 'absent') }
+    }
+}
+
+$module = [Ansible.Basic.AnsibleModule]::Create($args, $spec, @(Get-LowlyDbaSqlServerAuthSpec))
+$sqlInstance, $sqlCredential = Get-SqlCredential -Module $module
+$username = $module.Params.username
+$database = $module.Params.database
+$roles = $module.Params.roles
+$state = $module.Params.state
+$checkMode = $module.CheckMode
+
+$module.Result.changed = $false
+
+$getRoleSplat = @{
+    SqlInstance = $sqlInstance
+    SqlCredential = $sqlCredential
+    Database = $database
+    EnableException = $true
+}
+$module.Result.roles = $roles
+$existingRoleObjects = Get-DbaDbRoleMember @getRoleSplat | Where-Object { $_.UserName -eq $username }
+$existingRoles = @()
+# build an array of roles for the selected user
+foreach ($roleObject in $existingRoleObjects) {
+    $existingRoles += $roleObject.role
+}
+# Always return a list of existing roles if any exist
+if ($null -ne $existingRoleObjects) {
+    $module.Result.existingRoles = $existingRoles
+}
+else {
+    $module.Result.noRoles = "'$username' doesn't have any existing roles assigned on '$database'"
+}
+
+if ($state -eq "absent") {
+    # loop through all roles to remove and see if any are assigned to the user
+    $removeRoles = @()
+    foreach ($roleObject in $existingRoleObjects) {
+        if ($roles.Contains($roleObject.role)) {
+            $removeRoles += $roleObject.role
+        }
+    }
+
+    $module.Result.removeRoles = $removeRoles
+    if ($removeRoles) {
+        try {
+            $removeRolesSplat = @{
+                SqlInstance = $sqlInstance
+                SqlCredential = $sqlCredential
+                User = $username
+                Database = $database
+                Role = $removeRoles
+                EnableException = $true
+                WhatIf = $checkMode
+                Confirm = $false
+                Verbose = $true
+            }
+            $output = Remove-DbaDbRoleMember @removeRolesSplat
+            $module.Result.changed = $true
+        }
+        catch {
+            $module.FailJson("Removing role failed: $($_.Exception.Message)", $_)
+        }
+    }
+}
+elseif ($state -eq "present") {
+    # compare the list of roles to add vs the existing roles for the user and get the difference
+    $addRoles = $roles | Where-Object { $existingRoles -NotContains $_ }
+    $module.Result.addRoles = $addRoles
+    if ($null -ne $addRoles) {
+        try {
+            $addRolesSplat = @{
+                SqlInstance = $sqlInstance
+                SqlCredential = $sqlCredential
+                User = $username
+                Database = $database
+                Role = $addRoles
+                EnableException = $true
+                WhatIf = $checkMode
+                Confirm = $false
+                Verbose = $true
+            }
+            $output = Add-DbaDbRoleMember @addRolesSplat
+            $module.Result.changed = $true
+        }
+        catch {
+            $module.FailJson("Adding role failed: $($_.Exception.Message)", $_)
+        }
+    }
+}
+try {
+    if ($null -ne $output) {
+        $resultData = ConvertTo-SerializableObject -InputObject $output
+        $module.Result.data = $resultData
+    }
+    $module.ExitJson()
+}
+catch {
+    $module.FailJson("Failure: $($_.Exception.Message)", $_)
+}

plugins/modules/role_member.py

@@ -0,0 +1,73 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2022, John McCall (@lowlydba)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+DOCUMENTATION = r'''
+---
+module: role_member
+short_description: Add or remove one or more roles for a given user in a specific database.
+description:
+  - Add or remove one or more roles for a given user in a specific database.
+version_added: 1.4.0
+options:
+  username:
+    description:
+      - Name of the user
+    type: str
+    required: true
+  database:
+    description:
+      - Database for the user
+    type: str
+    required: true
+  roles:
+    description:
+      - Specifies a comma separated list of one or more roles to add or remove
+    type: list
+    elements: str
+    required: false
+
+author:
+  - "Joe Krilov (@joey40)"
+  - "John McCall (@lowlydba)"
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
+extends_documentation_fragment:
+  - lowlydba.sqlserver.sql_credentials
+  - lowlydba.sqlserver.attributes.check_mode
+  - lowlydba.sqlserver.attributes.platform_all
+  - lowlydba.sqlserver.state
+'''
+
+EXAMPLES = r'''
+- name: Add a single role for a user
+  lowlydba.sqlserver.role_member:
+    sql_instance: sql-01.myco.io
+    username: TheIntern
+    database: InternProject1
+    role: db_datareader
+
+- name: Add multiple roles for a user
+  lowlydba.sqlserver.role_member:
+    sql_instance: sql-01.myco.io
+    username: TheIntern
+    database: InternProject1
+    role: db_datareader, db_datawriter
+
+- name: Remove roles for a user
+  lowlydba.sqlserver.role_member:
+    sql_instance: sql-01.myco.io
+    username: TheIntern
+    database: InternProject1
+    role: db_datareader, db_datawriter
+    state: absent
+'''
+
+RETURN = r'''
+data:
+  description: Output from the C(Add-DbaDbRoleMember), C(Get-DbaDbRoleMember), or C(Remove-DbaDbRoleMember) function.
+  returned: success, but not in check_mode.
+  type: dict
+'''

plugins/modules/role_member_info.ps1

@@ -0,0 +1,59 @@
+#!powershell
+# -*- coding: utf-8 -*-
+
+# (c) 2022, John McCall (@lowlydba)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+#AnsibleRequires -CSharpUtil Ansible.Basic
+#AnsibleRequires -PowerShell ansible_collections.lowlydba.sqlserver.plugins.module_utils._SqlServerUtils
+#Requires -Modules @{ ModuleName="dbatools"; ModuleVersion="1.1.112" }
+
+$ErrorActionPreference = "Stop"
+
+$spec = @{
+    supports_check_mode = $true
+    options = @{
+        database = @{type = 'str'; required = $false }
+        username = @{type = 'str'; required = $false }
+        roles = @{type = 'list'; elements = 'str'; required = $false }
+    }
+}
+
+$module = [Ansible.Basic.AnsibleModule]::Create($args, $spec, @(Get-LowlyDbaSqlServerAuthSpec))
+$sqlInstance, $sqlCredential = Get-SqlCredential -Module $module
+$username = $module.Params.username
+$database = $module.Params.database
+$roles = $module.Params.roles
+
+$module.Result.changed = $false
+
+try {
+    $getRoleSplat = @{
+        SqlInstance = $sqlInstance
+        SqlCredential = $sqlCredential
+        EnableException = $true
+    }
+    if ($null -ne $roles) {
+        $getRoleSplat.Add("Role", $roles)
+    }
+    if ($null -ne $database) {
+        $getRoleSplat.Add("Database", $database)
+    }
+    if ($null -ne $username) {
+        $output = Get-DbaDbRoleMember @getRoleSplat | Where-Object { $_.UserName -eq $username }
+    }
+    else {
+        $output = Get-DbaDbRoleMember @getRoleSplat
+    }
+
+    if ($null -ne $output) {
+        $resultData = ConvertTo-SerializableObject -InputObject $output
+        $module.Result.data = $resultData
+    }
+
+    $module.ExitJson()
+
+}
+catch {
+    $module.FailJson("Failure: $($_.Exception.Message)", $_)
+}

plugins/modules/role_member_info.py

@@ -0,0 +1,62 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2022, John McCall (@lowlydba)
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+DOCUMENTATION = r'''
+---
+module: role_member_info
+short_description: Returns basic information about a role or roles
+description:
+  - Returns basic information about a role or roles.
+version_added: 1.4.0
+options:
+  username:
+    description:
+      - Name of the user
+    type: str
+    required: false
+  database:
+    description:
+      - Database for the user
+    type: str
+    required: false
+  roles:
+    description:
+      - Specifies a comma separated list of one or more roles
+    type: list
+    elements: str
+    required: false
+author:
+  - "Joe Krilov (@joey40)"
+  - "John McCall (@lowlydba)"
+requirements:
+  - L(dbatools,https://www.powershellgallery.com/packages/dbatools/) PowerShell module
+extends_documentation_fragment:
+  - lowlydba.sqlserver.sql_credentials
+  - lowlydba.sqlserver.attributes.check_mode_read_only
+  - lowlydba.sqlserver.attributes.platform_all
+'''
+
+EXAMPLES = r'''
+- name: Return member of the db_datareader and db_datawriter role on the 'InternProject1' DB
+  lowlydba.sqlserver.role_member_info:
+    sql_instance: sql-01.myco.io
+    database: InternProject1
+    role: db_datareader, db_datawriter
+
+
+- name: Return all roles for user 'TheIntern' on the 'InternProject1' DB
+  lowlydba.sqlserver.role_member_info:
+    sql_instance: sql-01.myco.io
+    username: TheIntern
+    database: InternProject1
+'''
+
+RETURN = r'''
+data:
+  description: Output from the C(Get-DbaDbRoleMember) function.
+  returned: always
+  type: dict
+'''

tests/integration/targets/role_member/aliases

@@ -0,0 +1,2 @@
+context/target
+setup/once/setup_sqlserver

tests/integration/targets/role_member/meta/main.yml

@@ -0,0 +1,3 @@
+---
+dependencies:
+  - setup_sqlserver_test_plugins