pgtoolkit.hba

This module supports reading, validating, editing and rendering pg_hba.conf file. See Client Authentication in PostgreSQL documentation for details on format and values of pg_hba.conf file.

API Reference

The main entrypoint of this API is the parse() function. It returns a HBA object containing HBARecord instances.

pgtoolkit.hba.parse(file: str | Iterable[str] | Path) → HBA

Parse a pg_hba.conf file.

Parameters:

file – Either a line iterator such as a file-like object, a path or a string corresponding to the path to the file to open and parse.

Return type:

HBA.

class pgtoolkit.hba.HBA(entries: Iterable[HBAComment | HBARecord] | None = None)

Represents pg_hba.conf records

lines

List of HBARecord and comments.

path

Path to a file. Is automatically set when calling parse() with a path to a file. save() will write to this file if set.

__iter__() → Iterator[HBARecord]

Iterate on records, ignoring comments and blank lines.

parse(fo: Iterable[str]) → None

Parse records and comments from file object

Parameters:

fo – An iterable returning lines

save(fo: str | Path | IO[str] | None = None) → None

Write records and comments in a file

Parameters:

fo – a file-like object. Is not required if path is set.

Line order is preserved. Record fields are vertically aligned to match the columen size of column headers from default configuration file.

# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             all                                     trust

remove(filter: Callable[[HBARecord], bool] | None = None, **attrs: str) → bool

Remove records matching the provided attributes.

One can for example remove all records for which user is ‘david’.

Parameters:

• filter – a function to be used as filter. It is passed the record to test against. If it returns True, the record is removed. It is kept otherwise.

• attrs – keyword/values pairs correspond to one or more HBARecord attributes (ie. user, conntype, etc…)

Returns:

True if records have changed.

Usage examples:

hba.remove(filter=lamdba r: r.user == 'david')
hba.remove(user='david')

merge(other: HBA) → bool

Add new records to HBAFile or replace them if they are matching

(ie. same conntype, database, user and address)

Parameters:

other – HBAFile to merge into the current one. Lines with matching conntype, database, user and database will be replaced by the new one. Otherwise they will be added at the end. Comments from the original hba are preserved.

Returns:

True if records have changed.

class pgtoolkit.hba.HBARecord(values: Iterable[tuple[str, str]] | dict[str, Any] | None = None, comment: str | None = None, **kw_values: str | Sequence[str])

Holds a HBA record composed of fields and a comment.

Common fields are accessible through attribute : conntype, databases, users, address, netmask, method. Auth-options fields are also accessible through attribute like map, ldapserver, etc.

address and netmask fields are not always defined. If not, accessing undefined attributes trigger an AttributeError.

databases and users have a single value variant respectively database and user, computed after the list representation of the field.

classmethod parse(line: str) → HBARecord

Parse a HBA record

Return type:

HBARecord or a str for a comment or blank line.

Raises:

ValueError – If connection type is wrong.

__init__(values: Iterable[tuple[str, str]] | dict[str, Any] | None = None, comment: str | None = None, **kw_values: str | Sequence[str]) → None

Parameters:

• values – A dict of fields.

• kw_values – Fields passed as keyword.

• comment – Comment at the end of the line.

__str__() → str

Serialize a record line, without EOL.

matches(**attrs: str) → bool

Tells if the current record is matching provided attributes.

Parameters:

attrs – keyword/values pairs corresponding to one or more HBARecord attributes (ie. user, conntype, etc…)

database

Hold database column as a single value.

Use databases attribute to get parsed database list. database is guaranteed to be a string.

user

Hold user column as a single value.

Use users property to get parsed user list. user is guaranteed to be a string.

Examples

Loading a pg_hba.conf file :

pgpass = parse('my_pg_hba.conf')

You can also pass a file-object:

with open('my_pg_hba.conf', 'r') as fo:
    hba = parse(fo)

Creating a pg_hba.conf file from scratch :

hba = HBA()
record = HBARecord(
    conntype='local', database='all', user='all', method='peer',
)
hba.lines.append(record)

with open('pg_hba.conf', 'w') as fo:
    hba.save(fo)

Using as a script

pgtoolkit.hba is usable as a CLI script. It accepts a pg_hba file path as first argument, read it, validate it and re-render it. Fields are aligned to fit pseudo-column width. If filename is -, stdin is read instead.

$ python -m pgtoolkit.hba - < data/pg_hba.conf
# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     trust
# IPv4 local connections:
host    all             all             127.0.0.1/32            ident map=omicron