[AaronBarnes07]

DatabaseConnectionConfig gains instance, the SQL Server named instance taken from the Instance input in the connection form's advanced settings. It is sent only for mssql and mssql_linked, the two engines that declare it on the server, pruned in _serialize the way data_encoding and iam_role_arn already are.

port becomes optional in the same change. A connection that names an instance is reached through the SQL Server Browser and is saved with the Port field blank, and the admin server stores the config with exclude_none=True, so GET /api/connections/ returns no port key for it. The client's port: int rejected that payload outright, so the new field would have been unreadable on the one connection shape it exists for.

Jira: https://datamasque.atlassian.net/browse/DM-5394

Decisions this change rests on

port became optional, which the ticket did not ask for. The server has had port: int | None = None on every database connection for a long time, and the merged ui-testing test test_sql_server_named_instance_saved_with_blank_port_keeps_instance_on_edit asserts the blank port is the point of a named instance. I rejected adding instance alone, because it ships a field that cannot be read back on the connection it is for, and I rejected a per-engine port validator, because the server imposes no such requirement and the client should not be stricter than the API it wraps. SnowflakeConnectionConfig.port is already Optional[int], so this follows the file rather than setting a new precedent. Evidence that the admin server rejects a create with no port would overturn it; I checked, and validation runs through the same pydantic schema that defaults it to None.

instance is kept for mssql_linked, not only mssql. Both server schema variants declare it and the connection form offers the input for both. The agent ignores the value on the linked-server path, so the field is carried rather than acted on for that engine. I rejected dropping it client-side for that engine, because it would lose a value the server round-trips. The server removing instance from MssqlLinkedConnection would change it.

No version bump. The HISTORY.rst entry goes under 1.6.0 (unreleased), which is the repo's convention. I rejected bumping the version here, because it couples a model change to a release decision. A maintainer wanting this released on its own would change it; the PyPI publish is a separate step either way.

Test evidence

Run in a worktree on the branch head, 1ff1346, on 2026-11-09 and re-run unchanged on 2026-11-12 before this pull request was opened:

• make lint: ruff check, ruff format --check and mypy all clean, 39 source files type-checked.
• uv run pytest: 579 passed.
• Ten new tests in tests/test_connections.py covering read-back with and without an instance, the round trip back to the API, the create request body, the linked-server variant, and the prune for five non-SQL-Server engines. The red half was proved by reverting only connection.py and re-running: 9 of the 10 fail without the model change. The tenth, test_database_connection_omits_the_named_instance_when_unset, passes either way because an absent field is absent either way; it is kept for symmetry with test_database_connection_omits_tagging_iam_role_when_unset, which has the same property.

I reviewed the diff and fixed one thing: a test docstring explained the prune by comparing it to the data_encoding prune, and now states that these engines have no instance field on the server. Two style-guard hits, in tests/test_connections.py and datamasque/client/models/connection.py, are pre-existing and outside this diff, confirmed with git blame, so I left them.

No AIT run and no UI test run: the change is confined to the client library and touches no masking engine, no admin-frontend/ and no ui-testing/.

Not in this change

Switching the ui-testing named-instance assertions to the typed model needs a released datamasque-python, so it follows this merging and the release. It also needs more than this field: the TODO DM-5394 in get_connections_json_by_name gives a second reason for the raw-JSON workaround, that list_connections raises when any connection on the instance fails to deserialise. That is untouched by this change and would exist regardless.

No companion merge requests: this change is confined to one repository.