访问官网
Github
文档
Pongo
Pongo - 基于PostgreSQL的Mongo，具有强一致性优势。
入门
将Pongo安装为npm模块并保存到package.json中：
npm install @event-driven-io/pongo
也可以阅读我博客上的介绍文章以获取更多背景信息。
示例
你可以使用Pongo语法，并明确支持的语法类型：
import { pongoClient } from "@event-driven-io/pongo";
import { v4 as uuid } from "uuid";
type User = { name: string; age: number };
const connectionString =
"postgresql://dbuser:secretpassword@database.server.com:3211/mydb";
const pongo = pongoClient(connectionString);
const pongoDb = pongo.db();
const users = pongoDb.collection<User>("users");
const roger = { name: "Roger", age: 30 };
const anita = { name: "Anita", age: 25 };
const cruella = { _id: uuid(), name: "Cruella", age: 40 };
// 插入
await users.insertOne(roger);
await users.insertOne(cruella);
const { insertedId } = await users.insertOne(anita);
const anitaId = insertedId;
// 更新
await users.updateOne({ _id: anitaId }, { $set: { age: 31 } });
// 删除
await users.deleteOne({ _id: cruella._id });
// 通过Id查找
const anitaFromDb = await users.findOne({ _id: anitaId });
// 查找多个
const usersFromDb = await users.find({ age: { $lt: 40 } });
或者使用兼容MongoDB的封装：
import { MongoClient } from "@event-driven-io/pongo/shim";
import { v4 as uuid } from "uuid";
type User = { name: string; age: number };
const connectionString =
"postgresql://dbuser:secretpassword@database.server.com:3211/mydb";
const pongoClient = new MongoClient(postgresConnectionString);
const pongoDb = pongoClient.db();
const users = pongoDb.collection<User>("users");
const roger = { name: "Roger", age: 30 };
const anita = { name: "Anita", age: 25 };
const cruella = { _id: uuid(), name: "Cruella", age: 40 };
// 插入
await users.insertOne(roger);
await users.insertOne(cruella);
const { insertedId } = await users.insertOne(anita);
const anitaId = insertedId;
// 更新
await users.updateOne({ _id: anitaId }, { $set: { age: 31 } });
// 删除
await users.deleteOne({ _id: cruella._id });
// 通过Id查找
const anitaFromDb = await users.findOne({ _id: anitaId });
// 查找多个
const usersFromDb = await users.find({ age: { $lt: 40 } }).toArray();
工作原理
Pongo将PostgreSQL作为文档数据库，利用JSONB支持。 与传统JSON类型的纯文本存储不同，JSONB以二进制格式存储JSON数据。这一简单的变化在性能和存储效率方面带来了显著的优势。
Pongo使用以下表结构来存储集合：
CREATE TABLE IF NOT EXISTS "YourCollectionName" (
_id TEXT PRIMARY KEY,
data JSONB NOT NULL,
metadata JSONB NOT NULL DEFAULT '{}',
_version BIGINT NOT NULL DEFAULT 1,
_partition TEXT NOT NULL DEFAULT 'png_global',
_archived BOOLEAN NOT NULL DEFAULT FALSE,
_created TIMESTAMPTZ NOT NULL DEFAULT now(),
_updated TIMESTAMPTZ NOT NULL DEFAULT now()
)
本质上，Pongo接受MongoDB API并将其转换为原生PostgreSQL查询。 这与Marten、FerretDB和AWS DocumentDB的概念类似。
例如，MongoDB更新语法：
const users = pongoDb.collection<User>("users");
await users.updateOne({ _id: someId }, { $push: { tags: "character" } });
将被转换为：
UPDATE "users"
SET data = jsonb_set(data, '{tags}', (COALESCE(data->'tags', '[]'::jsonb) || to_jsonb('character')))
WHERE _id = '137ef052-e41c-428b-b606-1c8070a47eda';
或者查询：
const result = await users
.find({ "address.history": { $elemMatch: { street: "Elm St" } } })
.toArray();
将生成：
SELECT data
FROM "users"
WHERE jsonb_path_exists(
data,
'$.address.history[*] ? (@.street == "Elm St")'
);
为什么选择Pongo？
MongoDB是一个不错的数据库，但在ACID合规性和许可方面存在问题，这可能会给项目场景和组织政策带来困难。
Pongo带来了PostgreSQL的变形能力，以：
- 通过使用经过实战检验且广泛使用的PostgreSQL ACID兼容数据库，获得强一致性的好处，
- 使用PostgreSQL更容易与系统的其他部分集成，
- 使用兼容的API复用你的MongoDB肌肉记忆。这将允许更容易地迁移现有项目，
- 减少样板代码，比传统关系表更容易管理嵌套数据，
- 比编写原生PostgreSQL JSON查询更容易操作。它们功能强大但不是最易用的，
- 通过JSONB索引功能获得性能提升，
- 受益于PostgreSQL的高级功能，如分区、逻辑复制和其他PostgreSQL超能力
- 与云RDS和CockroachDB、Supabase、Vercel Postgres等解决方案无缝集成。
存储
PostgreSQL JSONB的二进制格式意味着数据是预解析的，允许比基于文本的JSON更快的读写操作。 每次查询数据时无需重新解析，这节省了处理时间并提高了整体性能。此外，JSONB支持高级索引选项，如GIN和GiST索引，使JSONB文档内的搜索更快、更高效。
此外，JSONB保留了存储半结构化数据的灵活性，同时允许你使用PostgreSQL强大的查询功能。你可以对JSONB数据执行复杂查询、连接和事务，就像对常规关系数据一样。
与普遍认知相反，JSON文档数据是结构化的。 JSON有结构，但每个文档并不强制执行。我们可以通过添加新字段轻松扩展文档的架构，甚至是特定文档的架构。如果我们期望存在的字段不存在，我们也不应该失败。
这种灵活性、性能和一致性的组合使PostgreSQL与JSONB成为一个强大的工具。有基准测试显示，它甚至可能比MongoDB更快。
更多信息请查看：
- JSON类型文档
- JSON函数和运算符
- PostgreSQL、JSONB和GIN索引
- MongoDB与PostgreSQL JSONB基准测试
- 如何在PostgreSQL中使用JSON
- 对所有事情都使用Postgres
Pongo是ORM吗？
不是。
它专注于有效处理文档数据的特性。Node.js ORM有处理JSONB的能力，例如，DrizzleORM对基本操作有很好的支持。
然而，它们都具有有限的查询能力。 通常对于高级查询，你需要回退到JSONPath或JSONB函数（即原始SQL）。如上所示，这种语法处理起来并不是很愉快。这就是为什么Pongo旨在为你做这件事。
它与FerretDB有何不同？
FerretDB插入原生MongoDB协议，这允许它被用作MongoDB并连接到Mongo UI等工具。然而，它需要运行一个代理。
Pongo在不同的层面上操作，直接在库代码中将MongoDB API转换为SQL。 这可以允许更容易的无服务器集成，例如与其他基于PostgreSQL的工具共享连接池等。当然，它不允许使用基于MongoDB网络协议的原生工具。
Pongo的目标不是替代Mongo，而是重用其肌肉记忆并将PostgreSQL的功能和超能力带入Node.js领域。
它是否可以用于生产？
现有的功能是安全可用的，但距离100%兼容MongoDB还有很长的路要走。Pongo是一个新项目，所以可能会有一些功能缺失。
贡献
Pongo是一个社区项目，所以一旦你发现缺少或不工作的内容，我们鼓励你向我们发送GitHub问题或拉取请求来扩展支持或测试覆盖率！也请查看贡献指南
如果你认为缺少某些功能或想更快地获得某些功能，我很乐意接受赞助来优先处理。随时联系我 - 我们会找到方法来帮助你！
行为准则
本项目采用了贡献者公约定义的行为准则，以明确我们社区中的预期行为。
