NOTICE Documentation

Official TypeScript developer resources and documentation for pgsty/NOTICE. Verified technical context for AI.

0 stars TypeScript TypeScript 1 file · ~4,172 tokens
RAW Doc

1. Project Overview & Quickstart (pgsty/NOTICE)

NOTICE

Open-source repository pgsty/NOTICE

Repository Details

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (pgsty/docs)

File: README.md

Pigsty Docs

Source Directory for Pigsty Documentation

Documentation Site: https://doc.pgsty.com

Extension Catalog: https://pgext.cloud

Pigsty Repo: https://github.com/pgsty/pigsty

Develop

This is a Next.js application generated with Create Fumadocs.

File: content/ferret/admin.mdx

title: Administration icon: Wrench

Create FerretDB Cluster

After defining the FerretDB cluster in the inventory, you can install it with:

bash
./mongo.yml -l ferret   # Install MongoDB/FerretDB on ferret group

Since FerretDB uses PostgreSQL as its underlying storage, running this playbook multiple times is generally safe.

Remove FerretDB Cluster

To remove a Mongo/FerretDB cluster, run the mongo_purge subtask of mongo.yml playbook with the mongo_purge parameter:

bash
./mongo.yml -e mongo_purge=true -t mongo_purge

File: content/ferret/admin.zh.mdx

title: 管理 icon: Wrench

创建 FerretDB 集群 [#create-ferretdb-cluster]

在 清单 中 定义 FerretDB 集群后，您可以使用以下命令安装它：

bash
./mongo.yml -l ferret   # 在 ferret 组上安装 MongoDB/FerretDB

由于 FerretDB 使用 PostgreSQL 作为其底层存储，多次运行此剧本通常是安全的。

移除 FerretDB 集群 [#remove-ferretdb-cluster]

要移除 Mongo/FerretDB 集群，请使用 mongo_purge 参数运行 mongo.yml 剧本的 mongo_purge 子任务：

bash
./mongo.yml -e mongo_purge=true -t mongo_purge

File: content/ferret/config.mdx

title: Configure icon: CodeXml

FerretDB Cluster

Before deploying a Mongo (FerretDB) cluster, you need to define it in the inventory using the relevant parameters.

The following example uses the default single-node pg-meta cluster’s meta database as FerretDB’s underlying storage:

yaml
all:
  children:

    #----------------------------------#
    # ferretdb for mongodb on postgresql
    #----------------------------------#
    # ./mongo.yml -l ferret
    ferret:
      hosts:
        10.10.10.10: { mongo_seq: 1 }
      vars:
        mongo_cluster: ferret
        mongo_pgurl: 'postgres://mongod:[email protected]:5432/meta'

Here, mongo_cluster and mongo_seq are essential identity parameters. For FerretDB, mongo_pgurl is also required to specify the underlying PG location.

Note that the mongo_pgurl parameter requires a PostgreSQL superuser. In this example, a dedicated mongod superuser is defined for FerretDB.

Note that FerretDB’s authentication is entirely based on PostgreSQL. You can create other regular users using either FerretDB or PostgreSQL.

PostgreSQL Cluster

FerretDB 2.0+ requires an extension: DocumentDB, which depends on several other extensions. Here’s a template for creating a PostgreSQL cluster for FerretDB:

yaml
all:
  children:

    #----------------------------------#
    # pgsql (singleton on current node)
    #----------------------------------#
    # postgres cluster: pg-meta
    pg-meta:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:
        pg_cluster: pg-meta
        pg_users:
          - { name: mongod      ,password: DBUser.Mongo  ,pgbouncer: true ,roles: [dbrole_admin ] ,superuser: true ,comment: ferretdb super user }
          - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: pigsty admin user }
          - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer for meta database }
        pg_databases:
          - {name: meta, owner: mongod ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [ documentdb, postgis, vector, pg_cron, rum ]}
        pg_hba_rules:
          - { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes' }
          - { user: mongod      , db: all ,addr: world ,auth: pwd ,title: 'mongodb password access from everywhere' }
        pg_extensions:
          - documentdb, citus, postgis, pgvector, pg_cron, rum
        pg_parameters:
          cron.database_name: meta
        pg_libs: 'pg_documentdb, pg_documentdb_core, pg_cron, pg_stat_statements, auto_explain'  # add timescaledb to shared_preload_libraries

High Availability

You can use Services to connect to a highly available PostgreSQL cluster and deploy multiple FerretDB instance replicas with L2 VIP binding for FerretDB layer high availability.

yaml
ferret:
  hosts:
    10.10.10.45: { mongo_seq: 1 }
    10.10.10.46: { mongo_seq: 2 }
    10.10.10.47: { mongo_seq: 3 }
  vars:
    mongo_cluster: ferret
    mongo_pgurl: 'postgres://mongod:[email protected]:5436/test'
    vip_enabled: true
    vip_vrid: 128
    vip_address: 10.10.10.99
    vip_interface: eth1

File: content/ferret/config.zh.mdx

title: 配置 icon: CodeXml

FerretDB 集群 [#ferretdb-cluster]

在部署 Mongo (FerretDB) 集群之前，您需要使用相关 参数 在清单中定义它。

以下示例使用默认的单节点 pg-meta 集群的 meta 数据库作为 FerretDB 的底层存储：

yaml
all:
  children:

    #----------------------------------#
    # ferretdb for mongodb on postgresql
    #----------------------------------#
    # ./mongo.yml -l ferret
    ferret:
      hosts:
        10.10.10.10: { mongo_seq: 1 }
      vars:
        mongo_cluster: ferret
        mongo_pgurl: 'postgres://mongod:[email protected]:5432/meta'

这里，mongo_cluster 和 mongo_seq 是基本的身份参数。对于 FerretDB，还需要 mongo_pgurl 来指定底层 PG 位置。

请注意，mongo_pgurl 参数需要一个 PostgreSQL 超级用户。在此示例中，为 FerretDB 定义了一个专用的 mongod 超级用户。

请注意，FerretDB 的 身份验证 完全基于 PostgreSQL。您可以使用 FerretDB 或 PostgreSQL 创建其他常规用户。

PostgreSQL 集群 [#postgresql-cluster]

FerretDB 2.0+ 需要一个扩展：DocumentDB，它依赖于几个其他扩展。以下是为 FerretDB 创建 PostgreSQL 集群的模板：

yaml
all:
  children:

    #----------------------------------#
    # pgsql (singleton on current node)
    #----------------------------------#
    # postgres cluster: pg-meta
    pg-meta:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:
        pg_cluster: pg-meta
        pg_users:
          - { name: mongod      ,password: DBUser.Mongo  ,pgbouncer: true ,roles: [dbrole_admin ] ,superuser: true ,comment: ferretdb super user }
          - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: pigsty admin user }
          - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer for meta database }
        pg_databases:
          - {name: meta, owner: mongod ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [ documentdb, postgis, vector, pg_cron, rum ]}
        pg_hba_rules:
          - { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes' }
          - { user: mongod      , db: all ,addr: world ,auth: pwd ,title: 'mongodb password access from everywhere' }
        pg_extensions:
          - documentdb, citus, postgis, pgvector, pg_cron, rum
        pg_parameters:
          cron.database_name: meta
        pg_libs: 'pg_documentdb, pg_documentdb_core, pg_cron, pg_stat_statements, auto_explain'  # 将 timescaledb 添加到 shared_preload_libraries

高可用性 [#high-availability]

您可以使用 服务 连接到高可用的 PostgreSQL 集群，并部署多个 FerretDB 实例副本，并为 FerretDB 层高可用性绑定 L2 VIP。

yaml
ferret:
  hosts:
    10.10.10.45: { mongo_seq: 1 }
    10.10.10.46: { mongo_seq: 2 }
    10.10.10.47: { mongo_seq: 3 }
  vars:
    mongo_cluster: ferret
    mongo_pgurl: 'postgres://mongod:[email protected]:5436/test'
    vip_enabled: true
    vip_vrid: 128
    vip_address: 10.10.10.99
    vip_interface: eth1

File: content/ferret/index.mdx

title: FERRET icon: Leaf

import {
CodeXml,
Variable,
Wrench,
ScrollText,
Telescope,
MessageCircleQuestion
} from 'lucide-react';

MongoDB has lost its open-source appeal and is no longer suitable for many cases.
In contrast, PostgreSQL offers robust, native JSON support and outperforms MongoDB as a document database.

Thus, FerretDB provides a mongo wire-protocol-compatible layer upon postgres, enabling MongoDB users to migrate smoothly to PostgreSQL’s superior platform.
FERRET is an OPTIONAL module in Pigsty.
It requires the documentdb extensions to work since v2.0.

Pigsty has packaged that and provides a mongo.yml template to help you deploy a FerretDB cluster with ease.

} title='Configuration' href={"/ferret/config"}> Configure ferret module, and use multiple ferret nodes. } title='Parameters' href={"/ferret/param"}> Customize ferret components with 15 parameters } title='Administration' href={"/ferret/admin"}> Create, remove, expand, shrink, upgrade ferret cluster } title='Playbooks' href={"/ferret/playbook"}> Ansible playbooks that can be used in this module } title='Monitoring' href={"/ferret/monitor"}> Dashboards, metrics, record & alerting rules. } title='Usage' href={"/ferret/usage"}> How to use the mcli and configure backup repo

File: content/ferret/index.zh.mdx

title: FERRET icon: Leaf

import {
CodeXml,
Variable,
Wrench,
ScrollText,
Telescope,
MessageCircleQuestion
} from 'lucide-react';

MongoDB 已经失去了其开源吸引力，不再适合许多用例。
相比之下，PostgreSQL 提供强大的原生 JSON 支持，作为文档数据库的性能超越了 MongoDB。

因此，FerretDB 在 postgres 之上提供了与 mongo 线协议兼容的层，使 MongoDB 用户能够平滑迁移到 PostgreSQL 的优越平台。
FERRET 是 Pigsty 中的一个 可选 模块。
自 v2.0 以来，它需要 documentdb 扩展才能工作。

Pigsty 已经打包了这个扩展，并提供了一个 mongo.yml 模板，帮助您轻松部署 FerretDB 集群。

} title='配置' href={"/zh/ferret/config"}> 配置 ferret 模块，并使用多个 ferret 节点。 } title='参数' href={"/zh/ferret/param"}> 使用 9 个参数自定义 ferret 组件 } title='管理' href={"/zh/ferret/admin"}> 创建、移除、扩展、收缩、升级 ferret 集群 } title='剧本' href={"/zh/ferret/playbook"}> 可在此模块中使用的 Ansible 剧本 } title='监控' href={"/zh/ferret/monitor"}> 仪表板、指标、记录和告警规则。 } title='使用' href={"/zh/ferret/usage"}> 如何使用 mcli 和配置备份仓库

File: content/ferret/monitor.mdx

title: Monitor icon: Telescope

There is one dashboard for FERRET module for now.

Mongo Overview

Mongo Overview: Overview of a Mongo/FerretDB cluster

File: content/ferret/monitor.zh.mdx

title: 监控 icon: Telescope

FERRET 模块目前有一个仪表板。

Mongo Overview

Mongo Overview：Mongo/FerretDB 集群概览

File: content/ferret/param.mdx

title: Parameter icon: Variable

There are 9 parameters in the FERRET module.

Parameter Type Level Comment
mongo_seq int I mongo instance identifier, REQUIRED
mongo_cluster string C mongo cluster name, MONGO by default
mongo_pgurl pgurl C/I underlying postgres URL for ferretdb
mongo_ssl_enabled bool C mongo/ferretdb ssl enabled, false by default
mongo_listen ip C mongo listen address, empty for all addr
mongo_port port C mongo service port, 27017 by default
mongo_ssl_port port C mongo tls listen port, 27018 by default
mongo_exporter_port port C mongo exporter port, 9216 by default
mongo_extra_vars string C extra environment variables for MONGO server

Defaults

The default parameters are defined in roles/ferret/defaults/main.yml

yaml
# mongo_cluster:        #CLUSTER  # mongo cluster name, required identity parameter
# mongo_seq: 0          #INSTANCE # mongo instance seq number, required identity parameter
# mongo_pgurl: 'postgres:///'     # mongo/ferretdb underlying postgresql url, required
mongo_ssl_enabled: false          # mongo/ferretdb ssl enabled, false by default
mongo_listen: ''                  # mongo/ferretdb listen address, '' for all addr
mongo_port: 27017                 # mongo/ferretdb listen port, 27017 by default
mongo_ssl_port: 27018             # mongo/ferretdb tls listen port, 27018 by default
mongo_exporter_port: 9216         # mongo/ferretdb exporter port, 9216 by default
mongo_extra_vars: ''              # extra environment variables for mongo/ferretdb

`mongo_cluster`

name: mongo_cluster, type: string, level: C

mongo cluster name, required identity parameter.

default value is MONGO, but you should define it explicitly for production use.

Comply with regexp [a-z][a-z0-9-]*, it is recommended to use descriptive names and start with mongo-

`mongo_seq`

name: mongo_seq, type: int, level: I

mongo instance sequence number, unique integer among mongo cluster is required

You have to explicitly define the sequence number for each mongo instance. integer start from 0 or 1.

`mongo_pgurl`

name: mongo_pgurl, type: pgurl, level: C/I

underlying postgres URL for ferretdb connection.

no default value, you have to define it explicitly. This is the PostgreSQL database URL that FerretDB will use as its backend storage.

Format: postgres://username:password@host:port/database

`mongo_ssl_enabled`

name: mongo_ssl_enabled, type: bool, level: C

mongo/ferretdb ssl enabled flag.

default value is false. Set to true to enable SSL/TLS encryption for mongo connections.

`mongo_listen`

name: mongo_listen, type: ip, level: C

mongo listen address for binding.

default value is empty string '', which means listen on all available addresses. You can specify a specific IP address to bind to.

`mongo_port`

name: mongo_port, type: port, level: C

mongo service port for client connections.

default value is 27017, which is the standard MongoDB port. Change this if you need to avoid port conflicts.

`mongo_ssl_port`

name: mongo_ssl_port, type: port, level: C

mongo tls listen port for encrypted connections.

default value is 27018. This port is used when SSL/TLS is enabled for secure connections.

`mongo_exporter_port`

name: mongo_exporter_port, type: port, level: C

mongo exporter port for metrics collection.

default value is 9216. This port is used by the monitoring exporter to expose metrics for Prometheus.

`mongo_extra_vars`

name: mongo_extra_vars, type: string, level: C

extra environment variables for MONGO server.

default value is empty string ''. You can specify additional environment variables that will be passed to the FerretDB process.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →