---
title: "Data Compatibility Across TYPO3 Versions"
manual: "Grid Elements"
version: "main"
permalink: "https://docs.typo3.org/permalink/gridelementsteam/gridelements:upgradingcompatibilitydatacompatibility@main"
source: "Chapters/UpgradingCompatibility/DataCompatibility/Index.rst"
rendered: "2026-11-04T14:20:48+00:00"
---

# Data Compatibility Across TYPO3 Versions {#upgradingcompatibilitydatacompatibility}

The one piece of Grid Elements' data model that is genuinely at risk
during a TYPO3 version upgrade, rather than only during ordinary
editing, is `colPos`.

## The `colPos` issue {#the-colpos-issue}

This is exclusively a database schema matter, not a TCA one.
`tt_content.colPos` has two competing SQL column definitions,
supplied by two different extensions' `ext_tables.sql`:

| Definition | SQL |
| --- | --- |
| TYPO3 Core (`typo3/cms-frontend`) | `colPos int(11) unsigned DEFAULT '0' NOT NULL` |
| Grid Elements | `colPos int(11) DEFAULT '0' NOT NULL` |

Grid Elements' own `ext_tables.sql` deliberately declares the same
column without `unsigned`, because it depends on two negative
sentinel values, `-1` for a grid child and `-2` for an unused
element, to place content outside the page's own Backend Layout
columns, see [Data Model](https://docs.typo3.org/permalink/gridelementsteam/gridelements:datamodel@main) for exactly what each value means and
why. TCA plays no role in this at all; TCA describes how a field is
edited and validated in the backend, not the SQL type of the database
column that stores it. The signed/unsigned distinction is decided
entirely by which `ext_tables.sql` definition for this column ends
up applied to the database.

## Which definition wins {#which-definition-wins}

TYPO3's schema migration (Admin Tools > Maintenance on TYPO3 13 or
System > Maintenance on TYPO3 14, \``typo3
database:updateschema`\`, or equivalent deployment tooling) collects
the `ext_tables.sql` of every currently active extension and
combines them into the set of column definitions it compares the live
database against. As long as Grid Elements is active during that step,
its unsigned-free `colPos` definition is part of that combined set,
alongside Core's `unsigned` one, and Grid Elements' definition is
what actually applies to the column, keeping it signed.

The failure mode only exists if Grid Elements is *not* active during
that step: with its `ext_tables.sql` absent from the combined set,
only Core's `unsigned` definition remains, the schema migration then
sees the live column as merely differing from that definition, and
applying it converts the column back to unsigned. **This conversion
must never be allowed to happen.** If it does, every negative sentinel
value is lost: `colPos` on affected grid children can no longer
record that they are placed in a Grid Element column (`-1`) or
unused (`-2`), so TYPO3 Core's own placement handling and backend
presentation, both of which read `colPos` directly, interpret those
records incorrectly, typically as if they were ordinary page-level
elements. The parent-child relation itself, stored in
`tx_gridelements_container`, is not affected by this and continues
to identify each record as a child of its Grid Element; only what
`colPos` displays about it in the Page and List modules (Web > Page
and Web > List on TYPO3 13, Content > Layout and Content > Records on
TYPO3 14) is wrong.
This is exactly the scenario the Col Pos Fixer's own docblock
describes, see [Upgrade Wizards](https://docs.typo3.org/permalink/gridelementsteam/gridelements:upgradingcompatibilityupgradewizards@main).

There is no need to ever deactivate Grid Elements for a TYPO3 Core
major-version upgrade
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Deactivating, removing, or otherwise taking Grid Elements out of the
picture "for the duration of the upgrade" is not a required or
sensible step, and doing it is what actually creates the risk
described above; it is not something a Core upgrade forces on a
project. Each currently maintained Grid Elements version is built to
support both the TYPO3 version it targets and that version's immediate
predecessor at the same time. This branch's `composer.json` states
that directly: `"typo3/cms-core": "^13.4.7 || ^14.3"`. The same
installed Grid Elements version is already compatible before, during
and after a project runs `composer update` to move its TYPO3 Core
requirement from `^13.4.7` to `^14.3`. There is consequently no
point in that upgrade where Grid Elements needs to be absent, and no
reason for its `ext_tables.sql` to ever drop out of the combined
schema definition set. Where this has gone wrong in practice, it has
been a hosting provider's own automated upgrade process deactivating
extensions it did not recognize as compatible without checking their
actual supported-version range, not a limitation of Grid Elements
itself or a real requirement of the TYPO3 upgrade process.

Keep Grid Elements active throughout the upgrade, and this entire
failure mode does not arise. **Back up \`\`tt_content\`\` before a TYPO3
Core major-version upgrade regardless**, as ordinary precaution. If
the column does get converted back to unsigned, for example because a
provider's tooling deactivated the extension without being asked to,
restore the `colPos` sentinel with the Col Pos Fixer described at
[Data Consistency Tools](https://docs.typo3.org/permalink/gridelementsteam/gridelements:dataconsistencytools@main), which can repair the sentinel for any row
that still has its `tx_gridelements_container` intact. It cannot
recover the relation itself if that was also lost; a backup is the
only recovery path for that case.

## Applying schema migration suggestions safely {#applying-schema-migration-suggestions-safely}

Keeping Grid Elements active removes the cause of this specific
problem, but the schema migration step itself deserves a general
safety rule regardless, for `colPos` and every other field alike.
TYPO3's schema migrator always groups its suggestions into distinct
kinds, both in Admin Tools > Maintenance > Analyze Database Structure
(TYPO3 13) or System > Maintenance > Analyze Database Structure
(TYPO3 14)
and in `typo3 database:updateschema`: adding new tables, fields and
indexes; changing existing ones; and removing ones no active extension
declares anymore. Adding is always safe to apply without reviewing
each suggestion individually, since it only creates something that did
not exist before and cannot destroy existing data.

**Changing or removing a field or table should be the very last thing
applied during an upgrade, and only after reviewing exactly what each
suggestion does; never apply a batch of "change" or "remove"
suggestions unread.** This is precisely the mechanism that would
revert `colPos` to unsigned: once Core's is the only active
definition for that column, it does not appear as a new field to add,
it appears as a suggested *change* to an existing one. A project that
reviews change suggestions individually, rather than accepting all of
them at once, would see and reject exactly that change to `colPos`,
independent of whether Grid Elements stayed active throughout the
upgrade.

## What is, and is not, version-specific here {#what-is-and-is-not-version-specific-here}

This branch supports TYPO3 `^13.4.7 || ^14.3` simultaneously, not
one or the other. Grid Elements' signed `colPos` schema definition
and the `DataHandler` logic that depends on it are the same code for
both supported versions; there is no version-specific `colPos`
behavior within the range this branch targets, and no version-specific
reason to deactivate it either. The risk described above is entirely a
consequence of Grid Elements being made inactive during a schema
migration step; it is unrelated to, and not required by, moving
between any two TYPO3 Core versions this branch already supports.
