FerretDB

https://docs.ferretdb.io/v2.8/
Admin
FerretDB is an open-source MongoDB alternative that converts MongoDB 5.0+ wire protocol queries to...
Tokens:36,916
Snippets:503
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Insert Sample Documents

Source: https://docs.ferretdb.io/v2.8/reference/operators/query/element-operators

Inserts a set of sample documents into the 'electronics' collection for use in subsequent examples. This setup is required before running other queries.

```javascript
db.electronics.insertMany([
  {
    product: 'laptop',
    price: 1500,
    stock: 5,
    discount: true,
    specifications: [
      {
        processor: 'Intel Core i7'
      },
      {
        memory: 16
      }
    ]
  },
  {
    product: 'phone',
    price: 800,
    stock: 10,
    discount: true,
    specifications: [
      {
        brand: 'Apple'
      },
      {
        model: 'iPhone 12'
      }
    ]
  },
  {
    product: 'tablet',
    price: 500,
    stock: 15,
    discount: true,
    specifications: [
      {
        brand: 'Samsung'
      },
      {
        model: 'Galaxy Tab S7'
      }
    ]
  },
  {
    product: 'keyboard',
    price: 100,
    stock: 20
  },
  {
    product: 'mouse',
    price: 50,
    stock: 25,
    discount: null,
    specifications: []
  },
  {
    product: 'monitor',
    price: 250,
    stock: 30,
    discount: true,
    specifications: [
      {
        size: 27
      },
      {
        resolution: '4K'
      }
    ]
  },
  {
    product: 'printer',
    price: 150,
    stock: 35,
    discount: false
  },
  {
    product: 'scanner',
    price: 100,
    stock: 40,
    discount: true,
    specifications: [
      {
        type: 'flatbed'
      }
    ]
  }
])

```

--------------------------------

### Install PostgreSQL using YUM

Source: https://docs.ferretdb.io/v2.8/installation/ferretdb/rpm

If PostgreSQL is not automatically installed, use this command to install it on your system. This is a prerequisite for FerretDB.

```bash
sudo yum install -y postgresql  

```

--------------------------------

### Start FerretDB with Docker Compose

Source: https://docs.ferretdb.io/v2.8/security/tls-connections

Command to start the services defined in the `docker-compose.yml` file, including the FerretDB server configured for TLS.

```shell
docker compose up
```

--------------------------------

### Launch FerretDB Instance

Source: https://docs.ferretdb.io/v2.8/guides/replication

Start the FerretDB container to connect to the primary PostgreSQL instance.

```bash
docker compose up -d ferretdb  
```

--------------------------------

### Start FerretDB Evaluation Container

Source: https://docs.ferretdb.io/v2.8/installation/evaluation

Run this command to start a Docker container with FerretDB, PostgreSQL, and the DocumentDB extension. Ensure you replace `<username>` and `<password>` with your desired credentials. Data is persisted in the `./data` directory.

```bash
docker run -d --name ferretdb -p 27017:27017 \
  -e POSTGRES_USER=<username> \
  -e POSTGRES_PASSWORD=<password> \
  -v ./data:/var/lib/postgresql/data \
  ghcr.io/ferretdb/ferretdb-eval:2

```

--------------------------------

### Install DocumentDB DEB Package

Source: https://docs.ferretdb.io/v2.8/installation/documentdb/deb

Use this command to install the DocumentDB DEB package. Replace `/path/to/documentdb.deb` with the actual path to your downloaded file.

```bash
sudo dpkg -i /path/to/documentdb.deb
```

--------------------------------

### Verify FerretDB Installation

Source: https://docs.ferretdb.io/v2.8/installation/ferretdb/rpm

Run this command after installation to confirm that FerretDB has been successfully installed and to check its version.

```bash
ferretdb --version  

```

--------------------------------

### Example Diff Output

Source: https://docs.ferretdb.io/v2.8/configuration/operation-modes

This example shows the typical output format when using diff modes, highlighting differences in response headers and bodies between FerretDB and a proxy.

```text
Header diff:  
---
--- res header  
+++
+++ proxy header  
@@ -1 +1 @@  
-length:    63, id:    4, response_to:   13, opcode: OP_MSG  
+length:   191, id:   53, response_to:   13, opcode: OP_MSG  
 
Body diff:  
---
--- res body  
+++
+++ proxy body  
@@ -7,4 +7,12 @@  
      "Document": {  
-        "you": "127.0.0.1:64795",  
+        "you": "192.168.65.1:21365",  
         "ok": 1.0,  
       },

```

--------------------------------

### Start Replica PostgreSQL Instance

Source: https://docs.ferretdb.io/v2.8/guides/replication

Launches the replica PostgreSQL instance using Docker Compose after it has been initialized with the base backup from the primary.

```bash
docker compose up -d postgres_replica
```

--------------------------------

### Install FerretDB DEB package

Source: https://docs.ferretdb.io/v2.8/installation/ferretdb/deb

Use this command to install the downloaded FerretDB .deb package on your system.

```bash
sudo dpkg -i ferretdb.deb
```

--------------------------------

### Start Primary PostgreSQL Instance

Source: https://docs.ferretdb.io/v2.8/guides/replication

Initiates the primary PostgreSQL instance using Docker Compose. This command should be run before setting up the replica.

```bash
docker compose up -d postgres_primary
```

--------------------------------

### Typical Aggregation Pipeline Example

Source: https://docs.ferretdb.io/v2.8/usage/aggregations

Demonstrates a typical aggregation pipeline with `$match`, `$group`, and `$sort` stages to process sales data.

```javascript
db.sales.aggregate([
  { $match: { category: { $ne: 'Electronics' } } },
  {
    $group: {
      _id: '$category',
      totalPrice: { $sum: '$price' },
      productCount: { $sum: 1 }
    }
  },
  { $sort: { totalPrice: -1 } }
])
```

--------------------------------

### Install FerretDB RPM Package

Source: https://docs.ferretdb.io/v2.8/installation/ferretdb/rpm

Use this command to install the downloaded FerretDB RPM package. Ensure the package is renamed to `ferretdb.rpm` before running.

```bash
sudo rpm -i ferretdb.rpm  

```

--------------------------------

### Start FerretDB in diff-normal mode

Source: https://docs.ferretdb.io/v2.8/migration/premigration-testing

Use this command to start FerretDB in `diff-normal` mode for testing. Ensure to specify proxy and listen addresses, along with the PostgreSQL connection URL.

```bash
ferretdb --mode=diff-normal \
  --proxy-addr=<mongodb-URI> \
  --listen-addr=<ferretdb-listen-address> \
  --postgresql-url=<postgres-connection>
```

--------------------------------

### Insert Sample Documents

Source: https://docs.ferretdb.io/v2.8/reference/operators/query/evaluation-operators

Inserts sample documents into the 'catalog' collection for use in subsequent examples.

```javascript
db.catalog.insertMany([
  {
    product: 'bottle',
    price: 15,
    stock: 1
  },
  {
    product: 'spoon',
    price: 500,
    stock: 0
  },
  {
    product: 'cup',
    price: 100,
    stock: 14
  },
  {
    product: 'BoWL',
    price: 56,
    stock: 5
  },
  {
    product: 'boTtLe',
    price: 20,
    stock: 3
  }
])
```

--------------------------------

### Launch Read-Only FerretDB Instance

Source: https://docs.ferretdb.io/v2.8/guides/replication

Start a FerretDB instance configured for read-only access to the replica PostgreSQL instance.

```bash
docker compose up -d ferretdb_readonly  
```

--------------------------------

### Docker Compose for PostgreSQL and FerretDB

Source: https://docs.ferretdb.io/v2.8/security/authentication

Example Docker Compose file to set up a PostgreSQL server with specified credentials and connect FerretDB to it. This configures both the database and the FerretDB service.

```yaml
services:
  postgres:
    image: ghcr.io/ferretdb/postgres-documentdb:17
    environment:
      POSTGRES_USER: username
      POSTGRES_PASSWORD: password
      POSTGRES_DB: postgres
    volumes:
      - ./data:/var/lib/postgresql/data
  
  ferretdb:
    image: ghcr.io/ferretdb/ferretdb:2
    restart: on-failure
    ports:
      - 27017:27017
    environment:
      FERRETDB_POSTGRESQL_URL: postgres://username:password@postgres:5432/postgres

networks:
  default:
    name: ferretdb
```

--------------------------------

### Array Field Example

Source: https://docs.ferretdb.io/v2.8/usage/concepts

Shows an example of an array field within a document, used in conjunction with dot notation.

```json
{ "animals": ["dog", "cat", "fish", "fox"] }
```

--------------------------------

### Insert Initial Document for $push Example

Source: https://docs.ferretdb.io/v2.8/reference/operators/update/array-update-operators

Inserts a document with an existing array into the 'store' collection for demonstrating the $push operator.

```javascript
db.store.insertMany([
  { _id: 1, items: ['pens', 'pencils', 'paper', 'erasers', 'rulers'] }
])
```

--------------------------------

### Embedded Document Example

Source: https://docs.ferretdb.io/v2.8/usage/concepts

Provides an example of a document containing multiple levels of embedded documents, demonstrating dot notation usage.

```json
{
  "name": {
    "first": "Tom",
    "last": "Barry"
  },
  "contact": {
    "address": {
      "city": "Kent",
      "state": "Ohio"
    },
    "phone": "432-124-1234"
  }
}
```

--------------------------------

### Vector Search Response Example

Source: https://docs.ferretdb.io/v2.8/guides/vector-search

This is an example of the response returned by the vector search query when `returnStoredSource: true`. It includes the matching documents with their titles, summaries, vectors, and authors, along with similarity scores.

```javascript
response = {
  cursor: {
    id: Long(0),
    ns: 'db.books',
    firstBatch: [
      {
        _id: 'frankenstein_1818',
        title: 'Frankenstein',
        summary:
          'Victor Frankenstein creates life through unorthodox scientific methods '
          'but is horrified by his creation. As his creature seeks acceptance, the '
          'novel explores themes of responsibility, alienation, and the ethical limits '
          'of scientific experimentation.',
        vector: [
          -0.010190412402153015, 0.049356549978256226, -0.012309172190725803, 0.10420369356870651, 0.010599562898278236,
          0.057357728481292725, 0.02385704033076763, 0.04186723381280899, 0.003379989881068468, 0.02957085147500038,
          -0.08477196842432022, -0.0017921233084052801
        ],
        author: 'Mary Shelley'
      },
      {
        _id: 'moby_dick_1851',
        title: 'Moby Dick',
        summary:
          'Ishmael recounts his journey aboard the whaling ship Pequod under the leadership '
          'of the obsessed Captain Ahab, who is obsessed with hunting the legendary '
          'white whale, Moby Dick. The novel delves into themes of human struggle '
          'against nature and the destructive power of obsession.',
        vector: [
          -0.0016038859030231833, 0.08863562345504761, 0.006037247832864523, 0.044850509613752365,
          -0.019985735416412354, -0.017665650695562363, 0.07435955852270126, 0.0025448515079915524,
          -0.08427142351865768, 0.07445722818374634, -0.02302693948149681, -0.0778273269534111
        ],
        author: 'Herman Melville'
      }
    ]
  },
  ok: Double(1)
}

```

--------------------------------

### Install New DocumentDB DEB Package for Update

Source: https://docs.ferretdb.io/v2.8/installation/documentdb/deb

When updating FerretDB, first install the new matching DocumentDB DEB package. Replace `<new-documentdb-package.deb>` with the actual filename.

```bash
sudo dpkg -i /path/to/<new-documentdb-package.deb>
```

--------------------------------

### Vector Search Response Example

Source: https://docs.ferretdb.io/v2.8/guides/vector-search

This is an example of the response structure returned by a vector search query, showing the found documents with their respective fields and vectors.

```json
response = {
  cursor: {
    id: Long(0),
    ns: 'db.books',
    firstBatch: [
      {
        _id: 'moby_dick_1851',
        title: 'Moby Dick',
        summary:
          'Ishmael recounts his journey aboard the whaling ship Pequod under the leadership ' +
          'of the obsessed Captain Ahab, who is obsessed with hunting the legendary ' +
          'white whale, Moby Dick. The novel delves into themes of human struggle ' +
          'against nature and the destructive power of obsession.',
        vector: [
          -0.0016038859030231833, 0.08863562345504761, 0.006037247832864523, 0.044850509613752365,
          -0.019985735416412354, -0.017665650695562363, 0.07435955852270126, 0.0025448515079915524,
          -0.08427142351865768, 0.07445722818374634, -0.02302693948149681, -0.0778273269534111
        ],
        author: 'Herman Melville'
      },
      {
        _id: 'frankenstein_1818',
        title: 'Frankenstein',
        summary:
          'Victor Frankenstein creates life through unorthodox scientific methods ' +
          'but is horrified by his creation. As his creature seeks acceptance, the ' +
          'novel explores themes of responsibility, alienation, and the ethical limits ' +
          'of scientific experimentation.',
        vector: [
          -0.010190412402153015, 0.049356549978256226, -0.012309172190725803, 0.10420369356870651, 0.010599562898278236,
          0.057357728481292725, 0.02385704033076763, 0.04186723381280899, 0.003379989881068468, 0.02957085147500038,
          -0.08477196842432022, -0.0017921233084052801
        ],
        author: 'Mary Shelley'
      }
    ]
  },
  ok: Double(1)
}
```

--------------------------------

### Aggregation Pipeline Result Example

Source: https://docs.ferretdb.io/v2.8/usage/aggregations

Shows the expected result format after executing the typical aggregation pipeline.

```json
response = [
  { _id: 'Home', totalPrice: 2700, productCount: 2 },
  { _id: 'Clothing', totalPrice: 80, productCount: 2 },
  { _id: 'Books', totalPrice: 60, productCount: 2 }
]
```

--------------------------------

### Create DocumentDB Extension

Source: https://docs.ferretdb.io/v2.8/installation/documentdb/deb

Run this SQL command within the `postgres` database to create the DocumentDB extension after installing the package and configuring PostgreSQL.

```sql
CREATE EXTENSION documentdb CASCADE;
```

--------------------------------

### Use $regex Operator for Starting Character

Source: https://docs.ferretdb.io/v2.8/reference/operators/query/evaluation-operators

Finds documents where the 'product' field starts with the letter 'b' using the $regex operator.

```javascript
db.catalog.find({
  product: {
    $regex: /^b/
  }
})
```

--------------------------------

### Docker Compose Setup for FerretDB Replication

Source: https://docs.ferretdb.io/v2.8/guides/replication

Defines the services for primary and replica PostgreSQL instances, and FerretDB instances (one for primary, one read-only for replica). Ensure the primary PostgreSQL instance is initialized first.

```yaml
services:
  postgres_primary:
    image: ghcr.io/ferretdb/postgres-documentdb:17
    container_name: postgres_primary
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=postgres
    volumes:
      - ./primary_data:/var/lib/postgresql/data
      - replica_backup:/tmp/replica_backup
    ports:
      - '5432:5432'

  postgres_replica:
    image: ghcr.io/ferretdb/postgres-documentdb:17
    container_name: postgres_replica
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=postgres
    volumes:
      - replica_backup:/var/lib/postgresql/data
    ports:
      - '5433:5432'

  ferretdb:
    image: ghcr.io/ferretdb/ferretdb:2
    container_name: ferretdb
    environment:
      - FERRETDB_POSTGRESQL_URL=postgres://user:password@postgres_primary:5432/postgres
    ports:
      - '27017:27017'

  ferretdb_readonly:
    image: ghcr.io/ferretdb/ferretdb:2
    container_name: ferretdb_readonly
    environment:
      - FERRETDB_POSTGRESQL_URL=postgres://user:password@postgres_replica:5432/postgres
    ports:
      - '27018:27017'
    depends_on:
      - postgres_replica

networks:
  default:
    name: ferretdb

volumes:
  replica_backup:

```

--------------------------------

### Insert Document for $addToSet Example

Source: https://docs.ferretdb.io/v2.8/reference/operators/update/array-update-operators

Inserts a document with a basic 'items' array into the 'store' collection to demonstrate the $addToSet operator.

```javascript
db.store.insertMany([{ _id: 1, items: ['pens', 'pencils'] }])
```

--------------------------------

### Fetch Docker Logs

Source: https://docs.ferretdb.io/v2.8/configuration/observability

Use this command to fetch FerretDB logs when using Docker Compose for local setup. Otherwise, use 'docker ps' and 'docker logs'.

```bash
docker compose logs ferretdb  

```

--------------------------------

### Docker Compose for FerretDB Production Setup

Source: https://docs.ferretdb.io/v2.8/installation/ferretdb/docker

This configuration sets up a PostgreSQL database with the DocumentDB extension and FerretDB for local testing. It stores PostgreSQL data in a local './data' directory.

```yaml
services:
  postgres:
    image: ghcr.io/ferretdb/postgres-documentdb:17-0.108.0-ferretdb-2.8.0
    restart: on-failure
    environment:
      - POSTGRES_USER=username
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=postgres
    volumes:
      - ./data:/var/lib/postgresql/data

  ferretdb:
    image: ghcr.io/ferretdb/ferretdb:2.8.0
    restart: on-failure
    ports:
      - 27017:27017
    environment:
      - FERRETDB_POSTGRESQL_URL=postgres://username:password@postgres:5432/postgres

networks:
  default:
    name: ferretdb

```

--------------------------------

### Collection Example with Multiple Documents

Source: https://docs.ferretdb.io/v2.8/usage/concepts

Illustrates a FerretDB collection containing multiple documents, each representing a distinct record.

```json
{
  "scientists": [
    {
      "first": "Alan",
      "last": "Turing",
      "born": 1912
    },
    {
      "first": "Thomas",
      "last": "Edison",
      "birth": 1847
    },
    {
      "first": "Nikola",
      "last": "Tesla",
      "birth": 1856
    }
  ]
}
```

--------------------------------

### Example Search Response with Relevance Score

Source: https://docs.ferretdb.io/v2.8/guides/full-text-search

This is an example of a response from a full-text search query, including the calculated relevance score for a matching document. The score indicates how well the document matched the search criteria.

```javascript
response = {
  cursor: {
    id: Long(0),
    ns: 'db.books',
    firstBatch: [
      {
        _id: 'moby_dick_1851',
        title: 'Moby Dick',
        authors: [
          {
            name: 'Herman Melville',
            nationality: 'American'
          }
        ],
        summary:
          'Ishmael recounts his journey aboard the whaling ship Pequod under the leadership '
          + 'of the obsessed Captain Ahab, who is obsessed with hunting the legendary '
          + 'white whale, Moby Dick. The novel delves into themes of human struggle '
          + 'against nature and the destructive power of obsession.',
        score: Double(3)
      }
    ]
  },
  ok: Double(1)
}
```

--------------------------------

### Insert Documents for Deletion Example

Source: https://docs.ferretdb.io/v2.8/usage/delete

This snippet demonstrates how to insert multiple documents into a collection, which will be used for subsequent delete operations.

```javascript
db.scientists.insertMany([
  {
    firstname: 'Thomas',
    lastname: 'Edison',
    born: 1847,
    invention: 'LightBulb',
    nobel: true
  },
  {
    firstname: 'Graham',
    lastname: 'Bell',
    born: 1847,
    invention: 'telephone',
    nobel: false
  },
  {
    firstname: 'Nikola',
    lastname: 'Tesla',
    born: 1856,
    invention: 'Tesla coil',
    nobel: false
  },
  {
    firstname: 'Ada',
    lastname: 'Lovelace',
    born: 1815,
    invention: 'Computer programming',
    nobel: false
  }
])
```

--------------------------------

### Single Document Example

Source: https://docs.ferretdb.io/v2.8/usage/concepts

A basic FerretDB document representing a single record with key-value pairs.

```json
{
  "first": "Thomas",
  "last": "Edison",
  "invention": "Lightbulb",
  "birth": 1847
}
```

--------------------------------

### Example Search Result

Source: https://docs.ferretdb.io/v2.8/guides/full-text-search

Illustrates a typical response structure when performing a full-text search, showing the documents that matched the search criteria.

```json
{
  cursor: {
    id: Long(0),
    ns: 'db.books',
    firstBatch: [
      {
        _id: 'pride_prejudice_1813',
        title: 'Pride and Prejudice',
        authors: [
          {
            name: 'Jane Austen',
            nationality: 'British'
          }
        ],
        summary:
          'This novel portrays the life and challenges of Elizabeth Bennet as she '
          'navigates societal expectations, class prejudice, and romance. The book '
          'explores the evolving relationship between Elizabeth and Mr. Darcy, shedding '
          'light on the virtues of understanding and self-awareness.'
      }
    ]
  },
  ok: Double(1)
}
```

--------------------------------

### Vector Search for Book Recommendations

Source: https://docs.ferretdb.io/v2.8/guides/vector-search

This example demonstrates a vector search on the 'books' collection to find the two nearest neighbors for a given query vector. It includes a projection stage to display the title, author, summary, and vector of the results.

```javascript
db.runCommand({
  aggregate: 'books',
  pipeline: [
    {
      $search: {
        cosmosSearch: {
          vector: [
            0.02232860028743744, 0.06849973648786545, 0.030828291550278664, 0.0903232991695404, -0.028270352631807327,
            -0.036311957985162735, 0.02430308423936367, -0.051550041884183884, -0.06737732142210007,
            0.011019553989171982, -0.013402754440903664, -0.004793450236320496
          ],
          path: 'vector',
          k: 2,
          efSearch: 40
        }
      }
    },
    {
      $project: {
        title: 1,
        author: {
          $first: '$authors.name'
        },
        summary: 1,
        vector: 1
      }
    }
  ],
  cursor: {}
})
```

--------------------------------

### Connect to FerretDB with Authentication Enabled

Source: https://docs.ferretdb.io/v2.8/security/authentication

Example connection string for accessing FerretDB when authentication is enabled, requiring valid PostgreSQL user credentials within the URI.

```mongodb
mongodb://username:password@@127.0.0.1:27017/
```

--------------------------------

### Example MongoDB URI with TLS

Source: https://docs.ferretdb.io/v2.8/security/tls-connections

Use this URI format to connect to FerretDB with TLS enabled. The `tls` parameter must be set to `true`, and `tlsCAFile` should point to the root CA certificate if it's not system-issued.

```shell
mongodb://ferretdb:27018/?tls=true&tlsCAFile=companyRootCA.pem
```

--------------------------------

### Custom FerretDB Systemd Configuration for Unix Socket

Source: https://docs.ferretdb.io/v2.8/installation/ferretdb/systemd

This example shows how to override systemd options to make FerretDB listen on a Unix domain socket. Use `systemctl edit ferretdb` to apply such custom configurations.

```systemd
### Editing /etc/systemd/system/ferretdb.service.d/override.conf
### Anything between here and the comment below will become the new contents of the file

[Service]
Environment="FERRETDB_LISTEN_UNIX=/var/lib/ferretdb/ferretdb.sock"

### Lines below this comment will be discarded
...

```

--------------------------------

### Update or Insert with $set

Source: https://docs.ferretdb.io/v2.8/reference/operators/update/field-update-operators

Demonstrates using the $set operator with upsert: true to update existing documents or insert new ones. This example updates 'price' and 'lastUpdate'.

```javascript
db.stocks.update(  
  { symbol: 'AAPL' },  
  {  
    $set: {  
      price: 150,  
      lastUpdate: new Date()  
    }  
  },  
  { upsert: true }  
)
```

--------------------------------

### Combine Conditions with $or

Source: https://docs.ferretdb.io/v2.8/reference/operators/query/logical-operators

Use the $or operator to select documents where at least one of the specified conditions is true. This example selects documents that either have a discount and stock not equal to 0, or have a price less than or equal to 60.

```javascript
db.catalog.find({
  $or: [
    {
      $and: [
        {
          discount: true
        },
        {
          stock: {
            $ne: 0
          }
        }
      ]
    },
    {
      price: {
        $lte: 60
      }
    }
  ]
})
```

--------------------------------

### Example Telemetry Data Structure

Source: https://docs.ferretdb.io/v2.8/telemetry

This JSON structure represents the data collected and sent to the FerretDB Beacon service, as well as saved locally in telemetry.json. It includes version information, build details, system metrics, and command statistics.

```json
{
  "_comment": "Sent to https://beacon.ferretdb.com/ at 2025-03-06 13:28:57Z.",
  "version": "v2.0.0",
  "commit": "2214721e51d64be04ad016f401d0abf8a335993e",
  "branch": "unknown",
  "dirty": true,
  "package": "docker",
  "debug": false,
  "build_environment": {
    "-buildmode": "exe",
    "-compiler": "gc",
    "-trimpath": "true",
    "CGO_ENABLED": "0",
    "GOAMD64": "v1",
    "GOARCH": "amd64",
    "GOOS": "linux",
    "go.version": "go1.24.1",
    "vcs": "git",
    "vcs.modified": "true",
    "vcs.revision": "2214721e51d64be04ad016f401d0abf8a335993e",
    "vcs.time": "2025-03-05T12:26:16Z"
  },
  "os": "linux",
  "arch": "amd64",
  "postgresql_version": "PostgreSQL 16.8 (Debian 16.8-1.pgdg120+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 12.2.0-14) 12.2.0, 64-bit",
  "documentdb_version": "0.102.0 gitref: HEAD sha:f7c318c buildId:0",
  "uuid": "<redacted>",
  "uptime": 86400099948209,
  "command_metrics": {
    "OP_MSG": {
      "count": {
        "unknown": {
          "ok": 1440
        }
      },
      "find": {
        "unknown": {
          "ok": 1440
        }
      },
      "getMore": {
        "unknown": {
          "ok": 4320
        }
      },
      "hello": {
        "unknown": {
          "ok": 8639
        }
      },
      "ping": {
        "unknown": {
          "ok": 1437
        }
      },
      "update": {
        "unknown": {
          "ok": 1520
        }
      }
    },
    "OP_REPLY": {
      "unknown": {
        "unknown": {
          "ok": 3
        }
      }
    }
  }
}
```

--------------------------------

### Create Standby Signal File

Source: https://docs.ferretdb.io/v2.8/guides/replication

Create a standby.signal file on the replica to designate it as a replica instance.

```bash
docker exec -it postgres_replica bash -c "touch /var/lib/postgresql/data/standby.signal"  
```

--------------------------------

### Update FerretDB DEB package

Source: https://docs.ferretdb.io/v2.8/installation/ferretdb/deb

Install a new FerretDB .deb package to update your existing installation. Ensure you update the DocumentDB package first.

```bash
sudo dpkg -i /path/to/<new-ferretdb-package>.deb
```

--------------------------------

### Initialize Replica with Base Backup

Source: https://docs.ferretdb.io/v2.8/guides/replication

Executes `pg_basebackup` on the primary PostgreSQL instance to create a base backup and initialize the replica's data directory. The `-R` flag automatically creates the `standby.signal` and `postgresql.auto.conf` files for streaming replication.

```bash
docker exec -it postgres_primary pg_basebackup -D /tmp/replica_backup -P -R -X stream -c fast -U replicator
```

--------------------------------

### Configure PostgreSQL for DocumentDB Extension

Source: https://docs.ferretdb.io/v2.8/installation/documentdb/deb

Add these lines to your `postgresql.conf` file to load DocumentDB extension libraries on startup and configure DocumentDB settings. Ensure PostgreSQL is restarted after making changes.

```ini
shared_preload_libraries                      = 'pg_cron,pg_documentdb_core,pg_documentdb'
cron.database_name                            = 'postgres'
  
documentdb.enableCompact                      = true  
  
documentdb.enableLetAndCollationForQueryMatch = true  
documentdb.enableNowSystemVariable            = true  
documentdb.enableSortbyIdPushDownToPrimaryKey = true  
  
documentdb.enableSchemaValidation             = true  
documentdb.enableBypassDocumentValidation     = true  
  
documentdb.enableUserCrud                     = true  
documentdb.maxUserLimit                       = 100
```

--------------------------------

### Nested Document Example

Source: https://docs.ferretdb.io/v2.8/usage/concepts

Demonstrates a FerretDB document with a nested subdocument for structured data.

```json
{
  "name": {
    "first": "Thomas",
    "last": "Edison"
  },
  "invention": "Lightbulb",
  "birth": 1847
}
```

--------------------------------

### Connect to PostgreSQL with DocumentDB using psql

Source: https://docs.ferretdb.io/v2.8/installation/documentdb/docker

Connect to the running PostgreSQL with DocumentDB extension instance using the psql command-line tool. Replace placeholders with your actual credentials.

```bash
psql 'postgres://<username>:<password>@localhost:5432/postgres'
```

--------------------------------

### Configure Replica Connection Info

Source: https://docs.ferretdb.io/v2.8/guides/replication

Connect to the replica and set the primary connection details to receive WAL data.

```bash
docker exec -it postgres_replica psql -U user -d postgres -c "ALTER SYSTEM SET primary_conninfo TO 'host=postgres_primary port=5432 user=replicator password=replicatorpassword';"  
```

--------------------------------

### Insert Sample Documents

Source: https://docs.ferretdb.io/v2.8/reference/operators/query/array-operators

Inserts sample documents into the 'team' collection for demonstrating array query operators.

```javascript
db.team.insertMany([
  {
    id: 1,
    name: 'Jack Smith',
    position: 'Manager',
    skills: ['leadership', 'communication', 'project management'],
    contact: {
      email: 'john@example.com',
      phone: '123-456-7890'
    },
    active: true
  },
  {
    id: 2,
    name: 'Jane Mark',
    position: 'Software Developer',
    skills: ['Java', 'Python', 'C++'],
    contact: {
      email: 'jane@example.com',
      phone: '123-456-7891'
    },
    active: false
  },
  {
    id: 3,
    name: 'Bob Johnson',
    position: 'Graphic Designer',
    skills: ['Adobe Photoshop', 'Illustrator', 'InDesign'],
    contact: {
      email: 'bob@example.com',
      phone: '123-456-7892'
    },
    active: true
  },
  {
    id: 4,
    name: 'Alice Williams',
    position: 'Marketing Coordinator',
    skills: ['communication', 'content creation', 'event planning'],
    contact: {
      email: 'alice@example.com',
      phone: '123-456-7893'
    },
    active: true
  }
])
```

--------------------------------

### MongoDB Connection URI

Source: https://docs.ferretdb.io/v2.8/installation/ferretdb/docker

Example MongoDB connection string for authenticating to FerretDB using mongosh.

```text
mongodb://username:password@127.0.0.1/
```

--------------------------------

### Clone and Run FerretDB Compatibility Tool

Source: https://docs.ferretdb.io/v2.8/migration/premigration-testing

This command sequence clones the compatibility tool repository and executes it to check for unsupported operators in your application's files. Ensure you replace '/path/to/myapp' with the actual directory.

```bash
# clone the repository and run the compat-tool  
$ git clone https://github.com/FerretDB/amazon-documentdb-tools.git && cd amazon-documentdb-tools/compat-tool  
$ python3 compat.py --directory=/path/to/myapp --version=FerretDB  
```

--------------------------------

### Insert Sample Documents

Source: https://docs.ferretdb.io/v2.8/reference/operators/query/bitwise-operators

Inserts sample documents into the 'numbers' collection for demonstrating bitwise operators. These documents contain numeric and binary string representations of values.

```javascript
db.numbers.insertMany([
  { _id: 1, value: 23, binaryValue: '10111' },
  { _id: 2, value: 56, binaryValue: '111000' },
  { _id: 3, value: 67, binaryValue: '1000011' },
  { _id: 4, value: 102, binaryValue: '1100110' },
  { _id: 5, value: 5, binaryValue: '101' }
])
```

--------------------------------

### Apply Kubernetes Configuration

Source: https://docs.ferretdb.io/v2.8/installation/documentdb/kubernetes

Use this command to apply the PostgreSQL StatefulSet and Service configuration to your Kubernetes cluster.

```bash
kubectl apply -f postgres.yaml
```

--------------------------------

### Insert Sample Sales Data

Source: https://docs.ferretdb.io/v2.8/usage/aggregations

Inserts multiple documents into the 'sales' collection for demonstration purposes.

```javascript
db.sales.insertMany([
  { _id: 1, category: 'Electronics', price: 1000 },
  { _id: 2, category: 'Electronics', price: 800 },
  { _id: 3, category: 'Clothing', price: 30 },
  { _id: 4, category: 'Clothing', price: 50 },
  { _id: 5, category: 'Home', price: 1500 },
  { _id: 6, category: 'Home', price: 1200 },
  { _id: 7, category: 'Books', price: 20 },
  { _id: 8, category: 'Books', price: 40 }
])
```

--------------------------------

### Run MongoDB Shell inside Container

Source: https://docs.ferretdb.io/v2.8/installation/evaluation

If MongoDB Shell is not installed locally, you can execute it within the FerretDB Docker container. Replace `<username>` and `<password>` with your credentials.

```bash
docker exec -it ferretdb mongosh mongodb://<username>:<password>@127.0.0.1:27017/

```

--------------------------------

### Insert Sample Documents for Array Update

Source: https://docs.ferretdb.io/v2.8/usage/update

Populate the 'employees' collection with sample documents containing an 'catalog' array. This is a prerequisite for demonstrating array update operations.

```javascript
db.employees.insertMany([
  {
    name: {
      first: 'Earl',
      last: 'Thomas'
    },
    employeeID: 1234,
    age: 23,
    role: 'salesperson',
    catalog: ['printer', 'cardboard', 'crayons', 'books']
  },
  {
    name: {
      first: 'Sam',
      last: 'Johnson'
    },
    employeeID: 2234,
    age: 35,
    role: 'salesperson',
    catalog: ['cabinet', 'fridge', 'blender', 'utensils']
  },
  {
    name: {
      first: 'Clarke',
      last: 'Dane'
    },
    employeeID: 3234,
    age: 21,
    role: 'salesperson',
    catalog: ['printer', 'pencils', 'crayons', 'toys']
  }
])
```

--------------------------------

### Set Field to Current Date with $currentDate

Source: https://docs.ferretdb.io/v2.8/reference/operators/update/field-update-operators

Use the $currentDate operator to assign the current date or timestamp to a specified field. This example updates the 'startDate' field.

```javascript
db.employee.updateOne(  
  { name: 'John Doe' },  
  { $currentDate: { startDate: true } }  
)
```

--------------------------------

### Generic Aggregate Command Usage

Source: https://docs.ferretdb.io/v2.8/usage/aggregations

Illustrates the basic structure of the `aggregate` command with `$match` and `$group` stages for general data aggregation.

```javascript
// Aggregation pipeline to perform aggregation operations on a collection
db.collection.aggregate([
  // Stage 1: Matching documents based on a specific field and value
  { $match: { field: value } },
  // Stage 2: Grouping documents by the "category" field and calculating the sum of the "quantity" field
  { $group: { _id: '$category', total: { $sum: '$quantity' } } }
])
```

--------------------------------

### Combine Multiple Conditions with $and

Source: https://docs.ferretdb.io/v2.8/reference/operators/query/logical-operators

Use the $and operator to select documents where all specified conditions are true. This example selects documents where the price is less than 100 and the stock is not 0.

```javascript
db.catalog.find({
  $and: [
    {
      price: {
        $lt: 100
      }
    },
    {
      stock: {
        $ne: 0
      }
    }
  ]
})
```

--------------------------------

### Configure PostgreSQL WAL Settings for Replication

Source: https://docs.ferretdb.io/v2.8/guides/replication

Appends necessary settings to the `postgresql.conf` file within the primary PostgreSQL container to enable and configure WAL streaming for replication. These settings include `wal_level`, `max_wal_senders`, `wal_keep_size`, and `listen_addresses`.

```bash
docker exec -it postgres_primary bash
cat <<EOF >> /var/lib/postgresql/data/postgresql.conf
wal_level = replica
max_wal_senders = 10
wal_keep_size = 64MB
listen_addresses = '*'
EOF
```

--------------------------------

### Run psql inside a temporary PostgreSQL container

Source: https://docs.ferretdb.io/v2.8/installation/documentdb/docker

If psql is not installed locally, you can run it within a temporary PostgreSQL container. This command connects to your existing PostgreSQL instance.

```bash
docker run --rm -it ghcr.io/ferretdb/postgres-documentdb:17-0.108.0-ferretdb-2.8.0 \
  psql postgres://<username>:<password>@localhost:5432/postgres
```

--------------------------------

### Run Production PostgreSQL with DocumentDB Image

Source: https://docs.ferretdb.io/v2.8/installation/documentdb/docker

Use this command to run the production Docker image for PostgreSQL with the DocumentDB extension. Ensure you replace placeholder values for username, password, and database.

```bash
docker run -d \
  --restart on-failure \
  -e POSTGRES_USER=<username> \
  -e POSTGRES_PASSWORD=<password> \
  -e POSTGRES_DB=postgres \
  -v ./data:/var/lib/postgresql/data \
  -p 5432:5432 \
  ghcr.io/ferretdb/postgres-documentdb:17-0.108.0-ferretdb-2.8.0
```

--------------------------------

### Connect to PostgreSQL using Docker Exec

Source: https://docs.ferretdb.io/v2.8/installation/evaluation

Access the PostgreSQL database running inside the FerretDB container using `psql`. Replace `<username>` with your PostgreSQL username.

```bash
docker exec -it ferretdb psql -U <username> postgres

```

--------------------------------

### Select documents where stock is not less than 5

Source: https://docs.ferretdb.io/v2.8/reference/operators/query/logical-operators

Use the $not operator to exclude documents that match a specific condition. This example selects documents where the 'stock' field is not less than 5.

```javascript
db.catalog.find({
  stock: {
    $not: {
      $lt: 5
    }
  }
})
```

--------------------------------

### Run dataSize command in diff-proxy mode

Source: https://docs.ferretdb.io/v2.8/migration/premigration-testing

Execute the `dataSize` command in `diff-proxy` mode to observe the response handled by MongoDB.

```javascript
db.runCommand({ dataSize: '<DB-NAME>.locations' })
```

--------------------------------

### Insert Initial Document

Source: https://docs.ferretdb.io/v2.8/reference/operators/update/field-update-operators

Inserts a sample employee document into the 'employees' collection for use in update operations.

```javascript
db.employee.insertOne({
  name: 'John Doe',
  age: 35,
  email: 'johndoe@example.com',
  phone: '123-456-7890',
  address: {
    street: '123 Main St',
    city: 'Anytown',
    state: 'CA'
  },
  salary: 50000,
  jobTitle: 'Manager',
  startDate: new Date('2021-01-01'),
  endDate: null
})

```

--------------------------------

### Update DocumentDB Extension in PostgreSQL

Source: https://docs.ferretdb.io/v2.8/installation/documentdb/deb

After installing the new DEB package, run this command from within the `postgres` database to update the DocumentDB extension. This ensures compatibility with the new FerretDB version.

```bash
sudo -u postgres psql -d postgres -c 'ALTER EXTENSION documentdb UPDATE;'
```

--------------------------------

### MongoDB Client Connection URI

Source: https://docs.ferretdb.io/v2.8/installation/evaluation

Use this MongoDB URI to connect to the running FerretDB instance from any MongoDB client application. Replace `<username>` and `<password>` with the credentials used when starting the container.

```mongodb
mongodb://<username>:<password>@127.0.0.1:27017/

```

--------------------------------

### Configure pg_hba.conf for Replication Access

Source: https://docs.ferretdb.io/v2.8/guides/replication

Appends a rule to the `pg_hba.conf` file in the primary PostgreSQL instance to allow the 'replicator' user to connect from any IP address using MD5 password authentication for replication purposes.

```bash
echo 'host replication replicator 0.0.0.0/0 md5' >> /var/lib/postgresql/data/pg_hba.conf
```

--------------------------------

### Connect to FerretDB with mongosh

Source: https://docs.ferretdb.io/v2.8/installation/ferretdb/kubernetes

Connect to your locally forwarded FerretDB instance using the `mongosh` client. Replace placeholders with your actual credentials.

```bash
mongosh mongodb://<username>:<password>@127.0.0.1:27017/
```

--------------------------------

### Select Documents by Field Data Type using $type with BSON Type Alias

Source: https://docs.ferretdb.io/v2.8/reference/operators/query/element-operators

This example shows an alternative way to query documents where the 'discount' field is of boolean type, using the 'bool' alias.

```javascript
db.electronics.find({
  discount: {
    $type: 'bool'
  }
})
```

--------------------------------

### Select Documents by Field Data Type using $type with BSON Type Code

Source: https://docs.ferretdb.io/v2.8/reference/operators/query/element-operators

This example demonstrates how to query documents where the 'discount' field is of boolean type using its BSON type code (8).

```javascript
db.electronics.find({
  discount: {
    $type: 8
  }
})
```

--------------------------------

### Insert Initial Document for $pop

Source: https://docs.ferretdb.io/v2.8/reference/operators/update/array-update-operators

Inserts a document with an array into the 'products' collection to demonstrate the $pop operator.

```javascript
db.products.insertMany([
  { _id: 1, items: ['pens', 'pencils', 'paper', 'erasers', 'rulers'] }
])
```

--------------------------------

### Select documents that do not match any of the specified conditions

Source: https://docs.ferretdb.io/v2.8/reference/operators/query/logical-operators

The $nor operator selects documents that fail to match any of the provided conditions. This example selects documents where it's not true that (discount is true AND stock is not 0) AND price is not less than or equal to 60.

```javascript
db.catalog.find({
  $nor: [
    {
      $and: [
        {
          discount: true
        },
        {
          stock: {
            $ne: 0
          }
        }
      ]
    },
    {
      price: {
        $lte: 60
      }
    }
  ]
})
```

--------------------------------

### Create Vector Index

Source: https://docs.ferretdb.io/v2.8/guides/vector-search

Use the `createIndexes` command to define and create a vector index. Specify the collection name, index name, the path to the vector field, and detailed `cosmosSearchOptions` based on the chosen index kind.

```javascript
db.runCommand({
  createIndexes: '<collectionName>',
  indexes: [
    {
      name: '<indexName>',
      key: {
        '<path>': 'cosmosSearch'
      },
      cosmosSearchOptions: {
        kind: '<kind>',
        similarity: '<similarity>',
        dimensions: '<dimensions>',

        // HNSW only
        m: '<m>',
        efConstruction: '<efConstruction>',

        // IVF only
        numLists: '<numLists>'
      }
    }
  ]
})
```

--------------------------------

### Restart Replica Instance

Source: https://docs.ferretdb.io/v2.8/guides/replication

Restart the replica PostgreSQL instance to apply the configuration changes.

```bash
docker restart postgres_replica  
```

--------------------------------

### List All Indexes in a Collection

Source: https://docs.ferretdb.io/v2.8/usage/indexes

Retrieves and displays all indexes associated with the 'products' collection, including default and user-created indexes.

```javascript
db.products.getIndexes()
```

--------------------------------

### Apply FerretDB Configuration to Kubernetes

Source: https://docs.ferretdb.io/v2.8/installation/ferretdb/kubernetes

Use this command to apply the `ferretdb.yaml` configuration to your Kubernetes cluster.

```bash
kubectl apply -f ferretdb.yaml
```

--------------------------------

### Check Replication Status on Primary

Source: https://docs.ferretdb.io/v2.8/guides/replication

Inspect the replication status on the primary PostgreSQL server to confirm the replica is connected and streaming.

```sql
SELECT * FROM pg_stat_replication;
```

--------------------------------

### Connect with MongoDB Shell

Source: https://docs.ferretdb.io/v2.8/installation/evaluation

Connect to the FerretDB instance using the MongoDB Shell. Ensure you replace `<username>` and `<password>` with your credentials.

```bash
mongosh mongodb://<username>:<password>@127.0.0.1:27017/

```

--------------------------------

### Kubernetes Deployment and Service Configuration

Source: https://docs.ferretdb.io/v2.8/installation/ferretdb/kubernetes

This YAML file defines the Kubernetes Deployment for FerretDB and a Service to expose it. Ensure to replace placeholder credentials.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ferretdb
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ferretdb
  template:
    metadata:
      labels:
        app: ferretdb
    spec:
      containers:
        - name: ferretdb
          image: ghcr.io/ferretdb/ferretdb:2.8.0
          ports:
            - containerPort: 27017
          env:
            - name: FERRETDB_POSTGRESQL_URL
              value: postgres://<username>:<password>@postgres:5432/postgres

---
apiVersion: v1
kind: Service
metadata:
  name: ferretdb
  labels:
    app: ferretdb
spec:
  selector:
    app: ferretdb
  ports:
    - port: 27017
      targetPort: 27017

```
Tokens:
Raw