mongo-diff

mongo-diff 是一个命令行工具，人们可以使用它来比较两个MongoDB集合。

这些集合可以位于单个数据库或两个不同的数据库中（甚至跨越服务器）。

%% This is the source code of a Mermaid diagram, which GitHub will render as a diagram.
%% Note: PyPI does not render Mermaid diagrams, and instead displays their source code.
%%       Reference: https://github.com/pypi/warehouse/issues/13083
graph LR
    script[["mongo_diff.py"]]
    result["List of<br>differences"]

    subgraph s1 \[Server]
        subgraph d1 \[Database]
            collection_a[("Collection A")]
        end
    end

    subgraph s2 \[Server]
        subgraph d2 \[Database]
            collection_b[("Collection B")]
        end
    end

    collection_a --> script
    collection_b --> script
    script --> result

用法

安装

假设您已安装 pipx，您可以通过运行以下命令安装此工具

pipx install mongo-diff

pipx 是一个工具，人们可以使用它来 下载和安装 PyPI上托管的Python脚本。您可以通过运行 $ python -m pip install pipx 来安装 pipx。

运行

您可以通过运行以下命令显示工具的 --help 片段

mongo-diff --help

在撰写本文时，工具的 --help 片段如下

 Usage: mongo-diff [OPTIONS]

 Compare two MongoDB collections.
 Those collections can reside in either a single database or two separate
 databases (even across servers).

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --include-id    --no-include-id      Includes the `_id` field when comparing │
│                                      documents.                              │
│                                      [default: no-include-id]                │
│ --help                               Show this message and exit.             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Collection A ───────────────────────────────────────────────────────────────╮
│ *  --mongo-uri-a                    TEXT  Connection string for accessing    │
│                                           the MongoDB server containing      │
│                                           collection A.                      │
│                                           [env var: MONGO_URI_A]             │
│                                           [required]                         │
│ *  --database-name-a                TEXT  Name of the database containing    │
│                                           collection A.                      │
│                                           [required]                         │
│ *  --collection-name-a              TEXT  Name of collection A. [required]   │
│    --identifier-field-name-a        TEXT  Name of the field of each document │
│                                           in collection A to use to identify │
│                                           a corresponding document in        │
│                                           collection B.                      │
│                                           [default: id]                      │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Collection B ───────────────────────────────────────────────────────────────╮
│ --mongo-uri-b                    TEXT  Connection string for accessing the   │
│                                        MongoDB server containing collection  │
│                                        B (if different from that specified   │
│                                        for collection A).                    │
│                                        [env var: MONGO_URI_B]                │
│ --database-name-b                TEXT  Name of the database containing       │
│                                        collection B (if different from that  │
│                                        specified for collection A).          │
│ --collection-name-b              TEXT  Name of collection B (if different    │
│                                        from that specified for collection    │
│                                        A).                                   │
│ --identifier-field-name-b        TEXT  Name of the field of each document in │
│                                        collection B to use to identify a     │
│                                        corresponding document in collection  │
│                                        A (if different from that specified   │
│                                        for collection A).                    │
╰──────────────────────────────────────────────────────────────────────────────╯

注意：上述片段是从宽度为80像素的终端窗口中捕获的。

MongoDB连接字符串

如上文的 --help 片段所述，您可以通过以下方式之一向工具提供MongoDB连接字符串：(a) 命令行选项；或 (b) 命名为 MONGO_URI_A 和 MONGO_URI_B 的环境变量。后者对于包含密码的MongoDB连接字符串非常有用。

以下是创建这些环境变量的方法

export MONGO_URI_A='mongodb://localhost:27017'
export MONGO_URI_B='mongodb://username:password@host.example.com:22222'

注意：这将仅在当前shell进程创建这些环境变量。您可以通过将这些相同的命令添加到您的shell初始化脚本中（例如 ~/.bashrc，~/.zshrc）来持久化它们。

示例输出

当工具比较集合时，它会显示检测到的差异；如下所示

Documents differ between collections: id=1,id=1. Differences: [('change', 'name', ('Joe', 'Joseph'))]
Document exists in collection A only: id=2
Document exists in collection A only: id=4
Document exists in collection B only: id=5

当工具完成集合的比较后，它将显示结果的摘要；如下所示

                         Result                         
╭───────────────────────────────────────────┬──────────╮
│ Description                               │ Quantity │
├───────────────────────────────────────────┼──────────┤
│ Documents in collection A                 │        4 │
│ Documents in collection B                 │        3 │
├───────────────────────────────────────────┼──────────┤
│ Documents in collection A only            │        2 │
│ Documents in collection B only            │        1 │
├───────────────────────────────────────────┼──────────┤
│ Documents that differ between collections │        1 │
╰───────────────────────────────────────────┴──────────╯

更新中

您可以通过运行以下命令来更新工具到PyPI上可用的最新版本：https://pypi.ac.cn/project/mongo-diff/

pipx upgrade mongo-diff

卸载

您可以通过运行以下命令从您的计算机上卸载工具

pipx uninstall mongo-diff

开发

我们使用Poetry来管理依赖关系并将软件包发布到PyPI。

• pyproject.toml：Poetry和其他工具的配置文件（通过$ poetry init生成）
• poetry.lock：依赖项列表，包括直接和间接依赖项（通过$ poetry update生成）

克隆仓库

git clone https://github.com/eecavanna/mongo-diff.git
cd mongo-diff

创建虚拟环境

创建一个Poetry虚拟环境并将其附加到其shell

poetry shell

您可以通过运行以下命令查看Poetry虚拟环境的信息：$ poetry env info

您可以通过运行以下命令从Poetry虚拟环境的shell中退出：$ exit

从现在起，我将把Poetry虚拟环境的shell称为“Poetry shell”。

安装依赖项

在Poetry shell中，安装项目的依赖项

poetry install

进行更改

根据您的要求编辑工具的源代码和文档。

在编辑工具的源代码时，您可以像平时一样运行工具以测试功能。

mongo-diff --help

构建软件包

更新软件包版本

PyPI 不允许人们多次发布同一软件包的“版本”。

您可以通过运行以下命令来更新软件包的版本标识符

poetry version {version_or_keyword}

您可以将{version_or_keyword}替换为字面量版本标识符（例如0.1.1）或关键字（例如major、minor或patch）。您可以通过运行$ poetry version --help来查看有效的关键字。

或者，您可以手动编辑pyproject.toml中的一行

- version = "0.1.0"
+ version = "0.1.1"

构建软件包

在Poetry shell中，基于最新的源代码构建软件包

poetry build

这将创建一个在dist目录中的源分发文件（文件名以.tar.gz结尾）和一个 wheel 文件（文件名以.whl结尾）。

发布软件包

设置PyPI凭据

在Poetry shell中，创建以下环境变量，如果未以其他方式指定凭据，则Poetry会检查它：

export POETRY_PYPI_TOKEN_PYPI="{api_token}"

将{api_token}替换为包含您想要发布软件包的PyPI项目的PyPI API令牌的作用域。

将软件包发布到PyPI

在Poetry shell中，将新构建的软件包发布到PyPI

poetry publish

此时，人们可以从PyPI下载和安装软件包。