.. include:: /Includes.rst.txt .. index:: File; EXT:{extkey}/ext_tables.sql .. _ext_tables-sql: ====================== :file:`ext_tables.sql` ====================== *-- optional* The :file:`ext_tables.sql` file in the root folder of an extension holds additional SQL definition of database tables. This file should contain a table-structure dump of the tables used by the extension which are not :ref:`auto-generated `. It is used for evaluation of the database structure and is applied to the database when an extension is enabled. If you add additional fields (or depend on certain fields) to existing tables you can also put them here. In this case insert a :sql:`CREATE TABLE` structure for that table, but remove all lines except the ones defining the fields you need. Here is an example adding a column to the pages table: .. code-block:: sql CREATE TABLE pages ( tx_myextension_field int(11) DEFAULT '0' NOT NULL, ); TYPO3 will merge this table definition to the existing table definition when comparing expected and actual table definitions (for example, via the :guilabel:`Admin Tools > Maintenance > Analyze Database Structure` or the :ref:`CLI ` command :bash:`extension:setup`. Partial definitions can also contain indexes and other directives. They can also change existing table fields - but that is not recommended, because it may create problems with the TYPO3 Core and/or other extensions. The :file:`ext_tables.sql` file may not necessarily be "dumpable" directly to a database (because of the semi-complete table definitions allowed that define only required fields). But the extension manager or admin tools can handle this. TYPO3 parses :sql:`ext_tables.sql` files. TYPO3 expects that all table definitions in this file look like the ones produced by the :bash:`mysqldump` utility. Incorrect definitions may not be recognized by the TYPO3 SQL parser or may lead to SQL errors, when TYPO3 tries to apply them. If TYPO3 is not running on MySQL or a directly compatible other :abbr:`DBMS (Database Management System)` like MariaDB, the system will parse the file towards the target DBMS like PostgreSQL or SQLite. .. _auto-generated-db-structure: Auto-generated structure ======================== The database schema analyzer automatically creates TYPO3 "management"-related database columns by reading a table's TCA and checking the :ref:`t3tca:ctrl` section for table capabilities. Field definitions in :file:`ext_tables.sql` take precedence over automatically generated fields, so the TYPO3 Core never overrides a manually specified column definition from an :file:`ext_tables.sql` file. .. note:: .. versionadded:: 13.0 As column definitions are created automatically from the TCA configuration, the :file:`ext_tables.sql` file can end up with a table definition without columns, like: .. code-block:: sql CREATE TABLE tx_myextension_domain_model_table ( ); This would be invalid as such in most :abbr:`DBMS (Database Management System)`, since tables usually must have at least one column. However, it is a valid definition in the scope of :file:`ext_tables.sql` files when the TYPO3 Core enriches fields from TCA. Also, you can omit the :sql:`CREATE TABLE` statement without columns entirely. These columns below are automatically added if not defined in :file:`ext_tables.sql` for database tables that provide a :php:`$GLOBALS['TCA']` definition: :sql:`uid` and :sql:`PRIMARY KEY` If the :sql:`uid` field is not provided inside the :file:`ext_tables.sql` file, the :sql:`PRIMARY KEY` constraint **must** be omitted, too. :sql:`pid` and :sql:`KEY parent` The column :sql:`pid` is :php:`unsigned`, if the table is not :doc:`workspace `-aware, the default index :sql:`parent` includes :sql:`pid` and :sql:`hidden` as well as :sql:`deleted`, if the latter two are specified in TCA's :ref:`t3tca:ctrl`. The parent index creation is only applied, if the column :sql:`pid` is auto-generated, too. The following :ref:`$GLOBALS['TCA']['ctrl'] ` are considered for auto-generated fields, if they are not manually defined in the :file:`ext_tables.sql` file: :php:`['ctrl']['tstamp'] = 'my_field_name'` Often set to :sql:`tstamp` or :sql:`updatedon`. :php:`['ctrl']['crdate'] = 'my_field_name'` Often set to :sql:`crdate` or :sql:`createdon`. :php:`['ctrl']['delete'] = 'my_field_name'` Often set to :sql:`deleted`. :php:`['ctrl']['enablecolumns']['disabled'] = 'my_field_name'` Often set to :sql:`hidden` or :sql:`disabled`. :php:`['ctrl']['enablecolumns']['starttime'] = 'my_field_name'` Often set to :sql:`starttime`. :php:`['ctrl']['enablecolumns']['endtime'] = 'my_field_name'` Often set to :sql:`endtime`. :php:`['ctrl']['enablecolumns']['fe_group'] = 'my_field_name'` Often set to :sql:`fe_group`. :php:`['ctrl']['sortby'] = 'my_field_name'` Often set to :sql:`sorting`. :php:`['ctrl']['descriptionColumn'] = 'my_field_name'` Often set to :sql:`description`. :php:`['ctrl']['editlock'] = 'my_field_name'` Often set to :sql:`editlock`. :php:`['ctrl']['languageField'] = 'my_field_name'` Often set to :sql:`sys_language_uid`. :php:`['ctrl']['transOrigPointerField'] = 'my_field_name'` Often set to :sql:`l10n_parent`. :php:`['ctrl']['translationSource'] = 'my_field_name'` Often set to :sql:`l10n_source`. :sql:`l10n_state` Column added if :php:`['ctrl']['languageField']` and :php:`['ctrl']['transOrigPointerField']` are set. :php:`['ctrl']['origUid'] = 'my_field_name'` Often set to :sql:`t3_origuid`. :php:`['ctrl']['transOrigDiffSourceField'] = 'my_field_name'` Often set to :sql:`l10n_diffsource`. :php:`['ctrl']['versioningWS'] = true` and :sql:`t3ver_*` columns Columns that make a table :doc:`workspace `-aware. All those fields are prefixed with :sql:`t3ver_`, for example :sql:`t3ver_oid`. A default index named :sql:`t3ver_oid` to fields :sql:`t3ver_oid` and :sql:`t3ver_wsid` is added, too. The configuration in :ref:`$GLOBALS['TCA'][$table]['columns'][$field]['config']['MM'] ` is considered for auto-generating the intermediate table and fields for: * :ref:`TCA type "group" ` * :ref:`TCA type "inline" ` * :ref:`TCA type "select" ` The following types configured via :ref:`$GLOBALS['TCA'][$table]['columns'][$field]['config'] ` are considered for auto-generated fields, if they are not manually defined in the :file:`ext_tables.sql` file: * :ref:`TCA type "category" ` (since TYPO3 v12.0) * :ref:`TCA type "check" ` (since TYPO3 v13.0) * :ref:`TCA type "color" ` (since TYPO3 v13.0) * :ref:`TCA type "datetime" ` * :ref:`TCA type "email" ` (since TYPO3 v13.0) * :ref:`TCA type "file" ` (since TYPO3 v13.0) * :ref:`TCA type "flex" ` (since TYPO3 v13.0) * :ref:`TCA type "folder" ` (since TYPO3 v13.0) * :ref:`TCA type "group" ` (since TYPO3 v13.0) * :ref:`TCA type "imageManipulation" ` (since TYPO3 v13.0) * :ref:`TCA type "inline" ` (since TYPO3 v13.0) * :ref:`TCA type "json" ` * :ref:`TCA type "language" ` (since TYPO3 v13.0) * :ref:`TCA type "link" ` (since TYPO3 v13.0) * :ref:`TCA type "number" ` (since TYPO3 v13.0) * :ref:`TCA type "password" ` (since TYPO3 v13.0) * :ref:`TCA type "radio" ` (since TYPO3 v13.0) * :ref:`TCA type "select" ` (since TYPO3 v13.0) * :ref:`TCA type "slug" ` (since TYPO3 v12.0) * :ref:`TCA type "text" ` (since TYPO3 v13.0) * :ref:`TCA type "uuid" `