DbAuth

class lsst.daf.butler.registry.DbAuth(path: str | None = None, envVar: str | None = None, authList: list[dict[str, str]] | None = None)

Bases: object

Retrieves authentication information for database connections.

The authorization configuration is taken from the authList parameter or a (group- and world-inaccessible) YAML file located at a path specified by the given environment variable or at a default path location.

Parameters:
pathstr or None, optional

Path to configuration file.

envVarstr or None, optional

Name of environment variable pointing to configuration file.

authListlist [dict] or None, optional

Authentication configuration.

Notes

At least one of path, envVar, or authList must be provided; generally path should be provided as a default location.

Methods Summary

getAuth(dialectname, username, host, port, ...)

Retrieve a username and password for a database connection.

getUrl(url)

Fill in a username and password in a database connection URL.

Methods Documentation

getAuth(dialectname: str | None, username: str | None, host: str | None, port: int | str | None, database: str | None) → tuple[str | None, str]

Retrieve a username and password for a database connection.

This function matches elements from the database connection URL with glob-like URL patterns in a list of configuration dictionaries.

Parameters:
dialectnamestr

Database dialect, for example sqlite, mysql, postgresql, oracle, or mssql.

usernamestr or None

Username from connection URL if present.

hoststr

Host name from connection URL if present.

portstr or int or None

Port from connection URL if present.

databasestr

Database name from connection URL.

Returns:
username: str

Username to use for database connection; same as parameter if present.

password: str

Password to use for database connection.

Raises:
DbAuthError

Raised if the input is missing elements, an authorization dictionary is missing elements, the authorization file is misconfigured, or no matching authorization is found.

Notes

The list of authorization configuration dictionaries is tested in order, with the first matching dictionary used. Each dictionary must contain a url item with a pattern to match against the database connection URL and a password item. If no username is provided in the database connection URL, the dictionary must also contain a username item.

The url item must begin with a dialect and is not allowed to specify dialect+driver.

Glob-style patterns (using “*” and “?” as wildcards) can be used to match the host and database name portions of the connection URL. For the username, port, and database name portions, omitting them from the pattern matches against any value in the connection URL.

Examples

The connection URL postgresql://user@host.example.com:5432/my_database matches against the identical string as a pattern. Other patterns that would match include:

  • postgresql://*

  • postgresql://*.example.com

  • postgresql://*.example.com/my_*

  • postgresql://host.example.com/my_database

  • postgresql://host.example.com:5432/my_database

  • postgresql://user@host.example.com/my_database

Note that the connection URL postgresql://host.example.com/my_database would not match against the pattern postgresql://host.example.com:5432, even if the default port for the connection is 5432.

getUrl(url: str) → str

Fill in a username and password in a database connection URL.

This function parses the URL and calls getAuth.

Parameters:
urlstr

Database connection URL.

Returns:
urlstr

Database connection URL with username and password.

Raises:
DbAuthError

Raised if the input is missing elements, an authorization dictionary is missing elements, the authorization file is misconfigured, or no matching authorization is found.

See also

getAuth