How Joomla Extension SQL Update Files Work
SQL updates are declared by the extension manifest
Joomla extension manifests can define install SQL, uninstall SQL, and an update schemas path. The update path points to a directory of numbered SQL files for a particular database driver. This lets an extension evolve its database structure or data as administrators install newer releases.
Initial installation establishes a baseline
Joomla Programmer Documentation explains that on an initial install Joomla does not execute the SQL update files. If update files exist, Joomla orders their filenames numerically and records the highest filename, without the .sql extension, as that extension's version_id in #__schemas. If no update files exist, no schema record is created for that extension.
Updates start from the stored schema version
When an already-installed extension is updated, Joomla retrieves its current SQL version from #__schemas. It reads the files in the configured schemas directory, orders them numerically, and processes update files whose filename versions come after the stored version.
Joomla advances the schema record after processing
After processing the applicable SQL update files, Joomla stores the filename of the last processed update in the extension's #__schemas record. Administrators can therefore skip extension releases as long as the package provides the necessary ordered migration path and the extension itself supports that upgrade path.
Manifest version and SQL version are separate
The extension version from the manifest is stored in manifest_cache in #__extensions, while the SQL schema version is stored in version_id in #__schemas. Joomla treats these as distinct values and does not correlate them automatically. Developers often keep them aligned because doing so makes update state easier to understand.
SQL filenames use numerical ordering
Joomla compares update filenames numerically, so version-like filenames should be chosen consistently. This matters when a package contains several migrations. The ordering determines which files Joomla regards as later than the stored schema version.
Do not bypass a failed migration by editing #__schemas
Raising version_id without applying the underlying migration can cause Joomla to skip SQL the database still needs. If an update fails, preserve a backup, identify the failed migration, and prefer the extension developer's supported reinstall or repair path rather than falsifying the schema state.
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.