Skip to content
Documentation
Operations
Admin Tools

Admin Tools

Overview

Cavaliba provides a built-in Admin Tools interface for system administrators to perform critical maintenance and operational tasks. These tools are accessible from the administration dashboard and require the p_admintools permission.

Access the Admin Tools with the admintool sidebar button or at /private/admintools/

Permissions

All Admin Tools require the p_admintools permission. This permission should only be granted to trusted system administrators. It is available to all admin users.

To check and manage admin permissions:

  1. Navigate to Administration > Roles
  2. Grant the p_admintools permission to selected roles
  3. Map individual users and/or group to selected roles

Available Tools

Counters (Schema Counters & BigSet Update)

Purpose: Update schema counters and bigset status for all schemas

When to use:

  • After bulk data operations (imports, migrations)
  • When schema statistics appear out of sync
  • During routine maintenance

Command: Click the “Counters” button

What it does:

  • Recalculates instance count for each schema
  • Updates bigset cache status
  • Refreshes schema statistics used by the UI for pagination

Impact: Negligible. Safe to use.

Alternative: this task is included in the automatic daily housekeeping.

EAV Refresh

Purpose: Rebuild the Entity-Attribute-Value (EAV) cache for improved query and filtering responses

When to use:

  • When out of sync response / missing new entries in filtering

Command: Click the “EAV Refresh” button

What it does:

  • Rebuilds the complete EAV cache from the database

Impact: Long-running task. System performance may be temporarily reduced. Cache will be fully rebuilt after completion.

Note: This is an async task that runs in the background. Progress can be monitored in the application logs.

Alternative: this task is included in the automatic daily housekeeping.

EAV Purge

Purpose: Clear the EAV cache to remove orphan entries and improve queries and filtering

When to use:

  • When cache may be corrupted

Command: Click the “EAV Purge” button

What it does:

  • Recreates all cache entries from main Database

Impact: Long-running task. System performance may be temporarily reduced. Cache will be fully rebuilt after completion.

Note: This is an async task that runs in the background. Progress can be monitored in the application logs.

Alternative: this task is included in the automatic daily housekeeping.

Rename a keyname

Purpose: Rename an instance keyname and cascade the change to every instance that references it through a schema-type field

Permissions: p_admintools to reach the page, plus p_keyname_rename to perform the rename. Without the latter the page renders but the form is hidden.

When to use:

  • An instance identifier was mistyped or a naming convention changed
  • A keyname must follow a renamed upstream object

Command: Click the “Rename a keyname” button, then:

  1. Select the schema, type the current keyname and the new keyname
  2. Click Dry run — this step is mandatory and writes nothing
  3. Review the report: referrers scanned, referrers changed, per-schema breakdown, and the exact field-by-field before/after list
  4. Either New dry run (adjust and re-check) or Run for real (confirmation modal)

What it does:

  • Renames the target DataInstance keyname
  • Rewrites every referring instance’s schema-type field that pointed at the old keyname
  • Rebuilds the affected EAV cache rows and records a keyname revision on the target

Refusals (reported in the dry run, nothing written):

  • Keyname not found, or new keyname already taken
  • New keyname identical to the current one
  • The instance is is_builtin
  • A protected built-in identity (user/admin, role_admin, role_default) — refused even with force
  • A user, group or role instance, unless the Force checkbox is ticked

Force: renaming a user, group or role keyname changes an identity — logins and references elsewhere may break. The checkbox is an explicit opt-in.

Impact: The real run is synchronous and writes one update per referring instance. The dry-run report warns when more than 500 instances would be rewritten; for renames of that size, prefer the CLI or API below, which have no web request timeout.

Recovery: No undo other than renaming back. The whole cascade runs in a single database transaction, so a mid-run failure rolls everything back.

Alternatives:

# local CLI
cavaliba keyname --schema server --old srv01 --new srv02 --dryrun

# API
curl -X POST -H "X-Cavaliba-Key: test xxxxx" \
    'http://localhost:8000/api/keyname/?s=server&old=srv01&new=srv02&dryrun=true'

Data Revisions

Purpose: View data revision tracking history

When to use:

  • Audit data changes and modifications
  • Track who changed what and when
  • Investigate data mutation issues
  • Review revision history

Command: Click the “Revision” button

Features:

  • View all recorded data revisions (ordered by most recent first)
  • Pagination support (1000 items per page by default)
  • Columns: ID, Date, Schema, Instance, Action, User
  • Filter by custom page size using ?size=500 parameter

URL Parameters:

  • page: Page number (default: 1)
  • size: Items per page (default: 1000, max: 10000)

Example:

/private/admintools/revision/?page=1&size=500
/private/admintools/revision/?page=2

Factory Reset

Purpose: Empty the whole instance and re-provision a brand new one from the builtin definitions

⚠️ DANGER: This action is irreversible and deletes ALL data

When to use:

  • Development, demo and test environments
  • Fresh system initialization before a first real import

Permissions: p_admintools to reach the page, plus an admin account (the admin user or any user holding the role_admin role). The row and its modal are hidden from non-admin users.

Second factor: the admin account password — the value of the CAVALIBA_ADMIN_PASSWORD environment variable — must be typed in the modal. When that variable is not set on the instance, the feature is unavailable and the button is disabled: a deliberate way to forbid factory resets on a given deployment. (The database password is not used for this: a sqlite instance has none.)

Command: Click “Factory reset” in the Danger zone, type the admin account password, optionally tick Load demo data, then confirm.

What it does, in this order:

  1. Deletes every file in the filestore, export folder and mail/sms spools (.gitignore files are kept)
  2. Deletes every row of every Cavaliba table: schemas and fields, instances, EAV cache, revisions, files, tasks, registry, configuration, logs, API stats, permissions, SMS journal, CMT metrics, sessions
  3. Clears every cache (Redis or database cache tables) and the in-memory caches
  4. Runs the normal start/bootstrap sequence: builtin/init/*.yml provisioning (permissions, schemas, builtin users/groups/roles, dataviews, pipelines, apikey), configuration defaults, then the DB migrations up to the code version
  5. Optionally loads builtin/demo/ (about 3800 objects) exactly like cavaliba load builtin/demo/ would
  6. Recreates your own account (unless you are the builtin admin) and adds it to the role_admin role — only the identity (login, display name, enabled): email, groups and other roles are gone with the rest of the data. Without this an oauth2 administrator would come back as an unknown or permission-less user on the instance they just reset.
  7. Clears the caches again and writes the first log line of the new instance

What survives: the Django-internal tables — local Django accounts (auth_user), content types, admin log and, above all, the migration history. Local logins therefore still work after a reset. The Django admin account password is re-synced from CAVALIBA_ADMIN_PASSWORD as on any start, and locked if that variable is not set.

Impact:

  • Complete data loss. All application data is permanently removed.
  • Every session is dropped: you are logged out and must sign in again. The report page is displayed once, right after the reset.
  • The instance gets a new INSTANCE_UUID.
  • The operation is synchronous. With demo data it may run for a minute or more, which can exceed a reverse-proxy timeout — the reset itself still completes server-side.
  • Queued Celery jobs from before the reset are not purged and will fail on missing objects.

Recovery: none, other than a database backup.

Command-line Alternatives

Most admin tool operations have command-line equivalents accessible via the Django management command:

# EAV operations
cavaliba cache --eav_refresh
cavaliba cache --eav_purge
Backup and restore