_dns - DNS resolution utilities #

This module contains a few experimental utilities to interact with the DNS server before performing a connection.

$ pip install "dnspython >= 2.1"

psycopg._dns. resolve_srv ( params ) #

Apply SRV DNS lookup as defined in RFC 2782 .

Parameters :

params ( dict ) - The input parameters, for instance as returned by conninfo_to_dict() .

Returns :

An updated list of connection parameters.

For every host defined in the params["host"] list (comma-separated), perform SRV lookup if the host is in the form _Service._Proto.Target . If lookup is successful, return a params dict with hosts and ports replaced with the looked-up entries.

Raise OperationalError if no lookup is successful and no host (looked up or unchanged) could be returned.

In addition to the rules defined by RFC 2782 about the host name pattern, perform SRV lookup also if the the port is the string SRV (case insensitive).

Warning

This is an experimental functionality.

Note

One possible way to use this function automatically is to subclass Connection , extending the _get_connection_params() method:

import psycopg._dns  # not imported automatically

class SrvCognizantConnection(psycopg.Connection):
    @classmethod
    def _get_connection_params(cls, conninfo, **kwargs):
        params = super()._get_connection_params(conninfo, **kwargs)
        params = psycopg._dns.resolve_srv(params)
        return params

# The name will be resolved to db1.example.com
cnn = SrvCognizantConnection.connect("host=_postgres._tcp.db.psycopg.org")

async psycopg._dns. resolve_srv_async ( params ) #

Async equivalent of resolve_srv() .

classmethod Connection. _get_connection_params ( conninfo , ** kwargs ) #

Manipulate connection parameters before connecting.

Parameters :

• conninfo ( str ) - Connection string as received by connect() .

• kwargs ( Any ) - Overriding connection arguments as received by connect() .

Return type :

Dict [ str , Any ]

Returns :

Connection arguments merged and eventually modified, in a format similar to conninfo_to_dict() .

Warning

This is an experimental method.

This method is a subclass hook allowing to manipulate the connection parameters before performing the connection. Make sure to call the super() implementation before further manipulation of the arguments:

@classmethod
def _get_connection_params(cls, conninfo, **kwargs):
    params = super()._get_connection_params(conninfo, **kwargs)
    # do something with the params
    return params

async classmethod AsyncConnection. _get_connection_params ( conninfo , ** kwargs ) #

Manipulate connection parameters before connecting. :rtype: Dict [ str , Any ]

Changed in version 3.1: Unlike the sync counterpart, perform non-blocking address resolution and populate the hostaddr connection parameter, unless the user has provided one themselves. See ~psycopg._dns.resolve_hostaddr_async() for details.

Warning

This is an experimental method.

async psycopg._dns. resolve_hostaddr_async ( params ) #

Perform async DNS lookup of the hosts and return a new params dict.

Deprecated since version 3.1: The use of this function is not necessary anymore, because psycopg.AsyncConnection.connect() performs non-blocking name resolution automatically.

Parameters :

params ( !dict ) - The input parameters, for instance as returned by ~psycopg.conninfo.conninfo_to_dict() .

If a host param is present but not hostname , resolve the host addresses dynamically.

The function may change the input host , hostname , port to allow connecting without further DNS lookups, eventually removing hosts that are not resolved, keeping the lists of hosts and ports consistent.

Raise ~psycopg.OperationalError if connection is not possible (e.g. no host resolve, inconsistent lists length).

See the PostgreSQL docs for explanation of how these params are used, and how they support multiple entries.

Warning

Before psycopg 3.1, this function doesn’t handle the /etc/hosts file.

Note

Starting from psycopg 3.1, a similar operation is performed automatically by !AsyncConnection._get_connection_params() , so this function is unneeded.

In psycopg 3.0, one possible way to use this function automatically is to subclass ~psycopg.AsyncConnection , extending the ~psycopg.AsyncConnection._get_connection_params() method:

import psycopg._dns  # not imported automatically

class AsyncDnsConnection(psycopg.AsyncConnection):
    @classmethod
    async def _get_connection_params(cls, conninfo, **kwargs):
        params = await super()._get_connection_params(conninfo, **kwargs)
        params = await psycopg._dns.resolve_hostaddr_async(params)
        return params