Skip to content

About

PostgreSQL client for MojoπŸ”₯ β€” libpq bindings

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

3 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

mojo-postgres

PostgreSQL client for MojoπŸ”₯ β€” backed by libpq.

Talk to Postgres straight from your Mojo / MAX inference loop. No Python hop, no GIL on the hot path.

CI Release License Mojo libpq Status


Why this exists

Mojo's pitch is "Python ergonomics, systems performance, AI-native." The place that pitch meets the real world is the data layer β€” and most ML pipelines today pull features, labels, or config from Postgres.

If you want a Postgres table feeding a Mojo model today, your options are:

  1. Hop through Python with psycopg2 / psycopg β€” every row pays a Python ↔ Mojo FFI tax, plus you're back in GIL territory.
  2. Hand-roll libpq bindings yourself β€” possible, but it's a lot of opaque pointers and PGresult* lifetimes.

mojo-postgres is option 3: a Mojo-idiomatic, Pythonic API over the same libpq C foundation that every non-JVM Postgres client (Go, Rust, Python, Node, .NET) is already built on. Familiar shape, native perf, no FFI tax per row.

from postgres import Connection, ConnectionConfig

fn main() raises:
    var conn = Connection(ConnectionConfig(
        host="localhost",
        dbname="features",
        user="reader",
        password="hunter2",
    ))
    var res = conn.query("SELECT id, embedding FROM users WHERE active")
    for row in range(res.nrows()):
        run_inference(res.value(row, 1))    # straight into your Mojo / MAX model

Install

mojo-postgres depends on libpq at runtime. Recommended: let pixi handle everything.

# pixi.toml
[workspace]
channels = ["https://conda.modular.com/max", "conda-forge"]
platforms = ["linux-64", "osx-arm64"]

[dependencies]
max = "==25.7.0"
mojo = "==0.25.7.0"
libpq = ">=16.0"

Then add mojo-postgres as a Mojo dependency (vendor the package, or pull src/postgres/ into your tree β€” it's small and dependency-free on the Mojo side):

git clone https://github.com/dvirarad/mojo-postgres.git
cp -r mojo-postgres/src/postgres your_project/src/

Prefer system packages? libpq is widely available:

brew install libpq                      # macOS
sudo apt install libpq-dev              # Debian / Ubuntu
sudo dnf install libpq-devel            # Fedora

Quickstart

Query

from postgres import Connection, ConnectionConfig

fn main() raises:
    var conn = Connection(ConnectionConfig(
        host="localhost",
        dbname="postgres",
        user="postgres",
        password="postgres",
    ))
    var res = conn.query("SELECT id, name FROM users LIMIT 10")
    for row in range(res.nrows()):
        print(res.value(row, 0), res.value(row, 1))

Insert

var ins = conn.query("INSERT INTO events (name) VALUES ('signup')")
print(ins.rows_affected(), "row(s) inserted")

Inspect columns

var res = conn.query("SELECT * FROM users LIMIT 1")
for col in range(res.ncols()):
    print(res.column_name(col))

See examples/ for runnable scripts, including examples/ml_pipeline.mojo β€” a streaming feature pipeline that pulls rows from Postgres and feeds them into a tensor.

API surface (v0.1)

Symbol What it does
Connection / ConnectionConfig Open a connection, run statements, close
Result Row/column access via nrows(), ncols(), value(row, col), column_name(col), is_null(row, col), rows_affected()
PostgresError Raised with libpq status code + human description
libpq_version() Loaded libpq version (for diagnostics)

The full configuration surface mirrors libpq's conninfo parameters β€” under-the-hood, ConnectionConfig translates its typed fields into a conninfo string, so anything libpq supports is reachable.

Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  your Mojo / MAX code                               β”‚
β”‚                                                     β”‚
β”‚  from postgres import Connection, ConnectionConfig  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                     β”‚  Pythonic Mojo API
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  src/postgres/{connection,result,config}.mojo       β”‚
β”‚  typed structs, lifetime management, error mapping  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                     β”‚  external_call[...]
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  src/postgres/_ffi.mojo                             β”‚
β”‚  raw libpq symbol declarations                      β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                     β”‚  C ABI
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  libpq.so / .dylib       (PostgreSQL License)       β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

See docs/ARCHITECTURE.md for the longer write-up on FFI lifetimes and the PGconn / PGresult story.

Status

Alpha. v0.1.0 is the first public release. The FFI layer binds real libpq symbols and smoke tests pass against libpq 16+. Expect:

Use it in spikes and prototypes today. Wait for v1.0 before betting a production pipeline.

Roadmap

  • v0.2 β€” PQexecParams parameter binding, typed PostgresErrorKind, Result iterator protocol.
  • v0.3 β€” COPY FROM / COPY TO streaming, prepared statements, NOTIFY/LISTEN.
  • v0.4 β€” Connection pooling, tensor-zero-copy result accessors (UnsafePointer row views for MAX tensors).
  • v1.0 β€” API stable; feature parity with psycopg3's sync surface.

Feature requests go in the issue tracker. Comment with a πŸ‘ to vote.

Contributing

We protect main β€” contributions land via PR with passing CI and a review from a maintainer. See CONTRIBUTING.md for the full guide, but the short version is:

  1. Fork & branch.
  2. pixi install
  3. Make your change; add a test in tests/ if behavior changes.
  4. pixi run lint && pixi run test
  5. Open a PR. CI must be green.

Interesting layers if you're new:

Security issues? See SECURITY.md β€” please don't open a public issue for a CVE-shaped thing.

License

Apache 2.0 β€” see LICENSE. libpq itself is under the PostgreSQL License and is dynamically linked, not bundled or redistributed.

Acknowledgments

  • The PostgreSQL Global Development Group's libpq β€” the C client this whole project stands on.
  • psycopg β€” API shape we tried to honor.
  • The Modular team, for MojoπŸ”₯ and a C FFI that makes wrappers like this possible.

About

PostgreSQL client for MojoπŸ”₯ β€” libpq bindings

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages