mssql_*: named instances (#11664)

* mssql_*: named instances

* add changelog frag

* fix changelog

* Update plugins/modules/mssql_db.py

* Update plugins/modules/mssql_db.py

* Update plugins/modules/mssql_script.py

* Update plugins/modules/mssql_script.py

* fix backslashes

* Update plugins/modules/mssql_db.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update plugins/modules/mssql_script.py

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/11664-mssql-named-instance-port.yml

@@ -0,0 +1,9 @@
+bugfixes:
+  - mssql_db - fail with a clear error message when a named instance (``server\instance`` format)
+    is used together with ``login_port``, since these are mutually exclusive connection methods
+    (https://github.com/ansible-collections/community.general/issues/5693,
+    https://github.com/ansible-collections/community.general/pull/11664).
+  - mssql_script - fail with a clear error message when a named instance (``server\instance`` format)
+    is used together with ``login_port``, since these are mutually exclusive connection methods
+    (https://github.com/ansible-collections/community.general/issues/5693,
+    https://github.com/ansible-collections/community.general/pull/11664).

plugins/modules/mssql_db.py

@@ -39,12 +39,14 @@ options:
   login_host:
     description:
       - Host running the database.
+      - For named instances, use the format V(server\\instance). In that case, do not use O(login_port).
     type: str
     required: true
   login_port:
     description:
       - Port of the MSSQL server. Requires login_host be defined as other than localhost if login_port is used.
-    default: '1433'
+      - Cannot be used together with a named instance in O(login_host) (that is, V(server\\instance) format).
+      - If O(login_host) is not a named instance and O(login_port) is not specified, it defaults to V(1433).
     type: str
   state:
     description:
@@ -154,7 +156,7 @@ def main():
             login_user=dict(default=""),
             login_password=dict(default="", no_log=True),
             login_host=dict(required=True),
-            login_port=dict(default="1433"),
+            login_port=dict(),
             target=dict(),
             autocommit=dict(type="bool", default=False),
             state=dict(default="present", choices=["present", "absent", "import"]),
@@ -174,8 +176,14 @@ def main():
     login_host = module.params["login_host"]
     login_port = module.params["login_port"]
 
+    if "\\" in login_host and login_port is not None:
+        module.fail_json(
+            msg=r"login_port cannot be used with a named instance in login_host (server\instance format). "
+            "Named instances use the SQL Server Browser service to resolve the port automatically."
+        )
+
     login_querystring = login_host
-    if login_port != "1433":
+    if "\\" not in login_host and login_port is not None:
         login_querystring = f"{login_host}:{login_port}"
 
     if login_user != "" and login_password == "":

plugins/modules/mssql_script.py

@@ -39,12 +39,16 @@ options:
     description: The password used to authenticate with.
     type: str
   login_host:
-    description: Host running the database.
+    description:
+      - Host running the database.
+      - For named instances, use the format V(server\\instance). In that case, do not use O(login_port).
     type: str
     required: true
   login_port:
-    description: Port of the MSSQL server. Requires O(login_host) be defined as well.
+    description:
-    default: 1433
+      - Port of the MSSQL server. Requires O(login_host) to be defined as well.
+      - Cannot be used together with a named instance in O(login_host) (that is, V(server\\instance) format).
+      - If O(login_host) is not a named instance and O(login_port) is not specified, it defaults to V(1433).
     type: int
   script:
     description:
@@ -287,7 +291,7 @@ def run_module():
         login_user=dict(),
         login_password=dict(no_log=True),
         login_host=dict(required=True),
-        login_port=dict(type="int", default=1433),
+        login_port=dict(type="int"),
         script=dict(required=True),
         output=dict(default="default", choices=["dict", "default"]),
         params=dict(type="dict"),
@@ -313,8 +317,14 @@ def run_module():
     # Added param to set the transactional mode (true/false)
     transaction = module.params["transaction"]
 
+    if "\\" in login_host and login_port is not None:
+        module.fail_json(
+            msg=r"login_port cannot be used with a named instance in login_host (server\instance format). "
+            "Named instances use the SQL Server Browser service to resolve the port automatically."
+        )
+
     login_querystring = login_host
-    if login_port != 1433:
+    if "\\" not in login_host and login_port is not None:
         login_querystring = f"{login_host}:{login_port}"
 
     if login_user is not None and login_password is None: