Metadata-Version: 2.4
Name: postgamma
Version: 0.1.0a1
Summary: PostgreSQL embedded directly in a Python process
Requires-Python: >=3.10
Author: PostGamma contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://postgamma.com
Description-Content-Type: text/markdown
Keywords: embedded,database,postgresql
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: C
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Typing :: Typed
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES
License-File: LICENSE.postgresql
License-File: LICENSE.pgvector

# PostGamma

[postgamma.com](https://postgamma.com)

PostGamma embeds PostgreSQL 19 directly inside a CPython process. It starts no
database server process, opens no network socket, and exposes ordinary Python
`Database` and `Connection` objects backed by a thread-safe in-process kernel.
The wheel contains one CPython extension with the PostGamma kernel linked into
it statically; it does not ship or load a separate `libpostgamma.so`.

The [complete documentation](https://postgamma.com/) is also available under
`docs/` in the source checkout.

Once this alpha is published, install it from PyPI:

```console
python -m pip install "postgamma==0.1.0a1"
```

```python
import postgamma

cluster = "agent.pgm"

with postgamma.connect(cluster, autocommit=True) as connection:
    connection.execute(
        "create table if not exists memory("
        "id bigint primary key, body jsonb not null)"
    )
    connection.execute(
        "insert into memory values ($1, $2) "
        "on conflict (id) do update set body = excluded.body",
        [1, {"kind": "plan", "score": 0.98}],
    )
    print(connection.execute("select * from memory").fetchall())
```

The first argument may be a string or any `os.PathLike` object. It names a
PostgreSQL cluster directory, not a DSN or SQL database name. The default
`OPEN_OR_CREATE` mode initializes a missing PostgreSQL 19 cluster and opens an
existing compatible one without replacing data. PostGamma creates the final
cluster directory; only its parent must already exist. The initial SQL database
is `postgres` and the initial role is `postgamma`.

Use `OPEN_EXISTING` when an absent or misspelled production path must fail:

```python
with postgamma.connect(
    "agent.pgm", mode=postgamma.OpenMode.OPEN_EXISTING
) as connection:
    print(connection.execute("select current_database()").fetchone())
```

Repeated top-level calls for the same canonical path share one process-local
embedded instance and return independent sessions. The last connection closes
that implicit instance. Use `Database` when you want explicit ownership,
management operations, or an instance event stream.

The package includes DB-API 2.0 compatibility, synchronous and caller-driven
`asyncio` APIs, bounded row and COPY streaming, prepared statements, routed
events, logical dump and restore, management operations, and Arrow C Data
export. Separate connections can execute concurrently without holding the GIL.

Use DB-API 2.0 when an existing framework expects it:

```python
import postgamma

connection = postgamma.connect("agent.pgm")
try:
    cursor = connection.cursor()
    cursor.execute("select :1::int + :2::int", [20, 22])
    print(cursor.fetchone())
finally:
    connection.close()
```

Use the native asyncio facade for event-loop applications. Query progress is
driven by native waitables and does not dedicate one Python helper thread per
request.

This alpha targets Linux x86-64 with glibc 2.17 or newer and CPython 3.10
through 3.14. It embeds PostgreSQL 19 only. A materialized result is limited to
16 MiB by default and one value to 8 MiB; use row streaming or COPY for larger
workloads. Inherited database handles fail closed after `fork()`: open lazily
after the fork or call `Database.close_before_fork()` first.

This release provides the embedded PostgreSQL kernel, its public Python
adapters, and bundled pgvector 0.8.6. Enable vector types and indexes once per
logical database with `CREATE EXTENSION vector`; no separate native library is
loaded.
