Apply MongoDB indexes with the CLI

Written by UUG.AI Created Nov 4, 2026 Updated Nov 4, 2026

MongoDB indexes support the queries that Hub uses to find devices, recordings, markers and other resources. When a release introduces a new query, its supporting indexes may need to be installed before the application rollout.

The UUG.AI CLI provides a check-indexes action that compares your database with a versioned index specification. The safe operating sequence is choose a contract, dry-run, review, apply, then dry-run again.

Before you start

You need:

• The exact MongoDB connection URI and database name for the intended environment.
• Network access to MongoDB, including its TLS and authentication requirements.
• A database account allowed to list indexes; applying indexes also requires createIndex privileges on the target collections.
• A tested CLI checkout or container image that contains the required specification.
• For a local source run, Git, the Go version required by the checkout’s go.mod, and access to its dependencies.
• For a cluster run, kubectl access to the intended namespace and a Secret containing the connection URI.

Test in staging first. For production, confirm backups, available disk space and an appropriate change window. Index builds consume CPU, memory and I/O; duration depends on collection size and database load, not the tutorial’s reading time.

This action installs indexes, not a data migration. It does not backfill ownership fields or change how legacy resources belong to an organisation or project. Do not remove legacy-query indexes merely because canonical ownership indexes also exist.

Understand what the checker changes

The checker matches ordered index keys, uniqueness and the partial filter expression. An equivalent index under a different name counts as present. Changing compound-key order is not equivalent.

It does not drop extra indexes, rename existing indexes or replace conflicting definitions. It is an additive checker, not a complete database-schema reconciler.

Choose the right index version

Browse the CLI’s index specifications, preferably at the tag or commit you will run.

The migration- prefix does not make check-indexes migrate documents. These files can also describe runtime-query indexes that should be applied before deploying a feature.

The version is a filename stem, not a path. For example:

-index-version migration-hub-workflow-device-groups-08-10-2026

resolves to:

indexes/migration-hub-workflow-device-groups-08-10-2026.txt

Do not pass the indexes/ prefix or .txt suffix. The CLI loads the file relative to its working directory. Always specify the version explicitly: the current fallback is the older hub-08-12-2025, not automatic discovery of the latest file.

A baseline is not a promise to include every later feature-specific contract. Follow your release instructions for any additional sets. Likewise, do not apply every historical file indiscriminately.

The worked example below installs the focused workflow device-group lookup contract for groups and sites. Substitute the version and collections required by your deployment.

Apply indexes from a local checkout

git clone https://github.com/uug-ai/cli.git
cd cli

read -r -s -p 'MongoDB URI: ' MONGODB_URI
printf '\n'

MONGODB_DATABASE='Kerberos'
INDEX_VERSION='migration-hub-workflow-device-groups-08-10-2026'
INDEX_COLLECTIONS='groups,sites'

test -f "indexes/${INDEX_VERSION}.txt"

go run . -action check-indexes \
  -mongodb-uri "$MONGODB_URI" \
  -mongodb-destination-database "$MONGODB_DATABASE" \
  -collections "$INDEX_COLLECTIONS" \
  -index-version "$INDEX_VERSION" \
  -mode dry-run

[summary] missing_total=4 mode=dry-run
[info] dry-run mode: skipping index creation and prompts.

go run . -action check-indexes \
  -mongodb-uri "$MONGODB_URI" \
  -mongodb-destination-database "$MONGODB_DATABASE" \
  -collections "$INDEX_COLLECTIONS" \
  -index-version "$INDEX_VERSION" \
  -mode live

[ok] all canonical indexes present across checked collections.

Run the same workflow in Kubernetes

Running a Job inside the cluster is useful when MongoDB is reachable only over internal DNS. The CLI flags and verification requirements are identical; no public database endpoint is needed.

Use a pinned CLI image tag or digest that contains the selected specification. The repository’s Job template is a starting point, not a guarantee that its image includes a newer contract.

Prepare a dry-run Job

In your target namespace, provision an existing Secret named hub-index-check with a mongodb-uri key through your normal secret-management process. Do not paste credentials into the manifest.

Save this as index-check.yaml, replacing <tested-tag> with your approved CLI image tag and adjusting the database, contract and collections:

apiVersion: batch/v1
kind: Job
metadata:
  name: hub-indexes-dry-run
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: check-indexes
          image: ghcr.io/uug-ai/cli:<tested-tag>
          workingDir: /
          command: ["/main"]
          args:
            - "-action"
            - "check-indexes"
            - "-mongodb-uri"
            - "$(MONGODB_URI)"
            - "-mongodb-destination-database"
            - "Kerberos"
            - "-collections"
            - "groups,sites"
            - "-index-version"
            - "migration-hub-workflow-device-groups-08-10-2026"
            - "-mode"
            - "dry-run"
          env:
            - name: MONGODB_URI
              valueFrom:
                secretKeyRef:
                  name: hub-index-check
                  key: mongodb-uri

Kubernetes expands $(MONGODB_URI) in the argument from the Secret-backed environment variable; this is not automatic CLI environment-variable support. The official image includes its specifications under /indexes. Add an image pull Secret if your registry access requires one.

Run and review

Confirm your Kubernetes context, then set the intended namespace:

kubectl config current-context
NAMESPACE='your-hub-namespace'

kubectl -n "$NAMESPACE" create -f index-check.yaml
kubectl -n "$NAMESPACE" logs -f job/hub-indexes-dry-run
kubectl -n "$NAMESPACE" wait \
  --for=condition=complete job/hub-indexes-dry-run --timeout=10m

If the Pod is not ready when you request logs, inspect it with kubectl -n "$NAMESPACE" get pods, resolve any scheduling or image-pull issue, then read the logs again. A wait timeout does not cancel the Job or establish whether indexes are present.

Review the report using the same checklist as the local dry run. Kubernetes marking the Job Complete is not sufficient proof of success.

Apply and verify with separate Jobs

After review, make a second manifest with only these changes:

• Set metadata.name to hub-indexes-live.
• Change the -mode argument’s value to live.

Create that Job, follow its logs, and wait for completion. Allow enough time for the actual collection sizes. Keep the image, URI Secret, database, version and collection selection the same.

Finally, create a third Job named hub-indexes-verify with -mode dry-run. Confirm the all-present message and the absence of errors or skipped collections before continuing the rollout.

Use a new name for each Job, including later reruns: existing Job Pod arguments are immutable, so changing -mode on a completed Job with kubectl apply is not the workflow.

Troubleshooting

Further reading

• Check indexes command reference
• CLI overview
• Versioned index specifications
• CLI release and feature-specific instructions