occ db:* commands – quick reference

These commands are part of the Nextcloud OCC (OwnCloud Console) CLI. They help keep the database schema in sync with the code base. Use them after pulling a new release, after upgrading PHP or after installing an app that adds new tables/fields.

1. occ db:add-missing-indices

What it does Scans the database for foreign‑key or index definitions that are missing compared with the current application code and creates them.

When to run it

• After a fresh install or upgrade where the schema may be out‑of‑date.
• When you suspect referential integrity problems (e.g., “missing index” warnings in the log).

How to use

# Switch to the web‑server user (usually www-data) and run:
sudo -u www-data php /var/www/nextcloud/occ db:add-missing-indices

The command will output a short summary, e.g.:

Added 3 missing indices.

If nothing is reported, the schema already contains all required indices.

2. occ db:add-missing-columns

What it does Looks for columns that exist in the code definition but are absent from the database, then adds them.

When to run it

• After a core upgrade or an app update that introduces new fields.
• When you see errors like “column does not exist” in the Nextcloud logs.

How to use

sudo -u www-data php /var/www/nextcloud/occ db:add-missing-columns

Typical output:

Added 2 missing columns.

3. occ db:add-missing-primary-keys

What it does Ensures that every table that should have a primary key actually does, creating the key if it is missing.

When to run it

• Rarely needed on a healthy installation, but useful after a corrupted database restore or when manually fixing schema issues.

How to use

sudo -u www-data php /var/www/nextcloud/occ db:add-missing-primary-keys

Result example:

Added primary key to table `oc_filecache`.

4. occ db:convert-filecache-bigint

What it does Migrates the filecache table from the legacy INTEGER type to BIGINT(20) to support very large file IDs (required for installations with >2 billion files).

When to run it

• After upgrading to Nextcloud 24+ where this migration is mandatory.
• When you encounter “invalid identifier” or “numeric overflow” errors in the log.

How to use

sudo -u www-data php /var/www/nextcloud/occ db:convert-filecache-bigint

The command prints progress and finishes with:

Converted filecache to BIGINT.

Note: The conversion can take a long time on very large installations; it is safe to run on a live system but you may want to schedule it during low‑traffic periods.

General tips for using these commands

1. Always back up first – take a dump of the database (mysqldump) before running any schema‑modifying command.
2. Run as the web‑server user – www-data (or the user defined by httpd.service/php-fpm).
3. Check the log – after execution, review /var/www/nextcloud/data/nextcloud.log for any warnings.
4. Combine with maintenance mode – if you are performing a major upgrade, enable maintenance mode first:

   sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --on
   # …run db:* commands…
   sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --off

1. Verify the version – the commands are only available from Nextcloud 23 onward; older installations may need a manual schema upgrade.

What to check next?

• If any of the commands report errors, look at the Nextcloud log (data/nextcloud.log) for the exact message.
• Confirm that the database user used by Nextcloud has sufficient privileges (CREATE, ALTER, INSERT).
• Ensure you are using the correct path to occ (usually /var/www/nextcloud/occ).

These steps will keep your database schema healthy and prevent the typical “missing index/column” warnings that can appear after upgrades.