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.
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:
- Hop through Python with
psycopg2/psycopgβ every row pays a Python β Mojo FFI tax, plus you're back in GIL territory. - Hand-roll
libpqbindings yourself β possible, but it's a lot of opaque pointers andPGresult*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 modelmojo-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 # Fedorafrom 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))var ins = conn.query("INSERT INTO events (name) VALUES ('signup')")
print(ins.rows_affected(), "row(s) inserted")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.
| 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.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 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.
Alpha. v0.1.0 is the first public release. The FFI layer binds real libpq symbols and smoke tests pass against libpq 16+. Expect:
- API shape may still shift in
v0.2. - A few rough edges are tracked as
good first issueβ including parameterized queries viaPQexecParams, a typedPostgresErrorKind,COPYstreaming, and connection pooling.
Use it in spikes and prototypes today. Wait for v1.0 before betting a production pipeline.
- v0.2 β
PQexecParamsparameter binding, typedPostgresErrorKind,Resultiterator protocol. - v0.3 β
COPY FROM/COPY TOstreaming, prepared statements,NOTIFY/LISTEN. - v0.4 β Connection pooling, tensor-zero-copy result accessors (
UnsafePointerrow 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.
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:
- Fork & branch.
pixi install- Make your change; add a test in
tests/if behavior changes. pixi run lint && pixi run test- Open a PR. CI must be green.
Interesting layers if you're new:
src/postgres/_ffi.mojoβ rawlibpqsymbol declarations.src/postgres/config.mojoβ typed config builder over libpq conninfo strings.src/postgres/{connection,result}.mojoβ public API.
Security issues? See SECURITY.md β please don't open a public issue for a CVE-shaped thing.
Apache 2.0 β see LICENSE. libpq itself is under the PostgreSQL License and is dynamically linked, not bundled or redistributed.