How Joomla Extension SQL Update Files Work
Joomla extensions can use numbered SQL update files to evolve their database schema across releases. The extension manifest declares the schema-update location, Joomla tracks SQL migration progress in jossa_schemas, and that schema version is separate from the extension version stored with its installed-extension metadata.
The extension manifest defines the update path
An extension manifest can define installation SQL, uninstall SQL, and a schema/update path for supported database drivers. The update path points Joomla to numbered SQL files that can add or alter tables, indexes, columns, or data as the extension evolves.
Initial installation establishes the schema baseline
When an extension uses Joomla's schema-update mechanism, the initial installation establishes the database from the package's install process and Joomla records a schema baseline from the available update-file sequence. The exact package should therefore contain a coherent install schema plus the migration history needed for later updates.
Later updates start from the stored schema version
- Joomla identifies the installed extension and its recorded SQL schema state.
- It reads the numbered SQL files in the manifest-declared update path.
- It determines which files are later than the stored schema version.
- Applicable migrations are processed in version order.
- The schema record is advanced to represent the last migration processed.
This allows an extension package to carry a migration path across multiple releases instead of requiring every administrator to upgrade through each intermediate package manually.
Manifest version and SQL schema version are different
The human-facing extension version comes from manifest metadata associated with the installed extension record. The SQL migration version is stored separately in jossa_schemas.version_id. Developers may keep the numbers similar, but administrators should not assume that one proves the other.
Why failed migrations require care
If a migration fails after files have been replaced, the extension code can be newer than the database. Manually raising version_id can make later updates skip SQL that never completed. Conversely, rerunning migration SQL without checking current structure can produce duplicate-column or duplicate-index errors.
Preserve a database-and-files backup and establish the actual migration state before repair.
How to verify an extension's update state
- Record the extension's element, installed version, and
extension_id. - Read its schema
version_id. - Inspect the exact package's declared update directory and numbered SQL files.
- Compare the expected migrations with the real table structure.
- Use the vendor's supported update or repair path if those facts disagree.
The safest schema state is one that accurately represents migrations that actually ran—not merely the newest filename present in the package.
Need More Help with Joomla?
Still having trouble? Open a support ticket with QuantaCade Support and we'll be happy to help where we can.
Support priority is given to QuantaCade products, services, and customers. However, we're also happy to assist fellow Joomla users with general Joomla questions and troubleshooting when possible.
QuantaCade is an independent Joomla extension developer and is not official Joomla support. Some issues involving third-party extensions, hosting environments, server configurations, or other systems outside our development control may be beyond what we're able to resolve.