Skip to content

Commit 429d207

Browse files
committed
feat: add deterministic orchestration lifecycle
1 parent ea86434 commit 429d207

14 files changed

Lines changed: 1036 additions & 149 deletions

‎README.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# pg-workload
22

3-
`pg-workload` installs, validates, prepares, runs, and schedules declarative PostgreSQL workload
4-
profiles. It is the workload component in the PostgreSQL test flow:
3+
`pg-workload` emulates PostgreSQL backend activity that produces diverse query plans, logs, and
4+
runtime statistics for diagnostic observation. It installs, validates, runs, and schedules
5+
declarative activity profiles in the PostgreSQL test flow:
56

67
```text
78
pg-stand -> pg-workload -> pg-diag report
@@ -47,8 +48,7 @@ Initialize another directory with:
4748
pg-workload init --directory /srv/pg-workload/lab
4849
```
4950

50-
The CLI can also be invoked as `python -m pg_workload`. The repository-level `workload.py` file is
51-
a source-checkout compatibility entry point and is not installed into the wheel.
51+
The CLI can also be invoked as `python -m pg_workload`.
5252

5353
### Install from source
5454

@@ -364,6 +364,12 @@ locks, dumps, archives, and CSV datasets. Canonical immutable profile sources li
364364
`src/pg_workload/bundled/` and are included in the wheel; generated table rows live only in the
365365
target PostgreSQL database.
366366

367+
## Orchestrator integration
368+
369+
The normal profile and scheduler CLI remains human-oriented. Authors of
370+
`pg_play`-compatible orchestrators can use the separate
371+
[versioned machine contract](docs/pg_play-integration.md).
372+
367373
## Development and release checks
368374

369375
```bash

‎docs/pg_play-integration.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# pg_play integration contract
2+
3+
This document is for orchestrator authors. Normal users retain the concise
4+
profile, install, run, scheduler, and lifecycle CLI described in the README.
5+
6+
`pg_workload` supports the hidden `pg_play/component/v1` machine transport:
7+
8+
```bash
9+
pg-workload --machine --request-id workload-001 --component-capabilities
10+
pg-workload --machine --request-id workload-002 validate --root workload
11+
pg-workload --machine --request-id workload-003 plan \
12+
--root workload --operation=install --profile pagila
13+
```
14+
15+
`plan` hashes every selected profile file, selected jobs, scale, connection
16+
metadata without secrets, requested database changes, and scheduler state.
17+
Mutating `prepare-db`, `install`, `run`, `scheduler`, and `start` operations can
18+
be guarded with the returned component plan hash.
19+
20+
`start`, `status`, and `stop` provide a bounded background lifecycle useful to
21+
both people and orchestrators. `stop` verifies that the recorded PID belongs
22+
to the exact project scheduler before sending a signal.
23+
24+
For an orchestrated run, the hidden `--enable-selected` option is supplied to
25+
both `plan --operation=scheduler` and `start`. The plan hashes the prospective
26+
desired state; `start` verifies that hash, writes all selected enables under
27+
one state lock, and only then launches the scheduler.
28+
29+
Passwords are accepted only through the documented environment/passfile
30+
mechanisms. They are never accepted in the machine envelope or emitted to
31+
stdout.

‎pyproject.toml‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,16 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "pg-workload"
7-
version = "0.1.0"
8-
description = "PostgreSQL workload profiles, runner, and desired-state scheduler."
7+
version = "0.2.0"
8+
description = "PostgreSQL backend activity emulator for diverse plans, logs, and runtime statistics."
99
readme = "README.md"
1010
requires-python = ">=3.10"
1111
license = "MIT"
1212
license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
1313
authors = [
1414
{ name = "O2eg", email = "oleg.ispu@yandex.ru" }
1515
]
16-
keywords = ["postgresql", "pgbench", "benchmark", "workload", "performance"]
16+
keywords = ["postgresql", "workload", "emulation", "diagnostics", "observability"]
1717
dependencies = [
1818
"PyYAML>=6.0,<7"
1919
]
@@ -27,8 +27,7 @@ classifiers = [
2727
"Programming Language :: Python :: 3.10",
2828
"Programming Language :: Python :: 3.11",
2929
"Programming Language :: Python :: 3.12",
30-
"Topic :: Database",
31-
"Topic :: System :: Benchmark"
30+
"Topic :: Database"
3231
]
3332

3433
[project.urls]
@@ -57,17 +56,18 @@ pg-workload = "pg_workload.cli:main"
5756

5857
[tool.setuptools]
5958
package-dir = {"" = "src"}
60-
include-package-data = true
59+
include-package-data = false
6160

6261
[tool.setuptools.packages.find]
6362
where = ["src"]
63+
include = ["pg_workload*"]
64+
namespaces = false
6465

6566
[tool.setuptools.package-data]
6667
pg_workload = ["bundled/**/*"]
6768

6869
[tool.pytest.ini_options]
6970
addopts = "-ra"
70-
pythonpath = ["src"]
7171
testpaths = ["tests"]
7272

7373
[tool.ruff]

‎src/pg_workload/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
"""PostgreSQL workload generation and scheduling tools."""
22

3-
__version__ = "0.1.0"
3+
__version__ = "0.2.0"
44

55
from pg_workload.assets import bundled_profiles_root, initialize_project
66
from pg_workload.cli import build_parser

0 commit comments

Comments
 (0)