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, andinclude_dirdirectives. - 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
SetOptionValueItemto append items to comma-separated parameters (e.g.,shared_preload_libraries) uniquely, eliminating string-concatenation errors. - Flexible Validation Strategies (
StrictvsStandard):Standardmode mimics real-world PostgreSQL behavior where parameter overrides and duplicates are allowed ("last definition wins").Strictmode enforces single-definition invariants, throwing structured errors when accidental duplicates are detected.
- Fail-Safe Lifecycle Verification: Leverages internal
IsAlivestate validation mechanics to safeguard against modifying zombie reference nodes or processing out-of-sync cache handles. - Native
TestgresExceptionIntegration: Features a fully typed, strict hierarchy of operational errors and fatal bug checks derived directly from the coretestgresexception 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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.