# MatrixOne for PostgreSQL
A native PostgreSQL-compatible frontend built on MatrixOne's query engine,
transactions, lockservice, and storage. PostgreSQL clients connect directly to
the MatrixOne CN process. PG and MySQL listeners share the native MO engine.
This repository preserves MatrixOne source/history and extends it with PG wire
protocol, SQL/type/catalog adaptation and native execution/transaction fixes.
Production queries run through MO `doComQuery`, its optimizer/executors and
native storage. The separate PostgreSQL 17.6 instance is a test oracle.
**Status: experimental. Full PostgreSQL compatibility and production qualification
have not passed.** The PG 15 startup/version advertisement is a client setting;
it does not certify PG 15 or PG 17 support.
## Build and run
Use the [upstream build prerequisites](README_MATRIXONE.md) (Go 1.27+ and native
CPU dependencies), then build the ordinary MatrixOne service:
```sh
make build
```
Add to the CN configuration referenced by your launch file:
```toml
[cn.frontend]
postgresql-host = "127.0.0.1"
postgresql-port = 5432
```
```sh
./mo-service -launch ./etc/launch/launch.toml
```
The default PG port is zero (disabled). Use your native MatrixOne account.
Deployment should configure TLS and access controls as documented in the
[frontend guide](docs/developer/postgresql-frontend.md).
## Implementation
- PG protocol 3.0: simple/extended queries, text/binary types, prepares, portals,
cancellation, supported cursors and transaction status.
- SQL/parser/binder/executor adaptation for common PG queries, numeric/string/
date/JSON/array semantics, windows, DML RETURNING, targeted UPSERT and catalogs.
- Native REPEATABLE READ first-query snapshots, stale-target conflict 40001,
lock-only timeout 55P03 and savepoint recovery.
- Supported SET LOCAL, RESET/RESET ALL, DISCARD ALL; ordinary-table ALTER admission
preserves native snapshot/history protection.
- Statement-scoped TN/logtail applied frontiers enforce the tested cross-connection
acknowledged-commit visibility; native child operations share that boundary.
The Go module path remains `github.com/matrixorigin/matrixone` to preserve native
internal imports. Development and builds use this repository's sources.
## Measured validation
Recorded on 2026-10-12 (Asia/Shanghai), native candidate v30, PG 17.6 reference:
| Scope | Result |
| --- | --- |
| Common SQL corpus (400 templates x 25 data variants) | 10,000 / 10,000 |
| Strict functional differential cases | 2,572 / 2,572 |
| Own six-language integration scenarios | 107 / 107 |
| Local graceful/SIGKILL recovery | 2 / 2 |
| Native snapshot/history and same-storage restore | 3 passed, 1 failed |
| Official core, original inputs/expected output | 2 / 224 |
| Official main isolation, original inputs/expected output | 1 / 119 |
The final normal-workload campaign used 64 authenticated slots. A separate
32-slot campaign denied one official startup and remains a retained failed
verdict. No failing official semantic case is waived. The 107 scenarios use
ordinary upstream adapters; they are not complete upstream project suites or
20 complete projects per language. The 10,000 statements are data variants of
400 templates, not 10,000 independent features.
Runnable clients cover Python (Django, Flask, SQLAlchemy, Alembic), Node.js
(node-postgres, TypeORM, Express, Prisma), Go (GORM, Gin), Java (Spring Boot,
Hibernate, JDBC), Ruby (Rails/ActiveRecord on JRuby), and PHP (Laravel/Eloquent).
See [client examples](test/pgwire/README.md), [functional validation](test/pgwire/functional/VALIDATION.md)
and [archived raw evidence](test/pgwire/validation/README.md).
## Remaining work
Quoted database names with whitespace/embedded quotes still fail a required
restore scenario. SERIALIZABLE/SSI, complete PG lock modes, COPY/SCRAM, full
schema/type/catalog/role/procedure/trigger/extension contracts remain incomplete.
Distributed HA/durability, clean-storage backup/PITR, rolling upgrades, capacity
and long-soak validation remain open. See the [acceptance matrix](test/pgwire/production/ACCEPTANCE.md).
Upstream CI workflow definitions are preserved in
[`.github/upstream-workflows`](.github/upstream-workflows). They include scheduled
robot notifications and upstream release/image publication. Configure this
repository's CI, notifications and release destinations before activating selected
workflows under `.github/workflows`.
## Provenance and license
Based on [matrixorigin/matrixone](https://github.com/matrixorigin/matrixone)
commit `652c643666428f1c434e03369834f2a9bead7c27`; Apache 2.0 [LICENSE](LICENSE).
Original MatrixOne READMEs are retained as [English](README_MATRIXONE.md) and
[Chinese](README_CN_MATRIXONE.md). PostgreSQL official-test output fragments retain
their [reference license](test/pgwire/validation/POSTGRESQL_REFERENCE_LICENSE.txt).
[中文说明](README_CN.md)