---
name: mongodb-and-indexes
description: Design MongoDB prerequisites and index strategy for tibi website projects. Covers replica-set requirements, collection index modeling, text/search index implications, index auto-management on reload, and operator checks for persistence, backups, and regeneration-sensitive features.
---

# mongodb-and-indexes

## When to use this skill

Use this skill when:

- a project moves beyond simple demo data and needs deliberate MongoDB design
- collections need unique, text, sparse, or compound indexes
- search, audit, or larger datasets introduce operational database requirements
- operators need clarity about replica-set, persistence, or backup assumptions

## Goal

Give later agents one place for MongoDB prerequisites and index strategy.

This skill exists because tibi projects do not just “use MongoDB”. They rely on config-driven indexes, reload-time index reconciliation, and environment choices that can help or break production behavior.

## Source of truth

Use these sources when implementing or reviewing MongoDB/index decisions:

- `tibi-server/docs/02-configuration.md`
- `tibi-server/docs/04-collections.md`
- `tibi-server/docs/12-deployment.md`
- active project/server config

## MongoDB prerequisites

Current upstream deployment requirements include:

- MongoDB 4.4+
- replica set for transactions

That means later agents should not promise production-like behavior while ignoring the actual database topology.

For this starter family, check explicitly:

- which MongoDB version is targeted
- whether the environment runs as a replica set
- where persistent data lives
- how backup and restore are expected to work

## Index ownership model

Indexes can be defined in two places.

### Field-level indexes

Use for simple per-field indexes:

```yaml
fields:
    - name: email
      type: string
      index:
          - single
          - unique
```

Available field-level flags include:

- `single`
- `unique`
- `text`
- `sparse`

### Collection-level indexes

Use for compound or more explicit index definitions:

```yaml
indexes:
    - name: category_publish_date
      key:
          - category
          - -publishDate
      background: true
    - name: title_text
      key:
          - $text:title
      defaultLanguage: german
```

Use collection-level indexes when:

- sort patterns span multiple fields
- uniqueness depends on more than one field
- you need text-index language control
- the index needs a stable explicit name

## Important auto-management behavior

On project setup or reload:

1. configured indexes are created
2. indexes present in MongoDB but no longer in config are dropped
3. `_id_` is never dropped

This is a critical workflow fact.

Do not treat indexes as one-off manual DBA work while also expecting config reload to stay authoritative. In this stack, the YAML config owns the intended index state.

## Search and index interplay

Some search modes depend directly on index strategy:

- `mode: text` requires a text index
- explicit text search can use field-level `index: [text]` or collection-level `$text:` indexes
- regex fallback can become expensive without deliberate field/index choices
- enrichment-based modes such as `ngram` and `vector` add `_search` data and may require regeneration workflows rather than classic MongoDB indexes alone

Keep classic indexes and search config aligned. Search should not be modeled in isolation from database cost and reload behavior.

## Query shape matters

Before adding indexes, inspect the real access patterns:

- which fields appear in permission filters
- which fields appear in list sorting
- which fields appear in frequent admin or public lookups
- whether uniqueness is a real business rule or only a nice-to-have

Index design should follow concrete read and write patterns, not schema aesthetics.

## Operational decisions

At project-delivery level, document these choices explicitly:

- MongoDB version and topology
- replica-set availability
- persistence location for database and uploads
- backup/restore responsibility
- whether audit/search features introduce extra operational expectations

If these decisions are absent, later agents tend to over-focus on schema YAML while missing the operator-critical data layer.

## Anti-patterns

- adding indexes without checking actual query or sort behavior
- relying on manual indexes that the config will later drop
- enabling text search without provisioning the needed text index
- treating replica-set requirements as optional trivia
- shipping production projects without a backup and restore story

## Verification checklist

After MongoDB/index-related changes, verify all of these:

1. the target environment satisfies MongoDB version and replica-set needs
2. configured indexes match real query, sort, and uniqueness requirements
3. project reload succeeds after index changes
4. text/search features have the required index support
5. persistence and backup assumptions are documented

## What an LLM should inspect first

When asked to design or review the data layer on this starter, inspect in this order:

1. `tibi-server/docs/12-deployment.md`
2. `tibi-server/docs/02-configuration.md`
3. `tibi-server/docs/04-collections.md`
4. current collection YAML for indexes/search
5. actual query, sort, audit, and search requirements

This keeps index design tied to real runtime behavior and not just to field definitions.