---
title: "Database compare during update and installation"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:database-upgrade@main"
source: "ApiOverview/Database/DatabaseUpgrade/Index.rst"
modified: "2026-09-16T13:05:25+00:00"
---

# Database compare during update and installation

Whenever you install or update an extension, or change the
[TCA definition](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/Index.html#start) or the
[ext_tables.sql](https://docs.typo3.org/permalink/t3coreapi:database-exttables-sql@main) in an extension, you have to take
into account the fact that the database schema might have changed.

![TYPO3 backend with the "System > Maintenance". The database analyzer is highlighted.](../../../Images/ManualScreenshots/AdminTools/AnalyzeDatabase.png)

**Table of contents**

-   [Compare the database schema and apply changes](https://docs.typo3.org/permalink/t3coreapi:compare-the-database-schema-and-apply-changes@main)
-   [Tables that exist as views are ignored](https://docs.typo3.org/permalink/t3coreapi:tables-that-exist-as-views-are-ignored@main)
-   [Adding columns and tables is safe](https://docs.typo3.org/permalink/t3coreapi:adding-columns-and-tables-is-safe@main)
-   [Deleting columns or tables: be careful](https://docs.typo3.org/permalink/t3coreapi:deleting-columns-or-tables-be-careful@main)
-   [Changing a column type: it depends](https://docs.typo3.org/permalink/t3coreapi:changing-a-column-type-it-depends@main)
-   [Conflicting column definitions](https://docs.typo3.org/permalink/t3coreapi:conflicting-column-definitions@main)

## Compare the database schema and apply changes

Users with
[System Maintainer privileges](https://docs.typo3.org/permalink/t3coreapi:system-maintainer@main) can use the
**Analyze Database Structure** section in the
**System > Maintenance** module to compare the defined schema
with the current one. The module display options to incorporate changes by adding,
removing, or updating columns.

You can also use the console command `typo3 extension:setup` to add tables
and columns defined by installed or updated extensions:

**Composer-based installation**

```bash
vendor/bin/typo3 extension:setup
```

**Classic mode installation (no Composer)**

```bash
typo3/sysext/core/bin/typo3 extension:setup
```

## Tables that exist as views are ignored

> [!NOTE]
> **Changed in version 13.4**
>
> Tables that exist as views are excluded from the comparison.
> See [Important: #106546 - Tables that exist as views are ignored](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/13.4.x/Important-106546-TablesThatExistAsViewsAreIgnored.html#important-106546-1786385411).

A table declared in [`ext_tables.sql`](../../../ExtensionArchitecture/FileStructure/ExtTablesSql.md#file-extension-ext-tables-sql) or through TCA may exist as a view
on the connection it is mapped to, which is a common way to make data from
another system available to TYPO3. Such tables are excluded from the
comparison on both sides: the database analyzer neither proposes to alter or
drop the view, since TYPO3 does not own it, nor to create it, since the name
is already taken.

## Adding columns and tables is safe

Adding additional columns or tables is not problematic. You can safely add any
column shown as missing.

## Deleting columns or tables: be careful

Columns suggested for deletion might still be needed by
[upgrade wizards](https://docs.typo3.org/permalink/t3coreapi:upgrade-wizards@main).

Before deleting tables or columns with the database analyzer:

-   Run all upgrade wizards
-   Make a database backup

Some third-party extensions may rely on database columns or tables they do not
explicitly define. Removing them could cause these extensions to break.

## Changing a column type: it depends

Some column changes extend capabilities and are safe. For example:

-   Changing from `TEXT` to `LONGTEXT` allows more data to be stored
    and does not affect existing content.

Other changes can cause problems if existing data violates the new definition.
For instance:

-   Changing from `NULL` to `NOT NULL` will fail if any row,
    including **soft-deleted** ones (`deleted = 1`), still contains `NULL`.

Some extensions provide upgrade wizards to clean or convert data. Note that
many wizards ignore soft-deleted records. Deleting unnecessary soft-deleted
records may help.

## Conflicting column definitions

[Database structure](https://docs.typo3.org/permalink/t3coreapi:database-structure@main) is defined by the
[Table Configuration Array (TCA)](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/Index.html#start)
and by definitions in the [`ext_tables.sql`](../../../ExtensionArchitecture/FileStructure/ExtTablesSql.md#file-extension-ext-tables-sql) file in an extension, if the file exists.

If two extensions define the same column in different ways, the definition
from the extension that is
[loaded last](https://docs.typo3.org/permalink/t3coreapi:extension-loading-order@main)
will take precedence.

This means that an extension that changes or adds columns to a table **must**
declare a dependency on the original extension to ensure proper loading order.