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]) HBA [source]
Parse a pg_hba.conf file.
- Parameters:
file – Either a line iterator such as a file-like object 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)[source]
Represents pg_hba.conf records
- 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.
- parse(fo: Iterable[str]) None [source]
Parse records and comments from file object
- Parameters:
fo – An iterable returning lines
- save(fo: str | Path | IO[str] | None = None) None [source]
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) None [source]
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…)
Usage examples:
hba.remove(filter=lamdba r: r.user == 'david') hba.remove(user='david')
- merge(other: HBA) None [source]
- 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.
- class pgtoolkit.hba.HBARecord(values: Iterable[tuple[str, str]] | dict[str, Any] | None = None, comment: str | None = None, **kw_values: str | Sequence[str])[source]
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 likemap
,ldapserver
, etc.address
andnetmask
fields are not always defined. If not, accessing undefined attributes trigger anAttributeError
.databases
andusers
have a single value variant respectivelydatabase
anduser
, computed after the list representation of the field.- classmethod parse(line: str) HBARecord [source]
Parse a HBA record
- Return type:
- 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 [source]
- Parameters:
values – A dict of fields.
kw_values – Fields passed as keyword.
comment – Comment at the end of the line.
- matches(**attrs: str) bool [source]
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