pgflux package

Subpackages

Submodules

pgflux.cli module

pgflux.cli.list_outputs(stream: TextIO) → None

List all available output targets.

Parameters

stream – The target stream where the result will be printed into.

pgflux.cli.list_queries(stream: TextIO) → None

List all available queries.

Parameters

stream – The target stream where the result will be printed into.

pgflux.cli.list_queries_internal(scope: pgflux.core.Scope, stream: TextIO) → None

List all available queries with the given scope.

Parameters

  • scope – Either database-local or cluster-global

  • stream – The target stream where the result will be printed into.

pgflux.cli.main() → int

Main CLI entry-point of the script

pgflux.cli.parse_args(args: Optional[List[str]] = None) → argparse.Namespace

Parse command-line arguments

pgflux.cli.setup_logging(is_verbose: bool = False) → None

Enables logging if is_verbose is true. Otherwise this is a no-op.

pgflux.core module

class pgflux.core.FileItem(version: pgflux.core.PgVersion, query_name: str, path: pathlib.Path, scope: pgflux.core.Scope)

Bases: object

A FileItem represents a reference to a SQL file containing a query that can be run against a specific PostgreSQL version (including whether it’s cluster-global or db-local)

path: pathlib.Path

The path of the SQL file

query_name: str

The name of the query contained in the file

scope: pgflux.core.Scope

Whether the query is cluster-global or db-local

version: pgflux.core.PgVersion

The detected PostgreSQL version

class pgflux.core.PgVersion(major: int, minor: int)

Bases: NamedTuple

A simple data-type to represent the detected PostgreSQL version.

major: int

Alias for field number 0

minor: int

Alias for field number 1

class pgflux.core.QueryCollection(cluster: Dict[str, Dict[pgflux.core.PgVersion, str]], db: Dict[str, Dict[pgflux.core.PgVersion, str]])

Bases: object

A collection of queries to run against either the whole DB cluster, or a specific DB.

Some queries return statistics relative to the active client-connection. Others report values of the whole cluster and can be run from any connection.

cluster: Dict[str, Dict[pgflux.core.PgVersion, str]]

Queries to be run against the whole cluster

db: Dict[str, Dict[pgflux.core.PgVersion, str]]

Queries to be run against a single DB

class pgflux.core.Scope(value)

Bases: enum.Enum

The possible scopes for queries

CLUSTER = 'cluster'

“cluster” contains all queries which can be run against the whole cluster

DB = 'db'

“db” contains all queries which have to be run against a specific connection

pgflux.core.connect() → psycopg2.extensions.connection

Create a new database connection using the PGFLUX_POSTGRES_DSN environment variable.

The variable is also loaded from a .env file in the current working folder if it exists.

pgflux.core.execute_global(connection: Any, queries: Dict[str, Dict[pgflux.core.PgVersion, str]], query_name: str) → Iterable[Dict[str, Any]]

Execute a query (by name) against the database cluster and return all rows.

Parameters

  • connection – A reference to the DB cluster

  • queries – A collection of queries

  • query_name – The name of the query to execute

Returns

An iterable over the rows (columns depend on the executed query)

pgflux.core.execute_local(connection: Any, queries: Dict[str, Dict[pgflux.core.PgVersion, str]], query_name: str, dbname: str) → Iterable[Dict[str, Any]]

Execute a query (by name) against the database cluster and return all rows.

Parameters

  • connection – A reference to the DB cluster

  • queries – A collection of queries

  • query_name – The name of the query to execute

  • dbname – The name of the database to connect to

Returns

An iterable over the rows (columns depend on the executed query)

pgflux.core.execute_query(query: str, exclude: List[str], output: Output) → None

Run the given query against the DB clusters excluding any databases where the name matches any regex in exclude.

Parameters

  • query – The name of the query to execute

  • exclude – A list of regexes which are all used to verify if a database should be excluded from the stats. If any one of them matches, the DB is skipped.

pgflux.core.get_pg_version(cursor: Any) → pgflux.core.PgVersion

Returns the posgtes server version as a tuple of integers.

Example:

>>> get_pg_version(conn)
(9, 5, 8)
pgflux.core.get_query(queries: Dict[str, Dict[pgflux.core.PgVersion, str]], query_name: str, version: pgflux.core.PgVersion) → str

Retrieve a query from a collection of queries by name targeted at the given postgres version

pgflux.core.get_query_filename(version: pgflux.core.PgVersion, scope: pgflux.core.Scope, query_name: str) → str

Retrieve the filename where the query for query_name was defined.

Parameters

  • version – The detected PostgreSQL version

  • scope – Whether the query is cluster-global or db-local

  • query_name – The name of the query to look-up

pgflux.core.is_excluded(name: str, pattern: str) → bool

Determine whether the value in name matches the reges in pattern.

If True, also emit a log-message.

pgflux.core.iter_query_files(scope: pgflux.core.Scope) → Iterable[pgflux.core.FileItem]

Iterate over all defined query files.

Parameters

scope – Only return queries from the given scope.

pgflux.core.list_databases(connection: Any, exclude: List[str]) → Iterable[str]

Return a collection of all database names in the cluster connected to by connection.

Parameters

  • connection – A connection to the DB cluster

  • exclude – A list of regexes containing exclusion regexes which are checked against the DB-names.

pgflux.core.load_queries() → pgflux.core.QueryCollection

Load the bundled SQL queries from disk

pgflux.core.with_server_metadata(connection: Any, row: Mapping[str, Any], dbname: str = '') → Dict[str, str]

Enrich a database row with server-metadata.

This will add the following columns to the data in row:

pgflux.enums module

class pgflux.enums.Precision(value)

Bases: enum.Enum

An enumeration.

NANO_SECONDS = 9
SECONDS = 0

pgflux.exc module

exception pgflux.exc.PgFluxException

Bases: Exception

Base exception for pgflux

pgflux.influx module

pgflux.influx.row_to_influx(measurement: str, row: Mapping[str, Any], prefix: str = '', precision: pgflux.enums.Precision = Precision.NANO_SECONDS) → str

Convert db-results from PostgreSQL into a line for InfluxDB line-protocol

The row must contain the key ‘timestamp’ as a unix-timestamp integer value.

When converting, each column name starting with tag: will be converted to an InfluxDB tag, all other columns will be considered an InfluxDB field.

Example:

>>> row_to_influx(
...     'mymeasurement',
...     {'tag:database': 'postgres', 'size': 8758051}
... )
'mymeasurement,database=postgres size=8758051 1234'
pgflux.influx.with_type(value: Union[int, str, float, bool]) → str

Add an InfluxDB line-protocol type-hint.

>>> with_type(10)
'10i'
>>> with_type("hello")
'hello'

Module contents

Main package file