<img src="https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" height="20px" />

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问题或拉取请求来扩展支持或测试覆盖率！也请查看贡献指南

如果你认为缺少某些功能或想更快地获得某些功能，我很乐意接受赞助来优先处理。随时联系我 - 我们会找到方法来帮助你！

行为准则

本项目采用了贡献者公约定义的行为准则，以明确我们社区中的预期行为。