[DOCS] Document database records (#4760)

* [DOCS] Document database records

A detailed explanation of what they are was missing.

This is a preparation for documenting the
v13 additions of record objects.

Releases: main, 11.5

* Update Documentation/ApiOverview/Database/Index.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Apply suggestions from code review

Co-authored-by: Stefan Frömken <[email protected]>

* Apply suggestions from code review

Co-authored-by: Stefan Frömken <[email protected]>

* Update Documentation/ApiOverview/DatabaseRecords/Index.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Update Documentation/ApiOverview/Database/Index.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Update Documentation/ApiOverview/Database/Index.rst

* Update Index.rst

* Update Index.rst

* [DOCS] Document database records

A detailed explanation of what they are was missing.

This is a preparation for documenting the
v13 additions of record objects.

Releases: main, 11.5

---------

Co-authored-by: Stefan Frömken <[email protected]>

Documentation/ApiOverview/Categories/Index.rst

@@ -7,7 +7,8 @@ System categories
 =================
 
 TYPO3 provides a generic categorization system.
-Categories can be created in the backend like any other type of record.
+Categories can be created in the backend like any other type of
+:ref:`record <database-records>`.
 
 A TCA field of the column type :ref:`category<t3tca:columns-category>` is
 available.

Documentation/ApiOverview/ContentElements/Index.rst

@@ -28,7 +28,11 @@ Introduction
 ..  contents::
     :local:
 
-In TYPO3, content elements and plugins are both used to present and manage
+In TYPO3, Content elements and plugins are both stored as :ref:`database-records`
+in table :sql:`tt_content`. They are usually edited in the backend in module
+:guilabel:`Web > Page`.
+
+Content elements and plugins are both used to present and manage
 content on a website, but they serve different purposes and have distinct
 characteristics:
 

Documentation/ApiOverview/Database/Index.rst

@@ -1,29 +1,46 @@
 :navigation-title: Database
-.. include:: /Includes.rst.txt
-.. index:: ! Database
-.. _database:
+..  include:: /Includes.rst.txt
+..  index:: ! Database
+..  _database:
 
 ========================
 Database (Doctrine DBAL)
 ========================
 
-**Contents:**
+This chapter describes accessing the database on the level of the Doctrine
+Database Abstraction Layer (DBAL).
 
-.. toctree::
-   :titlesonly:
+The `Doctrine Database Abstraction Layer (DBAL) <https://www.doctrine-project.org/projects/dbal.html>`__ in TYPO3 provides developers
+with a powerful and flexible way to interact with databases, allowing them to
+perform database operations through an object-oriented API while ensuring
+compatibility across different database systems.
 
-   Introduction/Index
-   Configuration/Index
-   DatabaseStructure/Index
-   DatabaseUpgrade/Index
-   BasicCrud/Index
-   ClassOverview/Index
-   ConnectionPool/Index
-   QueryBuilder/Index
-   Connection/Index
-   ExpressionBuilder/Index
-   RestrictionBuilder/Index
-   Statement/Index
-   Middleware/Index
-   TipsAndTricks/Index
-   Troubleshooting/Index
+Within the TYPO3 backend rows of database tables are usually represented as
+:ref:`database-records` and configured in :ref:`database-records-tca`.
+
+In Extbase based extensions tables are abstracted as
+:ref:`Extbase models <extbase-model>`. Operations such as creating, updating and
+deleting database records are usually performed from within a
+:ref:`Extbase repository <extbase-repository>` with methods provided by Extbase
+classes. However, Doctrine DBAL can also be used by extensions that use, for
+example an :ref:`Extbase controller <extbase-controller>`.
+
+..  toctree::
+    :caption: Contents
+    :titlesonly:
+
+    Introduction/Index
+    Configuration/Index
+    DatabaseStructure/Index
+    DatabaseUpgrade/Index
+    BasicCrud/Index
+    ClassOverview/Index
+    ConnectionPool/Index
+    QueryBuilder/Index
+    Connection/Index
+    ExpressionBuilder/Index
+    RestrictionBuilder/Index
+    Statement/Index
+    Middleware/Index
+    TipsAndTricks/Index
+    Troubleshooting/Index

Documentation/ApiOverview/DatabaseRecords/Index.rst

@@ -0,0 +1,110 @@
+:navigation-title: Database records
+.. include:: /Includes.rst.txt
+.. _database-records:
+
+================
+Database records
+================
+
+In TYPO3, a **record** refers to an individual piece of content or data that
+is stored in the database. Each record is part of a table and represents a
+specific entity, such as a page, a content element, a backend user, or an
+extension configuration.
+
+TYPO3 uses a modular structure where different types of data are managed as
+records, making it easy to organize and manipulate content.
+
+Understanding records in TYPO3 is fundamental, as they are the building blocks
+for managing content and data within the system.
+
+..  contents::
+    :caption: Content on this page
+
+..  _database-records-examples:
+
+Common examples of records in TYPO3:
+====================================
+
+Page records
+    These represent pages in the page tree, which structure the website. They
+    are stored in table :sql:`pages`.
+Content records
+    These include text, images, videos, or any other element placed within a
+    page. They are stored in table :sql:`tt_content`.
+Backend user records
+    Information about users who have access to the TYPO3 backend. They
+    are stored in table :sql:`be_users`. The backend user groups they are
+    organized in are stored in table :sql:`be_groups`.
+System records
+    System records control the configuration and management of the TYPO3 system.
+    Examples include file references, file mounts, or categories.
+Extension-specific records
+    Extensions often define custom records to store specific data, such as
+    products for a shop system or events for a calendar.
+
+..  todo: Create a page listing all tables created by the core and explain what
+    they do. Link from here
+
+.. _database-records-technical:
+
+Technical structure of a record:
+================================
+
+Each record is stored in a database table. Each row represents one record. Each
+column represents a field of the record or some kind of metadata.
+
+A record typically includes a unique identifier in column `uid`, the id of the
+page record on which it is located in column `pid`, columns for various
+attributes (for example, title, content), and metadata like creation and
+modification timestamps, visibility, information on translation
+and workspace handling. A record can have relations to other records.
+
+.. _database-records-tca:
+
+TCA (Table Configuration Array)
+===============================
+
+TYPO3 uses the **TCA** to define how records of a specific table are
+structured, how they are displayed in the backend, and how they interact
+with other parts of the system. See the :ref:`TCA Reference <t3tca:start>`
+for details.
+
+.. _database-records-types:
+
+Types and subtypes in records
+-----------------------------
+
+In TYPO3, different types and subtypes of records are often stored in the same
+database table, even though not all types share the same columns. This approach
+allows for flexibility and efficiency in handling diverse content and data
+structures within a unified system.
+
+TYPO3 uses a **single-table inheritance** strategy, where records of various
+types are distinguished by a specific field, often named :sql:`type`.
+For historical reasons the field is named :sql:`CType` for content elements
+and :sql:`doktype` for pages. The field that is used for the type is defined in
+TCA in :confval:`ctrl > type <t3tca:ctrl-type>`. The types itself are stored in
+:ref:`types <t3tca:types>`.
+
+This allows TYPO3 to store related records, such as different content types,
+in a shared table like :sql:`tt_content` while supporting custom
+fields for each record type.
+
+For content elements in table :sql:`tt_content` there is a second level of
+subtypes in use where the field `CType` contains the value "list" and the field
+`list-type` contains the actual type. This second level of types exists for
+historic reasons. Read more about it in chapter :ref:`content-element-and-plugin`.
+
+.. _database-records-models:
+
+Extbase domain models
+=====================
+
+TYPO3 extensions based on Extbase typically introduce a class inheriting from
+:php:`\TYPO3\CMS\Extbase\DomainObject\AbstractEntity` to represent a record
+fully or partially within the domain of the extension. Multiple Extbase models
+can store their data in the same database table. Additionally, the same record
+can be represented in various ways by different Extbase models, depending on
+the specific requirements of each model.
+
+See also chapter :ref:`Extbase models <extbase-model>`.

Documentation/ExtensionArchitecture/Extbase/Reference/Domain/Model.rst

@@ -24,6 +24,8 @@ thread of continuity and identity, for example, a person or a blog post.
 Objects stored in the database are usually entities as they can be identified
 by the :sql:`uid` and are persisted, therefore have continuity.
 
+In the TYPO3 backend models are displayed as :ref:`database-records`.
+
 **Example:**
 
 ..  include:: /CodeSnippets/Extbase/Domain/AbstractEntity.rst.txt