The DB Schema Compare Utility explained

The DB Schema Compare Utility compares the database schema of your primary VICIdial database server against a secondary, cold-storage, or alt-log database server, and reports any tables, columns, or row counts that do not match.

Which database servers it covers

Larger VICIdial installations run more than one database server. The utility lets you compare the primary database against any of the following:

• Secondary database server — the hot replica that takes over if the primary fails, or that handles read traffic in a load-balanced setup. This is the most important one to keep in sync because a schema drift here means a silent failover could take your entire system offline.
• Cold-storage database server — a separate server used for archiving older call records and Call recording data that would otherwise grow the primary database indefinitely. Schema drift here typically shows up as import failures when you try to restore archived records.
• Alt-log database server — an alternate logging server that captures VICIdial log activity separately from the main transaction database. Drift here causes gaps in your Agent performance history and your call records.

You select the target server from a drop-down, then submit. The utility queries both the primary and the selected server and returns a structured comparison. Only one target can be checked per run — to check the secondary and the cold-storage server in the same session, use the utility twice.

The three result sections

Results arrive in three distinct sections, each answering a different structural question:

• TABLES LIST — which tables exist on each server. A table present on the primary but absent on the secondary appears here, which is the first sign of a partial migration or a replication failure that skipped a CREATE TABLE statement.
• TABLE ROW COUNTS — how many rows each shared table holds on each server. A gap here suggests replication lag, a failed data sync, or a bulk operation that ran on the primary and did not replicate cleanly.
• TABLE FIELD COUNTS — how many columns each table has on each server. A mismatch here means an ALTER TABLE ran on one server but not the other, which is the root cause of 'Unknown column' errors in the VICIdial logs.

Read the sections in order — tables first, then field counts, then row counts. A missing table is a harder problem than a missing column, and a missing column is a harder problem than a row gap. Starting from the top tells you the most urgent issue to fix first.

flowchart TD
  A["DB Schema Compare Utility"] --> B["Select target server"]
  B --> C["Secondary / Cold-storage / Alt-log"]
  C --> D["Compare against primary"]
  D --> E["TABLES LIST"]
  D --> F["TABLE ROW COUNTS"]
  D --> G["TABLE FIELD COUNTS"]
  E --> H{"Missing table?"}
  F --> I{"Row count gap?"}
  G --> J{"Column count differs?"}
  H -->|Yes| K["Partial migration or replication failure"]
  I -->|Yes| L["Replication lag or failed sync"]
  J -->|Yes| M["ALTER TABLE ran on one server only"]

When to run it

Run the DB Schema Compare Utility after any upgrade to VICIdial, after any migration that involved schema changes, and any time you see 'Unknown column' errors in the application or in your agent logs. It is also worth running after a secondary server failover event to confirm the server that took over is fully in sync before you rely on it as a live replica. Many teams add it to their post-upgrade checklist alongside a quick Real-time report check, so a schema drift is caught within minutes rather than discovered under load.

The Server snapshot and backup processes that run alongside VICIdial also depend on consistent schema. A mismatch caught here early prevents a silent corruption that could surface days later during a restore. A row-count gap in the Lead tables is one of the more damaging kinds of drift — it means leads that exist on the primary are invisible to any system querying the secondary, which can look like leads running out when they have not.

Schema health is part of the broader discipline of monitoring VICIdial server health and capacity. If the compare surfaces a replication lag you want to contextualize against server load at that time, how to read the Server Performance Report shows you the timeline of load and channel activity to cross-reference.

On a VICIfast managed server, database maintenance and replication health are monitored for you. Start a VICIfast trial and your VICIdial instance is live in under 40 seconds with observability tools available from first boot.