Running a VICIdial database schema upgrade

VICIdial code and the VICIdial database schema are a matched pair. When you pull a newer code revision, that code often expects columns, tables, or default values that your current database does not have yet. The fix is the upgrade SQL script: a file of ALTER and INSERT statements that brings your schema forward to match the code. Run it after every code update that needs it, or the agent screen starts throwing database errors.

Why a schema upgrade exists at all

The dialer stores everything in MySQL or MariaDB: campaigns, leads, agents, dispositions, live channel state. As features land, the schema grows. A new column on the campaign table to control a behavior. A new lookup table for a feature. The code that uses those structures and the structures themselves have to exist together. Update one without the other and queries reference columns that are not there.

flowchart TD
  A[Pull newer VICIdial code] --> B{Schema matches code}
  B -->|no| C[Run upgrade SQL script]
  B -->|yes| F[Restart processes]
  C --> D[ALTER add columns and tables]
  D --> E[INSERT new defaults]
  E --> F
  F --> G[Test agent screen]

What the upgrade script does

The upgrade script is ordered. Each block of statements corresponds to a code revision, so the file reads as a timeline of schema changes. ALTER TABLE statements add columns and indexes. CREATE TABLE statements add new structures. INSERT statements seed default settings rows the new code expects to find. You run the portion from your current revision forward, which the maintainers mark clearly so you do not re-apply old changes.

One caution worth internalizing: many VICIdial tables are MyISAM, which has no transaction rollback. If an ALTER fails partway, the changes already applied stay applied. There is no automatic undo at the table level. That is exactly why you take a backup first, so your rollback is a restore, not a prayer.

Run it safely

Back up before you run a single statement. Dump the database with mysqldump to a file you can restore. Better, take a whole-box Server snapshot so a failed upgrade is a one-click revert. Then pipe the upgrade script into the client against the asterisk database and watch for errors. A clean run is quiet. An error mid-run is your signal to stop, restore, and investigate, not to push forward and hope. For the database setup that underpins all of this, see our MySQL and MariaDB setup post.

After the schema is current, restart the dialer processes so the new code loads against the new structures. The cron-managed Keepalive cycle brings the AST scripts back, and you test: log in an agent, place a call, confirm a Disposition saves and a Real-time report updates without database errors. If it is clean, the schema and code agree. The installation guide places this step in the wider upgrade flow.

The order, one more time

Backup, pull code, run the schema script, restart, test. Never the schema before the code, never the code without the schema, never either without a backup. The discipline is boring, and boring is what you want from a database that holds every Lead list you have ever loaded.

On a managed box you keep root SSH and run the schema upgrade yourself when you move your VICIdial revision, on a Single tenant server that is yours alone. We get you there fast: provisioning the box and its database takes under 40 seconds, so you start from a clean, current schema. See plans and pricing.