testgres-exts.pglab 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,18 @@
1
+ Copyright (c) 2026, PgLab contributors
2
+
3
+ Permission to use, copy, modify, and distribute this software and its
4
+ documentation for any purpose, without fee, and without a written agreement is
5
+ hereby granted, provided that the above copyright notice and this paragraph and
6
+ the following two paragraphs appear in all copies.
7
+
8
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE TO ANY PARTY FOR
9
+ DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST
10
+ PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
11
+ THE AUTHORS OR COPYRIGHT HOLDERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH
12
+ DAMAGE.
13
+
14
+ THE AUTHORS AND COPYRIGHT HOLDERS SPECIFICALLY DISCLAIM ANY WARRANTIES,
15
+ INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16
+ FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS
17
+ IS" BASIS, AND THE AUTHORS AND COPYRIGHT HOLDERS HAVE NO OBLIGATIONS TO PROVIDE
18
+ MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
@@ -0,0 +1,217 @@
1
+ Metadata-Version: 2.4
2
+ Name: testgres_exts.pglab
3
+ Version: 0.1.0
4
+ Summary: Linux netns/cgroup/netem fault injection for PostgreSQL tests using Testgres
5
+ License-Expression: PostgreSQL
6
+ Classifier: Development Status :: 3 - Alpha
7
+ Classifier: Intended Audience :: Developers
8
+ Classifier: Operating System :: POSIX :: Linux
9
+ Classifier: Programming Language :: Python :: 3 :: Only
10
+ Classifier: Programming Language :: Python :: 3.8
11
+ Classifier: Programming Language :: Python :: 3.9
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: 3.14
17
+ Classifier: Topic :: Software Development :: Testing
18
+ Classifier: Topic :: Database
19
+ Requires-Python: >=3.8
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: testgres<1.18,>=1.17
23
+ Provides-Extra: test
24
+ Requires-Dist: pytest<10,>=8; extra == "test"
25
+ Dynamic: license-file
26
+
27
+ [![CI Status](https://img.shields.io/github/actions/workflow/status/postgrespro/testgres_exts.pglab/.github/workflows/ci.yml?label=CI)](https://github.com/postgrespro/testgres_exts.pglab/actions/workflows/ci.yml)
28
+ [![PyPI package version](https://badge.fury.io/py/testgres_exts_pglab.svg)](https://badge.fury.io/py/testgres_exts.pglab)
29
+ [![PyPI python versions](https://img.shields.io/pypi/pyversions/testgres_exts_pglab)](https://pypi.org/project/testgres-exts.pglab)
30
+
31
+ # PgLab
32
+
33
+ PgLab is a Linux fault-injection layer for PostgreSQL tests built on top of
34
+ [Testgres](https://github.com/postgrespro/testgres).
35
+
36
+ Testgres owns PostgreSQL lifecycle, SQL access, backups and physical replication.
37
+ PgLab owns Linux isolation and faults:
38
+
39
+ - network namespaces, veth pairs and a bridge;
40
+ - cgroup v1/v2 I/O throttling;
41
+ - network partitions;
42
+ - `tc netem` delay, jitter, loss, duplication, corruption, reordering and rate limits;
43
+ - freeze/unfreeze of a PostgreSQL process group;
44
+ - cleanup of namespaces, cgroups, qdiscs and temporary firewall rules.
45
+
46
+ PgLab currently requires Linux and root privileges because it creates network
47
+ namespaces, interfaces and cgroups. PostgreSQL itself runs as a configurable
48
+ unprivileged Unix account.
49
+
50
+ ## Why this needed changes in Testgres
51
+
52
+ Each PgLab node has a different `OsOperations` execution context: PostgreSQL
53
+ commands for a replica must run inside that replica's network namespace, and
54
+ server-starting commands must also enter its cgroup. A replica therefore cannot
55
+ simply inherit the primary node's `os_ops`, host and port-management context.
56
+
57
+ The Testgres target execution-context API lets PgLab keep the proper separation
58
+ of responsibilities: Testgres still owns `pg_basebackup`, physical replication
59
+ and `PostgresNode` lifecycle; PgLab only supplies the target execution context
60
+ and Linux fault injection.
61
+
62
+ See [docs/why-testgres-execution-context.md](docs/why-testgres-execution-context.md)
63
+ for the concrete primary/replica flow and the reason behind the upstream
64
+ Testgres changes.
65
+
66
+ ## Testgres compatibility
67
+
68
+ PgLab uses the target execution-context API in current Testgres:
69
+
70
+ ```python
71
+ primary.replicate(
72
+ target_os_ops=replica_ops,
73
+ target_host=replica_ip,
74
+ target_port=5432,
75
+ )
76
+ ```
77
+
78
+ The compatible Testgres tree must provide:
79
+
80
+ - `PostgresNode.replicate(target_os_ops=..., target_host=..., target_port=...)`;
81
+ - `NodeBackup(..., os_ops=...)`, so `pg_basebackup` can run in the target context;
82
+ - target execution-context support in node cloning.
83
+
84
+ The current development target is Testgres 1.17.0 with that API. Until those
85
+ changes are present in a released Testgres build, install Testgres from the
86
+ compatible checkout and install PgLab editable beside it.
87
+
88
+ ## Development install
89
+
90
+ With a compatible Testgres checkout in `../testgres`:
91
+
92
+ ```bash
93
+ ./setup.sh --testgres-dir ../testgres
94
+ ```
95
+
96
+ Or manually:
97
+
98
+ ```bash
99
+ python3 -m venv .venv
100
+ .venv/bin/python -m pip install -U pip setuptools wheel
101
+ .venv/bin/python -m pip install -e ../testgres
102
+ .venv/bin/python -m pip install -e '.[test]'
103
+ .venv/bin/python tools/verify_install.py
104
+ ```
105
+
106
+ When the required Testgres API is available from PyPI, a normal editable install
107
+ is enough:
108
+
109
+ ```bash
110
+ python3 -m venv .venv
111
+ .venv/bin/python -m pip install -e '.[test]'
112
+ ```
113
+
114
+ No `setup.py` is required. Packaging metadata lives in `pyproject.toml`.
115
+
116
+ ## PostgreSQL environment
117
+
118
+ Point PgLab at the PostgreSQL build you want to test:
119
+
120
+ ```bash
121
+ export PG_BIN=/home/user/build/postgres/bin
122
+ export PGLAB_OS_USER=user
123
+ export PGLAB_DB_USER=postgres
124
+ export PGLAB_TEST_ROOT=/var/tmp
125
+ ```
126
+
127
+ `PGLAB_TEST_ROOT` should live on a block-backed filesystem for cgroup I/O tests.
128
+ A tmpfs or overlay filesystem is fine for networking-only tests but cannot be
129
+ mapped reliably to a block device for `io.max`/blkio throttling.
130
+
131
+ Check the host:
132
+
133
+ ```bash
134
+ ./scripts/doctor.sh
135
+ ```
136
+
137
+ ## Example
138
+
139
+ ```python
140
+ from pglab import PgLab
141
+
142
+ with PgLab(
143
+ pg_bin="/home/user/build/postgres/bin",
144
+ base_dir="/var/tmp/pglab-demo",
145
+ subnet="10.203.0.0/24",
146
+ os_user="user",
147
+ db_superuser="postgres",
148
+ ) as lab:
149
+ primary = lab.create_primary("p1", "10.203.0.10", port=5432)
150
+ primary.init().start()
151
+
152
+ replica = lab.create_replica("p1", "r1", "10.203.0.11", port=5432)
153
+ replica.start()
154
+ replica.catchup()
155
+
156
+ replica.netem(delay_ms=100, loss_pct=1)
157
+ replica.clear_netem()
158
+
159
+ lab.partition("p1", "r1")
160
+ lab.heal_partition("p1", "r1")
161
+
162
+ replica.freeze()
163
+ replica.unfreeze()
164
+ ```
165
+
166
+ The same TCP port may be used by several nodes because each PostgreSQL server
167
+ runs in its own network namespace. PgLab disables Unix-domain PostgreSQL
168
+ sockets to avoid collisions in the shared mount namespace.
169
+
170
+ ## Tests
171
+
172
+ Smoke test:
173
+
174
+ ```bash
175
+ ./scripts/run-smoke.sh
176
+ ```
177
+
178
+ Full integration suite:
179
+
180
+ ```bash
181
+ ./scripts/run-tests.sh
182
+ ```
183
+
184
+ One file or test can be selected normally:
185
+
186
+ ```bash
187
+ ./scripts/run-tests.sh tests/test_pglab_netem_effects.py
188
+ ```
189
+
190
+ The integration suite covers primary/replica lifecycle, same-port replicas,
191
+ partitions and recovery, cgroup I/O controls, cleanup after failures, netem
192
+ latency/loss/rate effects, freeze/unfreeze, replication lag and an unrecoverable
193
+ WAL-gap scenario.
194
+
195
+ ## Project layout
196
+
197
+ ```text
198
+ pglab.py PgLab implementation
199
+ pyproject.toml Python package metadata
200
+ example.py small usage example
201
+ smoke.py end-to-end smoke test
202
+ tests/ integration and compatibility tests
203
+ scripts/doctor.sh environment diagnostics
204
+ scripts/run-tests.sh privileged test runner
205
+ scripts/run-smoke.sh privileged smoke runner
206
+ scripts/install-system-deps.sh host package helper
207
+ tools/verify_install.py Testgres API compatibility check
208
+ docs/why-testgres-execution-context.md
209
+ rationale for the Testgres target-context API
210
+ ```
211
+
212
+ PgLab is still experimental. The public API and packaging may change while the
213
+ corresponding Testgres execution-context API is being reviewed upstream.
214
+
215
+ ## License
216
+
217
+ PgLab is distributed under the PostgreSQL License. See [`LICENSE`](LICENSE).
@@ -0,0 +1,191 @@
1
+ [![CI Status](https://img.shields.io/github/actions/workflow/status/postgrespro/testgres_exts.pglab/.github/workflows/ci.yml?label=CI)](https://github.com/postgrespro/testgres_exts.pglab/actions/workflows/ci.yml)
2
+ [![PyPI package version](https://badge.fury.io/py/testgres_exts_pglab.svg)](https://badge.fury.io/py/testgres_exts.pglab)
3
+ [![PyPI python versions](https://img.shields.io/pypi/pyversions/testgres_exts_pglab)](https://pypi.org/project/testgres-exts.pglab)
4
+
5
+ # PgLab
6
+
7
+ PgLab is a Linux fault-injection layer for PostgreSQL tests built on top of
8
+ [Testgres](https://github.com/postgrespro/testgres).
9
+
10
+ Testgres owns PostgreSQL lifecycle, SQL access, backups and physical replication.
11
+ PgLab owns Linux isolation and faults:
12
+
13
+ - network namespaces, veth pairs and a bridge;
14
+ - cgroup v1/v2 I/O throttling;
15
+ - network partitions;
16
+ - `tc netem` delay, jitter, loss, duplication, corruption, reordering and rate limits;
17
+ - freeze/unfreeze of a PostgreSQL process group;
18
+ - cleanup of namespaces, cgroups, qdiscs and temporary firewall rules.
19
+
20
+ PgLab currently requires Linux and root privileges because it creates network
21
+ namespaces, interfaces and cgroups. PostgreSQL itself runs as a configurable
22
+ unprivileged Unix account.
23
+
24
+ ## Why this needed changes in Testgres
25
+
26
+ Each PgLab node has a different `OsOperations` execution context: PostgreSQL
27
+ commands for a replica must run inside that replica's network namespace, and
28
+ server-starting commands must also enter its cgroup. A replica therefore cannot
29
+ simply inherit the primary node's `os_ops`, host and port-management context.
30
+
31
+ The Testgres target execution-context API lets PgLab keep the proper separation
32
+ of responsibilities: Testgres still owns `pg_basebackup`, physical replication
33
+ and `PostgresNode` lifecycle; PgLab only supplies the target execution context
34
+ and Linux fault injection.
35
+
36
+ See [docs/why-testgres-execution-context.md](docs/why-testgres-execution-context.md)
37
+ for the concrete primary/replica flow and the reason behind the upstream
38
+ Testgres changes.
39
+
40
+ ## Testgres compatibility
41
+
42
+ PgLab uses the target execution-context API in current Testgres:
43
+
44
+ ```python
45
+ primary.replicate(
46
+ target_os_ops=replica_ops,
47
+ target_host=replica_ip,
48
+ target_port=5432,
49
+ )
50
+ ```
51
+
52
+ The compatible Testgres tree must provide:
53
+
54
+ - `PostgresNode.replicate(target_os_ops=..., target_host=..., target_port=...)`;
55
+ - `NodeBackup(..., os_ops=...)`, so `pg_basebackup` can run in the target context;
56
+ - target execution-context support in node cloning.
57
+
58
+ The current development target is Testgres 1.17.0 with that API. Until those
59
+ changes are present in a released Testgres build, install Testgres from the
60
+ compatible checkout and install PgLab editable beside it.
61
+
62
+ ## Development install
63
+
64
+ With a compatible Testgres checkout in `../testgres`:
65
+
66
+ ```bash
67
+ ./setup.sh --testgres-dir ../testgres
68
+ ```
69
+
70
+ Or manually:
71
+
72
+ ```bash
73
+ python3 -m venv .venv
74
+ .venv/bin/python -m pip install -U pip setuptools wheel
75
+ .venv/bin/python -m pip install -e ../testgres
76
+ .venv/bin/python -m pip install -e '.[test]'
77
+ .venv/bin/python tools/verify_install.py
78
+ ```
79
+
80
+ When the required Testgres API is available from PyPI, a normal editable install
81
+ is enough:
82
+
83
+ ```bash
84
+ python3 -m venv .venv
85
+ .venv/bin/python -m pip install -e '.[test]'
86
+ ```
87
+
88
+ No `setup.py` is required. Packaging metadata lives in `pyproject.toml`.
89
+
90
+ ## PostgreSQL environment
91
+
92
+ Point PgLab at the PostgreSQL build you want to test:
93
+
94
+ ```bash
95
+ export PG_BIN=/home/user/build/postgres/bin
96
+ export PGLAB_OS_USER=user
97
+ export PGLAB_DB_USER=postgres
98
+ export PGLAB_TEST_ROOT=/var/tmp
99
+ ```
100
+
101
+ `PGLAB_TEST_ROOT` should live on a block-backed filesystem for cgroup I/O tests.
102
+ A tmpfs or overlay filesystem is fine for networking-only tests but cannot be
103
+ mapped reliably to a block device for `io.max`/blkio throttling.
104
+
105
+ Check the host:
106
+
107
+ ```bash
108
+ ./scripts/doctor.sh
109
+ ```
110
+
111
+ ## Example
112
+
113
+ ```python
114
+ from pglab import PgLab
115
+
116
+ with PgLab(
117
+ pg_bin="/home/user/build/postgres/bin",
118
+ base_dir="/var/tmp/pglab-demo",
119
+ subnet="10.203.0.0/24",
120
+ os_user="user",
121
+ db_superuser="postgres",
122
+ ) as lab:
123
+ primary = lab.create_primary("p1", "10.203.0.10", port=5432)
124
+ primary.init().start()
125
+
126
+ replica = lab.create_replica("p1", "r1", "10.203.0.11", port=5432)
127
+ replica.start()
128
+ replica.catchup()
129
+
130
+ replica.netem(delay_ms=100, loss_pct=1)
131
+ replica.clear_netem()
132
+
133
+ lab.partition("p1", "r1")
134
+ lab.heal_partition("p1", "r1")
135
+
136
+ replica.freeze()
137
+ replica.unfreeze()
138
+ ```
139
+
140
+ The same TCP port may be used by several nodes because each PostgreSQL server
141
+ runs in its own network namespace. PgLab disables Unix-domain PostgreSQL
142
+ sockets to avoid collisions in the shared mount namespace.
143
+
144
+ ## Tests
145
+
146
+ Smoke test:
147
+
148
+ ```bash
149
+ ./scripts/run-smoke.sh
150
+ ```
151
+
152
+ Full integration suite:
153
+
154
+ ```bash
155
+ ./scripts/run-tests.sh
156
+ ```
157
+
158
+ One file or test can be selected normally:
159
+
160
+ ```bash
161
+ ./scripts/run-tests.sh tests/test_pglab_netem_effects.py
162
+ ```
163
+
164
+ The integration suite covers primary/replica lifecycle, same-port replicas,
165
+ partitions and recovery, cgroup I/O controls, cleanup after failures, netem
166
+ latency/loss/rate effects, freeze/unfreeze, replication lag and an unrecoverable
167
+ WAL-gap scenario.
168
+
169
+ ## Project layout
170
+
171
+ ```text
172
+ pglab.py PgLab implementation
173
+ pyproject.toml Python package metadata
174
+ example.py small usage example
175
+ smoke.py end-to-end smoke test
176
+ tests/ integration and compatibility tests
177
+ scripts/doctor.sh environment diagnostics
178
+ scripts/run-tests.sh privileged test runner
179
+ scripts/run-smoke.sh privileged smoke runner
180
+ scripts/install-system-deps.sh host package helper
181
+ tools/verify_install.py Testgres API compatibility check
182
+ docs/why-testgres-execution-context.md
183
+ rationale for the Testgres target-context API
184
+ ```
185
+
186
+ PgLab is still experimental. The public API and packaging may change while the
187
+ corresponding Testgres execution-context API is being reviewed upstream.
188
+
189
+ ## License
190
+
191
+ PgLab is distributed under the PostgreSQL License. See [`LICENSE`](LICENSE).
@@ -0,0 +1,51 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [tool.setuptools.package-dir]
6
+ "testgres_exts.pglab" = "src"
7
+
8
+ [tool.setuptools.dynamic]
9
+ version = {attr = "testgres_exts.pglab.__version__"}
10
+
11
+ [project]
12
+ name = "testgres_exts.pglab"
13
+ dynamic = ["version"]
14
+ description = "Linux netns/cgroup/netem fault injection for PostgreSQL tests using Testgres"
15
+ readme = "README.md"
16
+ requires-python = ">=3.8"
17
+ license = "PostgreSQL"
18
+ dependencies = [
19
+ "testgres>=1.17,<1.18",
20
+ ]
21
+ classifiers = [
22
+ "Development Status :: 3 - Alpha",
23
+ "Intended Audience :: Developers",
24
+ "Operating System :: POSIX :: Linux",
25
+ "Programming Language :: Python :: 3 :: Only",
26
+ "Programming Language :: Python :: 3.8",
27
+ "Programming Language :: Python :: 3.9",
28
+ "Programming Language :: Python :: 3.10",
29
+ "Programming Language :: Python :: 3.11",
30
+ "Programming Language :: Python :: 3.12",
31
+ "Programming Language :: Python :: 3.13",
32
+ "Programming Language :: Python :: 3.14",
33
+ "Topic :: Software Development :: Testing",
34
+ "Topic :: Database",
35
+ ]
36
+
37
+ [project.optional-dependencies]
38
+ test = [
39
+ "pytest>=8,<10",
40
+ ]
41
+
42
+ [tool.flake8]
43
+ extend-ignore = ["E501"]
44
+ exclude = [".git", "__pycache__", "env", "venv"]
45
+
46
+ # Pytest settings
47
+ [tool.pytest.ini_options]
48
+ testpaths = ["tests"]
49
+ log_file_level = "NOTSET"
50
+ log_file_format = "%(levelname)8s [%(asctime)s] %(message)s"
51
+ log_file_date_format = "%Y-%m-%d %H:%M:%S"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+