ds_provider_postgresql_py_lib.linked_service.postgresql
=======================================================

.. py:module:: ds_provider_postgresql_py_lib.linked_service.postgresql

.. autoapi-nested-parse::

   **File:** ``postgresql.py``
   **Region:** ``ds_provider_postgresql_py_lib/linked_service/postgresql``

   PostgreSQL Linked Service

   This module implements a linked service for PostgreSQL databases.

   .. rubric:: Example

   >>> linked_service = PostgreSQLLinkedService(
   ...     settings=PostgreSQLLinkedServiceSettings(
   ...         uri="postgresql://user:password@localhost:5432/mydb",
   ...     ),
   ... )
   >>> linked_service.connect()



Attributes
----------

.. autoapisummary::

   ds_provider_postgresql_py_lib.linked_service.postgresql.logger
   ds_provider_postgresql_py_lib.linked_service.postgresql.PostgreSQLLinkedServiceSettingsType


Classes
-------

.. autoapisummary::

   ds_provider_postgresql_py_lib.linked_service.postgresql.PostgreSQLLinkedServiceSettings
   ds_provider_postgresql_py_lib.linked_service.postgresql.PostgreSQLLinkedService


Module Contents
---------------

.. py:data:: logger

.. py:class:: PostgreSQLLinkedServiceSettings

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


   The object containing the PostgreSQL linked service settings.


   .. py:attribute:: uri
      :type:  str

      PostgreSQL connection URI.

      Format: postgresql://[user[:password]@][host][:port][/database][?param1=value1&param2=value2]

      .. rubric:: Examples

      postgresql://user:password@localhost:5432/mydb
      postgresql://user:password@localhost:5432/mydb?sslmode=require
      postgresql://user@localhost/mydb
      postgresql://localhost/mydb


   .. py:attribute:: pool_size
      :type:  int
      :value: 5


      The size of the connection pool. Defaults to 5.


   .. py:attribute:: max_overflow
      :type:  int
      :value: 10


      The maximum overflow connections allowed. Defaults to 10.


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


      The timeout in seconds for getting a connection from the pool. Defaults to 30.


   .. py:attribute:: pool_recycle
      :type:  int
      :value: 3600


      The time in seconds after which a connection is recycled. Defaults to 3600.


.. py:data:: PostgreSQLLinkedServiceSettingsType

.. py:class:: PostgreSQLLinkedService

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


   The class is used to connect with PostgreSQL database.


   .. py:attribute:: settings
      :type:  PostgreSQLLinkedServiceSettingsType


   .. py:attribute:: _engine
      :type:  sqlalchemy.Engine | None
      :value: None


      The SQLAlchemy engine instance with connection pool.


   .. py:property:: type
      :type: ds_provider_postgresql_py_lib.enums.ResourceType


      Get the type of the linked service.

      :returns: ResourceType


   .. py:property:: engine
      :type: sqlalchemy.Engine | None


      Get the SQLAlchemy engine instance.

      :returns: The engine if initialized, None otherwise.
      :rtype: Engine | None


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


      Get the established backend connection object.

      :returns: The initialized SQLAlchemy engine.
      :rtype: Engine

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


   .. py:property:: pool
      :type: sqlalchemy.pool.Pool | None


      Get the connection pool from the engine.

      The pool is automatically created by SQLAlchemy when create_engine() is called
      with pool parameters. All connections (via engine.connect(), engine.begin(), etc.)
      automatically use this pool.

      :returns: The connection pool if the engine is initialized, None otherwise.
      :rtype: Pool | None


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

      Connect to the PostgreSQL database and create a connection pool.

      :returns: None



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

      Test the connection to the PostgreSQL database.

      :returns: A tuple containing a boolean indicating success and a string message.
      :rtype: tuple[bool, str]



   .. py:method:: _is_authentication_error(error: Exception) -> bool

      Detect authentication failures from SQLAlchemy/driver exceptions.

      :param error: The exception to check.

      :returns: True if the error is an authentication error, False otherwise.
      :rtype: bool



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

      Close the linked service.