Skip to main content

CI Status PyPI package version PyPI python versions

testgres.postgres_configration

A robust, enterprise-grade Python library designed for parsing, manipulating, and writing PostgreSQL configuration files. This library functions as a modular component of the testgres ecosystem.

What is it?

testgres.postgres_configration provides a comprehensive object-oriented interface to manage complex, multi-file PostgreSQL configurations (such as postgresql.conf and postgresql.auto.conf). It allows developers and QA engineers to programmatically inspect, modify, and save database settings within isolation layers, making it ideal for automated testing infrastructure and database orchestration.

Key Features

  • Multi-File & Include Directive Support: Seamlessly loads, traverses, and writes deeply nested configuration structures utilizing include, include_if_exists, and include_dir directives.
  • Preservation of Comments and Formatting: Built using a dedicated layout tracking engine that preserves human-written inline comments, block comments, blank lines, and file indentation patterns upon serialization.
  • Advanced List-Option Manipulation: Provides high-level APIs like SetOptionValueItem to append items to comma-separated parameters (e.g., shared_preload_libraries) uniquely, eliminating string-concatenation errors.
  • Flexible Validation Strategies (Strict vs Standard):
    • Standard mode mimics real-world PostgreSQL behavior where parameter overrides and duplicates are allowed ("last definition wins").
    • Strict mode enforces single-definition invariants, throwing structured errors when accidental duplicates are detected.
  • Fail-Safe Lifecycle Verification: Leverages internal IsAlive state validation mechanics to safeguard against modifying zombie reference nodes or processing out-of-sync cache handles.
  • Native TestgresException Integration: Features a fully typed, strict hierarchy of operational errors and fatal bug checks derived directly from the core testgres exception package.

Installation

Install the library using pip:

pip install testgres.postgres-configuration

Quick Start Example

The following complete end-to-end example demonstrates how to initialize a temporary cluster via testgres, load its configuration, modify scalar and list properties, and verify changes natively using SQL statements.

import testgres
import testgres.postgres_configuration as testgres_pg_conf

# 1. Initialize a standard temporary PostgreSQL node using testgres
node = testgres.PostgresNode()
node.init()

# 2. Attach our configuration manager to the node's data directory (PGDATA)
cfg = testgres_pg_conf.PostgresConfiguration(node.data_dir)

# Load existing configuration files (postgresql.conf, etc.) from disk
testgres_pg_conf.PostgresConfigurationReader.LoadConfiguration(cfg)

# ----------------------------------------------------------------------
# Setup Initial State for List Demonstration
# ----------------------------------------------------------------------
# Let's explicitly define a base preloaded library first
cfg.SetOptionValue("shared_preload_libraries", "auto_explain")

# ----------------------------------------------------------------------
# Demonstration of GetOptionValue (Reading Current Values)
# ----------------------------------------------------------------------
# Read the current port configuration. It retrieves the effective value
# from the configuration tree (handling overrides if multiple exist).
current_port = cfg.GetOptionValue("port")
print(f"Initial PostgreSQL port: {current_port}")

# ----------------------------------------------------------------------
# Demonstration of SetOptionValue (Scalar Options)
# ----------------------------------------------------------------------
# Change the maximum number of concurrent connections from default 100 to 15.
# In 'Standard' mode, this creates or updates the postgresql.auto.conf file.
cfg.SetOptionValue("max_connections", 15)

# ----------------------------------------------------------------------
# Demonstration of SetOptionValueItem (List/Array Options - Appending)
# ----------------------------------------------------------------------
# Unique append: instead of replacing 'auto_explain', this method appends
# 'pg_stat_statements' into the existing list parameter.
cfg.SetOptionValueItem("shared_preload_libraries", "pg_stat_statements")

# ----------------------------------------------------------------------
# Save and Apply Changes
# ----------------------------------------------------------------------
# Flush all modified in-memory configuration trees back to the file system
testgres_pg_conf.PostgresConfigurationWriter.WriteConfiguration(cfg)

# 3. Start the PostgreSQL server to let it pick up the new configuration
node.start()

# 4. Verify modified options via standard SQL queries
# Verify max_connections changes
res_conn = node.execute("SELECT setting FROM pg_settings WHERE name = 'max_connections';")
print(f"Configured max_connections: {res_conn}")  # Output: 15

# Verify preloaded libraries using native SHOW command.
# Output will prove that 'pg_stat_statements' was safely appended to 'auto_explain'.
res_libs = node.execute("SHOW shared_preload_libraries;")
print(f"Preloaded libraries: {res_libs}")  # Expected output: auto_explain,pg_stat_statements

# 5. Stop the process and clean up temporary node directories
node.cleanup()

Output:

Initial PostgreSQL port: 53916
Configured max_connections: 15
Preloaded libraries: auto_explain,pg_stat_statements

Authors

Postgres Professional

Metadata

Release files for testgres.postgres-configuration 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for testgres.postgres-configuration 0.6.0
File Size Uploaded Provenance Actions
testgres_postgres_configuration-0.6.0.tar.gz 52.3 kB With provenance Details for testgres_postgres_configuration-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for testgres.postgres-configuration 0.6.0
File Interpreter ABI Platform Actions
testgres_postgres_configuration-0.6.0-py3-none-any.whl Python 3 none any Details for testgres_postgres_configuration-0.6.0-py3-none-any.whl

Total release size: 122.8 kB

Release files / testgres_postgres_configuration-0.6.0.tar.gz

Download URL testgres_postgres_configuration-0.6.0.tar.gz
Size 52.3 kB
Tags Source
SHA-256 checksum
How to use checksums
9a652cf3db2e57f25db9dfbb9949e9f6d379f5e75c4ffdf185f5d67a3786f24c
BLAKE2b-256 checksum
How to use checksums
e68ace2af6d569a734b7b2ce67ffa1488b489c1a4138bc77f5a0ddf9d4914fbf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / testgres_postgres_configuration-0.6.0-py3-none-any.whl

Download URL testgres_postgres_configuration-0.6.0-py3-none-any.whl
Size 70.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
334f17dd480a82db44ce42a4dd1e0e0a2ac7fa10e31c59a32d1e6c9b2de394b3
BLAKE2b-256 checksum
How to use checksums
7b80aec36ce7d48eecb41e0054179fd44cae42e4a4c529c39b9fafca24153b19
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for testgres.postgres-configuration 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for testgres_postgres_configuration-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page