ds_provider_microsoft_py_lib.linked_service
===========================================

.. py:module:: ds_provider_microsoft_py_lib.linked_service

.. autoapi-nested-parse::

   **File:** ``__init__.py``
   **Region:** ``ds-provider-microsoft-py-lib/linked_service``

   Linked service module for Microsoft provider.

   Example:
   >>> linked_service = MsSqlLinkedService(
   ...     settings=MsSqlLinkedServiceSettings(
   ...         server="account name",
   ...         database="database",
   ...         username="username",
   ...         password="password",
   ...     ),
   ...     id=uuid.uuid4(),
   ...     name="testmssqlpackage",
   ...     version="0.0.1",
   ...     description="testmssqlpackage"
   ... )
   >>> linked_service.connect()



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/ds_provider_microsoft_py_lib/linked_service/mssql/index


Classes
-------

.. autoapisummary::

   ds_provider_microsoft_py_lib.linked_service.MsSqlLinkedService
   ds_provider_microsoft_py_lib.linked_service.MsSqlLinkedServiceSettings


Package Contents
----------------

.. py:class:: MsSqlLinkedService

   Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.linked_service.LinkedService`\ [\ :py:obj:`MsSqlLinkedServiceSettingsType`\ ], :py:obj:`Generic`\ [\ :py:obj:`MsSqlLinkedServiceSettingsType`\ ]


   Linked service for connecting to Microsoft SQL Server.

   This linked service manages connections to SQL Server databases.
   It handles authentication, connection lifecycle, and error handling
   according to the linked service contract.

   .. rubric:: Example

   >>> settings = MsSqlLinkedServiceSettings(
   ...     server="localhost",
   ...     database="mydb",
   ...     username="user",
   ...     password="pass"
   ... )
   >>> service = MsSqlLinkedService(
   ...     settings=settings,
   ...     id=uuid.uuid4(),
   ...     name="my_mssql",
   ...     version="0.0.1"
   ... )
   >>> service.connect()
   >>> with service as svc:
   ...     data = svc.connection.execute(...)


   .. py:attribute:: settings
      :type:  MsSqlLinkedServiceSettingsType


   .. py:attribute:: _connection
      :type:  sqlalchemy.engine.Engine | None
      :value: None


      The SQLAlchemy Engine instance representing the connection to the SQL Server database.


   .. py:method:: check_settings_is_set() -> None

      Check if settings are set correctly.

      :returns: None

      :raises AttributeError: If settings are not set correctly.



   .. py:property:: connection
      :type: sqlalchemy.engine.Engine


      Get the backend connection (SQLAlchemy Engine).

      :returns: The SQLAlchemy Engine instance.
      :rtype: Engine

      :raises ConnectionError: If connect() has not been called.


   .. py:property:: type
      :type: ds_provider_microsoft_py_lib.enums.ResourceType


      Get the type of the linked service.

      :returns: ResourceType


   .. py:method:: _get_connection_string() -> str

      Build the ODBC connection string.

      :returns: The ODBC connection string.
      :rtype: str



   .. py:method:: _create_engine() -> sqlalchemy.engine.Engine

      Connect to SQL Server and return SQLAlchemy Engine.

      :returns: The SQLAlchemy Engine instance.
      :rtype: Engine

      :raises ConnectionError: If the engine cannot be created.
      :raises AuthenticationError: If credentials are invalid.



   .. py:method:: connect() -> None

      Establish a connection to Microsoft SQL Server.

      The result is stored internally and accessible via the `connection` property.

      :returns: None

      :raises ConnectionError: If the connection cannot be established.
      :raises AuthenticationError: If credentials are invalid.

      Rules:
          - Idempotent: Calling connect() on an already-connected service reuses the connection.
          - Must authenticate using credentials from self.settings.
          - Must fail loudly if connection cannot be established.



   .. py:method:: test_connection() -> tuple[bool, str]

      Verify that the connection to Microsoft SQL Server is healthy.

      Performs a lightweight check against the backend (a simple SELECT 1 query).
      This method does not raise on connection failure -- instead returns
      (False, "error message"). Exceptions are reserved for unexpected internal errors.

      :returns: (True, "").
                On failure: (False, "reason").
      :rtype: tuple[bool, str] -- On success

      Rules:
          - Must not raise on connection failure.
          - Must not modify any data.
          - Should complete quickly.
          - Idempotent: Yes.



   .. py:method:: close() -> None

      Release connections, sessions, or handles held by the linked service.

      This method is safe to call multiple times and does not raise even if
      the connection is already closed. Called automatically by `__exit__`
      when using a context manager.

      :returns: None

      Rules:
          - Must release any open connections, sessions, or handles.
          - Must not raise if the connection is already closed.
          - Must be safe to call multiple times.
          - Idempotent: Yes.



.. py:class:: MsSqlLinkedServiceSettings

   Bases: :py:obj:`ds_resource_plugin_py_lib.common.resource.linked_service.LinkedServiceSettings`


   The object containing the Microsoft SQL Server linked service settings.


   .. py:attribute:: server
      :type:  str

      The hostname or IP address of the SQL Server instance.


   .. py:attribute:: database
      :type:  str

      The name of the database to connect to.


   .. py:attribute:: username
      :type:  str

      The username for authentication.


   .. py:attribute:: password
      :type:  str

      The password for authentication. This field is masked in logs and serialized output.


   .. py:attribute:: port
      :type:  int
      :value: 1433


      The port number for the SQL Server instance. Defaults to 1433, the standard port for SQL Server.


   .. py:attribute:: driver
      :type:  str
      :value: 'ODBC Driver 18 for SQL Server'


      The ODBC driver to use for the connection. Defaults to "ODBC Driver 18 for SQL Server"


   .. py:attribute:: encrypt
      :type:  bool
      :value: True


      Whether to encrypt the connection. Defaults to True.


   .. py:attribute:: trust_server_certificate
      :type:  bool
      :value: False


      Whether to trust the server certificate when encrypting. Defaults to False.


   .. py:attribute:: connection_timeout
      :type:  int
      :value: 30


      The connection timeout in seconds. Defaults to 30.