chore: release 3.1.0

CHANGELOG.rst

@@ -4,6 +4,22 @@ lowlydba.sqlserver Release Notes
 
 .. contents:: Topics
 
+v3.1.0
+======
+
+Minor Changes
+-------------
+
+- Add a Pester unit test suite under ``tests/unit/plugins/module_utils/`` covering the ``module_utils`` helpers (``Get-LowlyDbaSqlServerAuthSpec``, ``Get-SqlCredential``, ``ConvertTo-SerializableObject``), and wire it into CI as a standalone job since ``ansible-test units`` only supports Python (https://github.com/lowlydba/lowlydba.sqlserver/issues/382).
+- Add check-mode assertions for the ``backup`` and ``restore`` integration test targets, add idempotency assertions for the ``availability_group`` and ``ag_replica`` targets, and exercise a non-default ``deployment_method`` in the ``install_script`` targets (https://github.com/lowlydba/lowlydba.sqlserver/issues/381).
+- Standardize module documentation examples and correct invalid parameters, missing required options, and incorrect module references (https://github.com/lowlydba/lowlydba.sqlserver/pull/399).
+
+Bugfixes
+--------
+
+- availability_group - Fix ``changed`` being incorrectly reported as ``true`` on an unchanged AG. ``Get-DbaAvailabilityGroup``'s SMO object never populates ``FailureConditionLevel``/``HealthCheckTimeout`` (they read back as unset defaults), and ``sys.availability_groups`` is a cache of the WSFC cluster resource's copy, so it's empty for AGs with ``cluster_type`` set to ``None``. Since neither source can be trusted, both properties are now excluded from the idempotency diff; they're still applied via ``Set-DbaAvailabilityGroup`` whenever another property change triggers an update (https://github.com/lowlydba/lowlydba.sqlserver/issues/381).
+- backup, restore - Fix ``changed`` being reported as ``false`` in ``check_mode``, since ``Backup-DbaDatabase``/``Restore-DbaDatabase`` return no output under ``-WhatIf`` (https://github.com/lowlydba/lowlydba.sqlserver/issues/381).
+
 v3.0.0
 ======
 

changelogs/changelog.yaml

@@ -738,3 +738,33 @@ releases:
     - ci-integration-timeouts.yml
     - release-summary.yml
     release_date: '2026-09-04'
+  3.1.0:
+    changes:
+      bugfixes:
+      - availability_group - Fix ``changed`` being incorrectly reported as ``true``
+        on an unchanged AG. ``Get-DbaAvailabilityGroup``'s SMO object never populates
+        ``FailureConditionLevel``/``HealthCheckTimeout`` (they read back as unset
+        defaults), and ``sys.availability_groups`` is a cache of the WSFC cluster
+        resource's copy, so it's empty for AGs with ``cluster_type`` set to ``None``.
+        Since neither source can be trusted, both properties are now excluded from
+        the idempotency diff; they're still applied via ``Set-DbaAvailabilityGroup``
+        whenever another property change triggers an update (https://github.com/lowlydba/lowlydba.sqlserver/issues/381).
+      - backup, restore - Fix ``changed`` being reported as ``false`` in ``check_mode``,
+        since ``Backup-DbaDatabase``/``Restore-DbaDatabase`` return no output under
+        ``-WhatIf`` (https://github.com/lowlydba/lowlydba.sqlserver/issues/381).
+      minor_changes:
+      - Add a Pester unit test suite under ``tests/unit/plugins/module_utils/`` covering
+        the ``module_utils`` helpers (``Get-LowlyDbaSqlServerAuthSpec``, ``Get-SqlCredential``,
+        ``ConvertTo-SerializableObject``), and wire it into CI as a standalone job
+        since ``ansible-test units`` only supports Python (https://github.com/lowlydba/lowlydba.sqlserver/issues/382).
+      - Add check-mode assertions for the ``backup`` and ``restore`` integration test
+        targets, add idempotency assertions for the ``availability_group`` and ``ag_replica``
+        targets, and exercise a non-default ``deployment_method`` in the ``install_script``
+        targets (https://github.com/lowlydba/lowlydba.sqlserver/issues/381).
+      - Standardize module documentation examples and correct invalid parameters,
+        missing required options, and incorrect module references (https://github.com/lowlydba/lowlydba.sqlserver/pull/399).
+    fragments:
+    - 381-integration-test-gaps.yml
+    - 382-pester-unit-tests.yml
+    - 399-documentation-examples.yml
+    release_date: '2026-09-08'

galaxy.yml

@@ -2,7 +2,7 @@
 
 namespace: lowlydba
 name: sqlserver
-version: 3.0.0
+version: 3.1.0
 readme: README.md
 authors:
   - John McCall (github.com/lowlydba)

plugins/modules/ag_listener.py

@@ -72,21 +72,20 @@
 '''
 
 EXAMPLES = r'''
-- name: Create Availability Group
+- name: Create an availability group
   lowlydba.sqlserver.availability_group:
-    sql_instance: sql-01.myco.io
-    ag_name: AG_MyDatabase
+    sql_instance: sql01.example.com
+    ag_name: AG_App
 
-- name: Create AG Listener
+- name: Create an availability group listener
   lowlydba.sqlserver.ag_listener:
-    sql_instance_primary: sql-01.myco.io
-    ag_name: AG_MyDatabase
-    listener_name: aglMyDatabase
+    sql_instance: sql01.example.com
+    ag_name: AG_App
+    listener_name: AG-App
     ip_address:
       - 10.0.20.20
-      - 10.1.77.77
     subnet_ip:
-      - 255.255.252.0
+      - 10.0.20.0
     subnet_mask:
       - 255.255.255.0
 '''

plugins/modules/ag_replica.py

@@ -122,16 +122,16 @@
 '''
 
 EXAMPLES = r'''
-- name: Create Availability Group
+- name: Create an availability group
   lowlydba.sqlserver.availability_group:
-    sql_instance: sql-01.myco.io
-    ag_name: AG_MyDatabase
+    sql_instance: sql01.example.com
+    ag_name: AG_App
 
-- name: Add a DR replica
+- name: Add a disaster recovery replica
   lowlydba.sqlserver.ag_replica:
-    ag_name: 'AG_MyDatabase'
-    sql_instance: sql-01.myco.io
-    sql_instance_replica: sql-02.myco.io
+    ag_name: AG_App
+    sql_instance: sql01.example.com
+    sql_instance_replica: sql02.example.com
     failover_mode: 'Manual'
     availability_mode: 'AsynchronousCommit'
     seeding_mode: 'Automatic'

plugins/modules/agent_job.py

@@ -69,10 +69,10 @@
 '''
 
 EXAMPLES = r'''
-- name: Create a job
+- name: Create a SQL Server Agent job
   lowlydba.sqlserver.agent_job:
-    sql_instance: sql-01.myco.io
-    job: MyJob
+    sql_instance: sql01.example.com
+    job: NightlyBackup
     force: true
 '''
 

plugins/modules/agent_job_category.py

@@ -34,10 +34,10 @@
 '''
 
 EXAMPLES = r'''
-- name: Create a maintenance job category
+- name: Create a SQL Server Agent job category
   lowlydba.sqlserver.agent_job_category:
-    sql_instance: sql-01.myco.io
-    category: "Index Maintenance"
+    sql_instance: sql01.example.com
+    category: Index Maintenance
 '''
 
 RETURN = r'''

plugins/modules/agent_job_schedule.py

@@ -115,22 +115,24 @@
 '''
 
 EXAMPLES = r'''
-- name: Create a job schedule
+- name: Create a daily SQL Server Agent schedule
   lowlydba.sqlserver.agent_job_schedule:
-    sql_instance: sql-01.myco.io
+    sql_instance: sql01.example.com
+    job: NightlyBackup
     schedule: DailySchedule
     force: true
     enabled: true
-    start_date: 2020-05-25  # May 25, 2020
-    end_date: 2099-05-25    # May 25, 2099
-    start_time: 010500      # 01:05:00 AM
-    end_time: 140030        # 02:00:30 PM
+    frequency_type: Daily
+    start_date: '20260101'
+    end_date: '20991231'
+    start_time: '010500'
+    end_time: '140030'
     state: present
 
-- name: Create a job with schedule
+- name: Assign the schedule to a SQL Server Agent job
   lowlydba.sqlserver.agent_job:
-    sql_instance: sql-01.myco.io
-    job: MyJob
+    sql_instance: sql01.example.com
+    job: NightlyBackup
     force: true
     schedule: DailySchedule
 '''

plugins/modules/agent_job_step.py

@@ -102,28 +102,28 @@
 '''
 
 EXAMPLES = r'''
-- name: Create a job
+- name: Create a SQL Server Agent job
   lowlydba.sqlserver.agent_job:
-    sql_instance: sql-01.myco.io
-    job: MyJob
+    sql_instance: sql01.example.com
+    job: NightlyBackup
     force: true
 
-- name: Create a job step
+- name: Create a SQL Server Agent job step
   lowlydba.sqlserver.agent_job_step:
-    sql_instance: sql-01.myco.io
-    job: MyJob
-    step_name: Step1
+    sql_instance: sql01.example.com
+    job: NightlyBackup
+    step_name: TruncateStagingTable
     step_id: 1
     command: "TRUNCATE TABLE dbo.TestData;"
 
-- name: Create a job step with output file
+- name: Create a job step with output redirected to a file
   lowlydba.sqlserver.agent_job_step:
-    sql_instance: sql-01.myco.io
-    job: MyJob
-    step_name: Step2
+    sql_instance: sql01.example.com
+    job: NightlyBackup
+    step_name: ListDatabases
     step_id: 2
     command: "SELECT * FROM sys.databases;"
-    output_file: "C:\\Logs\\MyJob_Step2.log"
+    output_file: "C:\\Logs\\NightlyBackup_ListDatabases.log"
 '''
 
 RETURN = r'''

plugins/modules/availability_group.py

@@ -160,10 +160,10 @@
 '''
 
 EXAMPLES = r'''
-- name: Create Availability Group
+- name: Create an availability group
   lowlydba.sqlserver.availability_group:
-    sql_instance: sql-01.myco.io
-    ag_name: AG_MyDatabase
+    sql_instance: sql01.example.com
+    ag_name: AG_App
 '''
 
 RETURN = r'''

plugins/modules/backup.py

@@ -175,17 +175,17 @@
 '''
 
 EXAMPLES = r'''
-- name: Create striped full database backup in default dir
+- name: Create a striped full database backup
   lowlydba.sqlserver.backup:
-    sql_instance: sql-01.myco.io
-    database: LowlyDB
+    sql_instance: sql01.example.com
+    database: AppDb
     type: full
     file_count: 8
 
-- name: Create t-log backup
+- name: Create a transaction log backup
   lowlydba.sqlserver.backup:
-    sql_instance: sql-01.myco.io
-    database: LowlyDB
+    sql_instance: sql01.example.com
+    database: AppDb
     type: log
 '''
 

plugins/modules/credential.py

@@ -58,28 +58,31 @@
 EXAMPLES = r'''
 - name: Create a credential with a password
   lowlydba.sqlserver.credential:
-    sql_instance: sql-01.myco.io
-    identity: ad\\user
-    name: MyCredential
-    password : <Password>
+    sql_instance: sql01.example.com
+    identity: EXAMPLE\sql-backup
+    name: BackupCredential
+    password: "{{ vault_backup_credential_password }}"
 
 - name: Replace an existing credential
   lowlydba.sqlserver.credential:
-    sql_instance: sql-01.myco.io
-    identity: MyIdentity
+    sql_instance: sql01.example.com
+    identity: EXAMPLE\sql-backup
+    name: BackupCredential
+    password: "{{ vault_backup_credential_password }}"
     force: true
 
 - name: Create a credential using a SAS token for a backup URL
   lowlydba.sqlserver.credential:
-    sql_instance: sql-01.myco.io
+    sql_instance: sql01.example.com
     identity: SHARED ACCESS SIGNATURE
-    name: https://<azure storage account name>.blob.core.windows.net/<blob container>
-    password : <Shared Access Token>
+    name: https://examplestorage.blob.core.windows.net/sql-backups
+    password: "{{ vault_azure_storage_sas_token }}"
 
 - name: Remove a credential
   lowlydba.sqlserver.credential:
-    sql_instance: sql-01.myco.io
-    identity: MyIdentity
+    sql_instance: sql01.example.com
+    identity: EXAMPLE\sql-backup
+    name: BackupCredential
     state: absent
 '''
 

plugins/modules/database.py

@@ -79,15 +79,15 @@
 '''
 
 EXAMPLES = r'''
-- name: Create database
+- name: Create a database
   lowlydba.sqlserver.database:
-    sql_instance: sql-01.myco.io
-    database: LowlyDB
+    sql_instance: sql01.example.com
+    database: AppDb
 
-- name: Create database with customizations
+- name: Create a database with custom settings
   lowlydba.sqlserver.database:
-    sql_instance: sql-01.myco.io
-    database: LowlyDB
+    sql_instance: sql01.example.com
+    database: ReportingDb
     owner: sa
     maxdop: 2
     recovery_model: Simple

plugins/modules/dba_multitool.py

@@ -51,8 +51,8 @@
 EXAMPLES = r'''
 - name: Install DBA MultiTool
   lowlydba.sqlserver.dba_multitool:
-    sql_instance: test-server.my.company.com
-    database: dba_tools
+    sql_instance: sql01.example.com
+    database: DbaTools
 '''
 
 RETURN = r'''

plugins/modules/first_responder_kit.py

@@ -70,10 +70,10 @@
 '''
 
 EXAMPLES = r'''
-- name: Install FRK
+- name: Install First Responder Kit
   lowlydba.sqlserver.first_responder_kit:
-    sql_instance: test-server.my.company.com
-    database: dba_tools
+    sql_instance: sql01.example.com
+    database: DbaTools
 '''
 
 RETURN = r'''

plugins/modules/hadr.py

@@ -49,9 +49,9 @@
 '''
 
 EXAMPLES = r'''
-- name: Enable hadr with service restart
+- name: Enable HADR and restart the SQL Server service
   lowlydba.sqlserver.hadr:
-    sql_instance: sql-01.myco.io
+    sql_instance: sql01.example.com
     enabled: true
     force: true
 '''

plugins/modules/install_script.py

@@ -90,9 +90,9 @@
 '''
 
 EXAMPLES = r'''
-- name: Migrate a database
+- name: Apply database migration scripts
   lowlydba.sqlserver.install_script:
-    sql_instance: test-server.my.company.com
+    sql_instance: sql01.example.com
     database: AdventureWorks
     path: migrations
 '''

plugins/modules/instance_info.py

@@ -21,9 +21,9 @@
 '''
 
 EXAMPLES = r'''
-- name: Get basic info for an instance
+- name: Get basic instance information
   lowlydba.sqlserver.instance_info:
-    sql_instance: sql-01.myco.io
+    sql_instance: sql01.example.com
 '''
 
 RETURN = r'''