We’re excited to announce one of the most impactful updates to the GuardianDB ecosystem. A fully PostgreSQL-compatible relational layer. From now on, there’s no need to choose between the robustness of the traditional SQL ecosystem and the freedom of a decentralized, peer-to-peer (P2P), local-first data model. GuardianDB now delivers the best of both worlds, seamlessly.
The biggest strength of this new layer is immediate interoperability. Standard PostgreSQL clients such as the psql terminal, libraries like node-postgres and TypeORM, or visual tools like DBeaver can connect directly to GuardianDB using the native PostgreSQL wire protocol (v3). This means you can run conventional SQL queries without changing a single line of client-specific code or installing proprietary drivers.
Inside the Architecture
Under the hood, this magic lives entirely within the guardian-db library, split into three main modules enabled via features: pgwire (handling authentication and the flow of simple or extended queries), sql (responsible for parsing, planning, and command execution), and relational (which manages types, indexes, and the catalog). The engine was designed to be fully storage-agnostic, operating through an abstraction called RelationalStorage.
Currently, there are two ways to run this gateway. The first is an in-memory version, ideal for rapid development environments and conformance testing. To start it, simply run:
cargo run --features pgwire --bin guardian-pgwire
By default, this gateway listens locally on port 15432, uses trust authentication mode (accepting any username and password), and runs without TLS encryption, making agile development easier.
The second approach, and the true heart of our vision, is the Iroh-based gateway (postgres_iroh_gateway). With this setup, every table created via TypeORM or psql is internally converted into GuardianDB document collections. Data is persisted locally and asynchronously replicated across P2P nodes using Iroh protocols, Willow range reconciliation, and LWW (Last-Writer-Wins) CRDT structures. If you run two instances on different nodes, rows written on one side will automatically converge on the other through mDNS discovery.
Seamless Integration with TypeORM and Standard Tools
To connect any tool to GuardianDB, the connection string is exactly what you already expect from the Postgres ecosystem:
postgres://guardian:guardian@127.0.0.1:15432/app?sslmode=disable
TypeORM support has been treated as an absolute priority. Advanced features such as automatic schema synchronization (synchronize: true), migration execution via QueryRunner, repository usage, query builders (QueryBuilder), and transaction management all work perfectly out of the box.
And if you want to simplify infrastructure management even further in Node.js, we provide the native driver @guardiandb/postgres-typeorm. It exposes GuardianDataSource, which automatically and embeddedly initializes the database gateway, allowing you to configure data paths and peer nodes directly from TypeScript code.
SQL Features and Concurrency Management
This is not a superficial compatibility layer. GuardianDB supports a wide range of traditional SQL features. On the data definition side (DDL), you can create and alter tables, schemas, real BTree indexes, and views. For data manipulation (DML), you have multi-row inserts, RETURNING clauses, updates, deletes, and conflict resolution strategies with ON CONFLICT DO NOTHING or DO UPDATE. Advanced queries involving joins, correlated subqueries, complex aggregations, and non-recursive common table expressions (CTEs) work accurately.
The system also includes a robust lock manager identical to PostgreSQL’s (src/sql/lock.rs). It operates at the table level (with all eight traditional modes such as ACCESS SHARE and EXCLUSIVE), at the row level (SELECT ... FOR UPDATE with support for NOWAIT and SKIP LOCKED), and even supports advisory locks. There’s also an integrated deadlock detection mechanism that aborts conflicting transactions with the standard error code 40P01.
All transactions run under the Read Committed isolation level. Any error occurring within a BEGIN ... COMMIT block immediately aborts the transaction, requiring a ROLLBACK before accepting new commands, exactly matching native PostgreSQL behavior.
Understanding Local-First Consistency and Documented Gaps
Because GuardianDB is fundamentally a local-first database, its distributed consistency model has important nuances that developers should understand. In Local-First mode (the default), transactions are atomic and isolated on the local replica. However, replication between peer nodes remains asynchronous. This means two disconnected replicas can insert the same primary key simultaneously; when the network reconnects, records converge via CRDTs, and the surviving value is exposed through the relational layer. Global uniqueness is therefore eventually consistent.
For scenarios that demand absolute strictness, Strict SQL Mode is under active development. It introduces a coordinating leader to globally order writes, allowing constraint violations to abort transactions immediately across the entire network.
Finally, it’s important to note that because this is a ground-up implementation, there are some known limitations compared to the traditional PostgreSQL engine. Features such as window functions (OVER), recursive CTEs, stored procedures (CREATE FUNCTION), triggers, and advanced full-text search are not currently supported and will return the standard error code 0A000 (feature not supported). Additionally, while foreign key constraints are parsed and visible in the catalog for introspection tools, local enforcement of cascading or restrictive actions is not yet natively implemented.
The project includes rigorous test coverage, validating everything from type encoding in the relational layer to end-to-end conformance tests with Node.js drivers. We invite you to explore the examples folder in our repository to see real-world applications running with TypeORM and start building powerful decentralized architectures without giving up the familiarity of SQL.