## 1. Project Overview & Quickstart (pgsty/LICENSE) # LICENSE Open-source repository pgsty/LICENSE ### Repository Details - **Repository:** [pgsty/LICENSE](https://github.com/pgsty/LICENSE) - **Primary Language:** Code *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](https://github.com/fuma-nama/fumadocs). --- ## File: content/ferret/admin.mdx --- title: Administration icon: Wrench --- ------ ## Create FerretDB Cluster After [defining](/ferret/config/) the FerretDB cluster in the [inventory](/config/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`](/ferret/playbook) 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] 在 [清单](/zh/config/inventory) 中 [定义](/zh/ferret/config/) FerretDB 集群后，您可以使用以下命令安装它： ```bash ./mongo.yml -l ferret # 在 ferret 组上安装 MongoDB/FerretDB ``` 由于 FerretDB 使用 PostgreSQL 作为其底层存储，多次运行此剧本通常是安全的。 ------ ## 移除 FerretDB 集群 [#remove-ferretdb-cluster] 要移除 Mongo/FerretDB 集群，请使用 `mongo_purge` 参数运行 [`mongo.yml`](/zh/ferret/playbook) 剧本的 `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](/ferret/param). 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:DBUser.Mongo@10.10.10.10: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](https://docs.ferretdb.io/security/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](https://pgext.cloud/e/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](/pgsql/service/) 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:DBUser.Mongo@10.10.10.3: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) 集群之前，您需要使用相关 [参数](/zh/ferret/param) 在清单中定义它。 以下示例使用默认的单节点 `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:DBUser.Mongo@10.10.10.10:5432/meta' ``` 这里，`mongo_cluster` 和 `mongo_seq` 是基本的身份参数。对于 FerretDB，还需要 `mongo_pgurl` 来指定底层 PG 位置。 请注意，`mongo_pgurl` 参数需要一个 PostgreSQL **超级用户**。在此示例中，为 FerretDB 定义了一个专用的 `mongod` 超级用户。 请注意，FerretDB 的 [身份验证](https://docs.ferretdb.io/security/authentication/) 完全基于 PostgreSQL。您可以使用 FerretDB 或 PostgreSQL 创建其他常规用户。 ------ ## PostgreSQL 集群 [#postgresql-cluster] FerretDB 2.0+ 需要一个扩展：[DocumentDB](https://pgext.cloud/e/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] 您可以使用 [服务](/zh/pgsql/service/) 连接到高可用的 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:DBUser.Mongo@10.10.10.3: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**](/ferret) is an [OPTIONAL](/intro/module#extra-modules) module in Pigsty. It requires the `documentdb` extensions to work since v2.0. Pigsty has packaged that and provides a [`mongo.yml`](https://github.com/pgsty/pigsty/blob/main/conf/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**](/zh/ferret) 是 Pigsty 中的一个 [可选](/zh/intro/module#extra-modules) 模块。 自 v2.0 以来，它需要 `documentdb` 扩展才能工作。 Pigsty 已经打包了这个扩展，并提供了一个 [`mongo.yml`](https://github.com/pgsty/pigsty/blob/main/conf/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`](/ferret/) module for now. ### Mongo Overview [Mongo Overview](https://g.pgsty.com/d/mongo-overview): Overview of a Mongo/FerretDB cluster --- ## File: content/ferret/monitor.zh.mdx --- title: 监控 icon: Telescope --- [`FERRET`](/zh/ferret/) 模块目前有一个仪表板。 ### Mongo Overview [Mongo Overview](https://g.pgsty.com/d/mongo-overview)：Mongo/FerretDB 集群概览 --- ## File: content/ferret/param.mdx --- title: Parameter icon: Variable --- There are 9 parameters in the [`FERRET`](/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`](https://github.com/pgsty/pigsty/blob/main/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.