typo3db_legacy for TYPO3

Why typo3db_legacy is only a bridge for every extension

TYPO3 completely switched its database abstraction to Doctrine DBAL with version 8. The old API via $GLOBALS['TYPO3_DB'] was marked as deprecated in v8 and has been removed from the Core since v9. 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 should plan the migration, even though version 1.3.0 still covers TYPO3 up to v14.

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 v9+.

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 builds SQL strings and sends them over its own mysqli connection; Doctrine DBAL only opens that connection. This works reliably for standard queries. It becomes problematic with:

• Databases other than MySQL and MariaDB, because the layer only speaks mysqli
• Prepared statements, which trigger a deprecation notice on every call
• Transaction handling, because the old API uses a second connection next to the Core’s
• Performance: as soon as an old query runs, the layer opens a second database connection

Besides the TYPO3 Core, the extension only needs the PHP extension mysqli. It simply needs to be installed via Composer (friendsoftypo3/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. The layer itself sends the queries unchanged via mysqli, but type errors in the old code remain. 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 feel the second database connection that the layer opens in addition. Here, only the complete migration to Doctrine DBAL with QueryBuilder helps, making the layer unnecessary.

Migration and version compatibility

The code of typo3db_legacy was part of the TYPO3 Core up to version 8.7 LTS. Since TYPO3 v9, it has been available as a separate extension. The Friends of TYPO3 keep maintaining it: version 1.2.0 supports TYPO3 v10 to v12, version 1.3.0 v12 to v14. Both versions are available in the TER and on Packagist, so there is no need for unofficial forks.

The layer keeps working under TYPO3 v13 as well. The Core’s database layer has moved to Doctrine DBAL 4.0, but the layer talks to mysqli directly. Anyone using typo3db_legacy still cannot avoid a complete migration in the long run.

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.