Metadata-Version: 2.4
Name: celerp-postgres
Version: 17.10.0
Summary: Full PostgreSQL server + client tools (pg_dump, psql, ...) as pip-installable wheels. No compilation, no system packages, no root.
License: MIT License
        
        Copyright (c) 2026 Noah Severs
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        ---
        
        The PostgreSQL binaries distributed in the platform wheels of this package are
        NOT covered by the license above. They are distributed under the PostgreSQL
        License; their COPYRIGHT and upstream LICENSE notices are included inside the
        package at celerp_postgres/pginstall/.
        
Project-URL: Repository, https://github.com/celerp/celerp-postgres
Project-URL: Upstream binaries, https://github.com/theseus-rs/postgresql-binaries
Keywords: postgresql,postgres,embedded,database,binaries,pg_dump,self-contained,portable
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# celerp-postgres

**PostgreSQL, pip installable.** A full PostgreSQL distribution — the server *and* the
client tools — delivered as a platform wheel. No apt/brew/installer, no Docker, no root,
no compilation.

```bash
pip install celerp-postgres
```

That's the whole setup. You get unmodified PostgreSQL binaries on disk and a
three-function API that tells you where they are. What you run with them is up to you.

## Quickstart

Spin up a real PostgreSQL 17 database in a few lines — no drivers required beyond
whatever you already use to talk to Postgres:

```python
import subprocess, tempfile
from celerp_postgres import tool

data = tempfile.mkdtemp()

# One-time cluster init (no password prompts: local trust auth; libc collation
# keeps the package fully self-contained — ICU remains available per-collation)
subprocess.run([tool("initdb"), "-D", data, "-U", "postgres", "-A", "trust",
                "--locale-provider=libc"], check=True)

# Start on localhost:54321
subprocess.run([tool("pg_ctl"), "-D", data, "-w",
                "-o", "-c listen_addresses=127.0.0.1 -c port=54321",
                "-l", f"{data}/log", "start"], check=True)

# ... connect with psycopg / asyncpg / SQLAlchemy / anything:
#     postgresql://postgres@127.0.0.1:54321/postgres

subprocess.run([tool("pg_ctl"), "-D", data, "-w", "stop"], check=True)
```

On Linux/macOS you can skip TCP entirely and listen on a unix socket
(`-c listen_addresses='' -c unix_socket_directories=<dir>`), which keeps the database
invisible to the network.

## What's in the box

Every wheel contains the complete distribution for its platform:

| | |
|---|---|
| **Server** | `postgres`, `initdb`, `pg_ctl` |
| **Client tools** | `psql`, `pg_dump`, `pg_restore`, `pg_basebackup`, `createdb`, … |
| **Runtime** | `lib/` (shared libraries), `share/` (initdb templates, timezone data) |
| **Licenses** | PostgreSQL `COPYRIGHT` + upstream `LICENSE`, inside the package |

C headers (`include/`) are not shipped — this package runs PostgreSQL; it isn't a
build-against-libpq SDK.

### Supported platforms

| Wheel | Platform |
|---|---|
| `manylinux_2_34_x86_64` / `_aarch64` | Linux (glibc 2.34+) |
| `musllinux_1_2_x86_64` / `_aarch64` | Alpine / musl Linux |
| `macosx_26_0_x86_64`, `macosx_26_0_arm64` | macOS 26+ (upstream binaries target current macOS) |
| `win_amd64` | Windows x64 |

Any CPython ≥ 3.9. Wheels only — there is deliberately no sdist, because a source
install could not contain the binaries and would silently produce a broken package.

Every wheel is fully self-contained: the required shared libraries (openssl, icu,
libxml2, compression codecs, …) ship inside the package, so it works on minimal images
like `python:slim` and `python:alpine` with no system packages. A few niche server
extensions that would drag in huge or host-specific dependencies (`plpython3u`,
JIT/`llvmjit`, `uuid-ossp`, `xml2`) are not included.

## API

Three symbols; that's the entire surface:

```python
from celerp_postgres import POSTGRES_VERSION, bin_dir, tool, icu_data_dir

POSTGRES_VERSION   # "17.10.0" — the bundled PostgreSQL version (== package version)
bin_dir()          # ".../site-packages/celerp_postgres/pginstall/bin"
tool("pg_dump")    # full path to a tool; raises FileNotFoundError if absent
icu_data_dir()     # musl wheels only: set ICU_DATA to this when spawning the
                   # server (Alpine's ICU reads data from an external file);
                   # None on every other platform
```

No lifecycle magic, no hidden daemons, no atexit hooks. You own the process — which is
exactly what makes this composable with whatever supervisor, test fixture, or app
framework you already have.

## Why you'd want this

- **Test suites** that need a real PostgreSQL without Docker, CI services, or a
  system install — `pip install`, boot per-session, throw away.
- **Local-first / desktop apps** that embed a private database next to the app's data
  directory instead of asking users to install a server.
- **CLI tools and data scripts** that need `pg_dump`/`pg_restore`/`psql` at a known,
  version-pinned path regardless of what the host has on `PATH`.
- **Air-gapped and locked-down environments** — everything arrives through pip's
  normal, hash-verifiable channel; nothing is downloaded at runtime.
- **Teaching, notebooks, demos** — a real database with zero setup instructions.

## Versioning & updates

The package version **is** the PostgreSQL version (`17.10.0` ships PostgreSQL 17.10).
New PostgreSQL point releases are published as new package versions shortly after the
upstream release train; pin `>=17.10,<18` to receive security patches within the major
you initialized your data directory with. Repackaging-only fixes use post releases
(`17.10.0.post1`). PostgreSQL major upgrades change the on-disk `pgdata` format —
moving 17 → 18 requires a `pg_dump`/`pg_restore` migration, as with any PostgreSQL
installation.

## How it's built (and why you can trust it)

Wheels repackage the excellent
[theseus-rs/postgresql-binaries](https://github.com/theseus-rs/postgresql-binaries)
release archives — the same binary source used across the Rust embedded-postgres
ecosystem. Every archive's sha256 is **pinned in this repository** and verified at
build time (never trusted from a live sidecar), the binaries are shipped unmodified,
and every release is gated on CI that boots a real cluster on each platform and runs a
`pg_dump` → `pg_restore` roundtrip before anything reaches PyPI. Publishing uses PyPI
trusted publishing (OIDC) — no long-lived credentials exist.

## License

- **Package code** (accessor module + build tooling): [MIT](LICENSE).
- **PostgreSQL binaries**: [PostgreSQL License](https://www.postgresql.org/about/licence/)
  — permissive, OSI-approved; the `COPYRIGHT` and upstream `LICENSE` notices ship inside
  the package at `celerp_postgres/pginstall/`.

Credits: the [PostgreSQL Global Development Group](https://www.postgresql.org/), and
[theseus-rs](https://github.com/theseus-rs/postgresql-binaries) for the portable builds.

---

Maintained by the [Celerp](https://github.com/celerp) team.
