typo3db_legacy for TYPO3

Why typo3db_legacy has been a security risk for every extension since TYPO3 v12

TYPO3 completely switched its database abstraction to Doctrine DBAL with version 8. The old API via $GLOBALS['TYPO3_DB'] was marked as deprecated from v9 and has been fully removed since v12. Despite this, thousands of TYPO3 installations in practice run extensions still based on the legacy API. typo3db_legacy keeps these extensions alive by recreating the old API as a compatibility layer.

The problem: the extension is not a permanent solution but a bridge. Each subsequent TYPO3 version increases the risk that the compatibility layer itself breaks. Anyone still using typo3db_legacy today faces a clear decision - migrate or risk the upgrade to v13.

Typical use cases

Custom extensions with direct database access. Many agencies wrote extensions between 2012 and 2018 that call $GLOBALS['TYPO3_DB']->exec_SELECTquery() directly. In a typical mid-market installation, 3 to 8 such extensions can be found. Without typo3db_legacy, they would immediately fail with fatal errors after an update to v10+.

Third-party extensions without active maintainer. Extensions like older versions of tt_address add-ons, industry directories or specialized import tools were often maintained by solo developers. If the maintainer is no longer active, typo3db_legacy is the only option to preserve functionality during the upgrade.

Staged migration of large installations. Organizations with 50+ extensions cannot migrate everything simultaneously. typo3db_legacy allows a step-by-step approach: first perform the core upgrade, then convert extension by extension to Doctrine DBAL. Gosign plans such migrations in sprints of 3 to 5 extensions each, prioritized by business criticality and dependencies.

Technical architecture

typo3db_legacy registers as a TYPO3 extension and provides the class TYPO3\CMS\Typo3DbLegacy\Database\DatabaseConnection. This class implements the same methods as the old DatabaseConnection from the TYPO3 Core: exec_SELECTquery(), exec_INSERTquery(), exec_UPDATEquery(), exec_DELETEquery() and the associated prepared statement variants.

Internally, the layer forwards all calls to Doctrine DBAL. This works reliably for standard queries. It becomes problematic with:

• Direct MySQL functions in queries (e.g. GROUP_CONCAT, database-specific syntax)
• Prepared statements with named parameters in the old format
• Transaction handling via the old API that does not map 1:1 to Doctrine
• Performance: every query passes through an additional abstraction layer with 5-15% overhead

The extension has no dependencies other than the TYPO3 Core itself. It simply needs to be installed via Composer (typo3/cms-typo3db-legacy) or the Extension Repository.

An important architectural aspect: typo3db_legacy was designed as a temporary measure. The code deliberately contains no optimizations that would make it longer-lived. There is no query caching on the compatibility layer, no connection pooling integration and no support for advanced Doctrine DBAL features like Expression Builder or custom type mappings. The design goal was: keep old queries running until they are migrated.

Common problems and solutions

Extension does not work despite typo3db_legacy after upgrade. The cause is usually that the extension uses not only $GLOBALS['TYPO3_DB'] but also other removed APIs like $GLOBALS['TSFE']->sys_page in old form or deprecated hook registrations. The solution requires a complete code analysis of the extension, not just the database calls. A scan with the TYPO3 Extension Scanner provides a prioritized list of all affected locations. Gosign performs such scans as an inventory before the actual upgrade begins - typical effort: 2 to 4 hours per installation with a report on all affected extensions and estimated migration effort.

Queries return different results than before the upgrade. Doctrine DBAL handles types more strictly than the old mysqli-based API. A WHERE uid = '5' (string instead of integer) can lead to unexpected behavior in edge cases. Solution: check all queries for correct PHP types and set casts explicitly.

Performance drop after installation. Installations with more than 100,000 records and frequent queries experience the overhead of the double abstraction measurably. Here, only the complete migration to Doctrine DBAL with QueryBuilder helps, making the layer unnecessary.

Migration and version compatibility

typo3db_legacy was an official part of the TYPO3 Core through version 9.5 LTS. For TYPO3 v10 and v11, the extension existed as a separate Composer package. For TYPO3 v12 LTS, there is no officially supported release. Unofficial forks on GitHub attempt to establish compatibility but are tested by neither the Core team nor the Extension Owners group.

For TYPO3 v13, no compatibility layer is planned or realistic. The database layer has changed too significantly with the upgrade to Doctrine DBAL 4.0. Anyone using typo3db_legacy who wants to upgrade to v13 cannot avoid a complete migration.

The recommended migration path: every exec_SELECTquery() call is rewritten to use the Doctrine DBAL QueryBuilder. A typical extension with 10 to 20 query calls can be migrated in 4 to 8 hours. Gosign uses automated code analysis that identifies all legacy API calls and suggests migration code. For complex extensions with dynamically assembled queries, the effort increases to 2 to 3 days per extension.

The most common rewrites in detail: exec_SELECTquery() becomes $queryBuilder->select()->from()->where()->executeQuery(). exec_INSERTquery() becomes $connection->insert(). exec_UPDATEquery() becomes $connection->update(). The pattern is consistent, but each query must be individually reviewed because the old code frequently concatenates strings that the QueryBuilder expects as separate parameters. Particularly tricky: queries with dynamic WHERE clause construction where conditions are appended via loops. These require a complete restructuring of the logic.