---
title: "SaveToDatabase finisher"
manual: "Form"
version: "14.3"
permalink: "https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-savetodatabasefinisher@14.3"
source: "I/Concepts/Finishers/ReadyToUseFinishers/SaveToDatabaseFinisher/Index.rst"
rendered: "2026-09-19T11:59:02+00:00"
---

# SaveToDatabase finisher {#concepts-finishers-savetodatabasefinisher}

The "SaveToDatabase finisher" saves data from a submitted form into a
database table.

**Table of contents**

-   [SaveToDatabase finisher options](https://docs.typo3.org/permalink/typo3/cms-form:savetodatabase-finisher-options@14.3)
-   [SaveToDatabase finisher in a YAML form definition](https://docs.typo3.org/permalink/typo3/cms-form:savetodatabase-finisher-in-a-yaml-form-definition@14.3)
-   [Example: adding uploads to ext:news (fal_related_files and fal_media):](https://docs.typo3.org/permalink/typo3/cms-form:example-adding-uploads-to-ext-news-fal-related-files-and-fal-media@14.3)
-   [Using a SaveToDatabase finisher in PHP code](https://docs.typo3.org/permalink/typo3/cms-form:using-a-savetodatabase-finisher-in-php-code@14.3)
-   [Multiple database operations](https://docs.typo3.org/permalink/typo3/cms-form:multiple-database-operations@14.3)

> [!NOTE]
> This finisher cannot be used in the backend form editor. It can only be
> used in a form definition YAML file or programmatically.

> [!IMPORTANT]
> Finishers are executed in the order defined in your form definition.
>
> See [Finisher execution order](https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-execution-order@14.3).

## SaveToDatabase finisher options {#apireference-finisheroptions-savetodatabasefinisher-options}

The finisher options can be set in the form definition YAML file or
programmatically:

-   **table**

    -   *Type:* string
    -   *Required:* true

    Insert or update values in this table.

-   **mode**

    -   *Type:* string
    -   *Default:* `'insert'`

    -   **`insert`**

        will create a new database row with the values from the submitted form
        and/or some predefined values. See also [elements](https://docs.typo3.org/permalink/typo3/cms-form:confval-savetodatabasefinisher-elements@14.3) and
        [databaseColumnMappings](https://docs.typo3.org/permalink/typo3/cms-form:confval-savetodatabasefinisher-databasecolumnmappings@14.3).

    -   **`update`**

        will update a database row with the values from the submitted form
        and/or some predefined values. In this case [whereClause](https://docs.typo3.org/permalink/typo3/cms-form:confval-savetodatabasefinisher-whereclause@14.3) is required.

-   **whereClause**

    -   *Type:* array
    -   *Required:* true
    -   *Default:* `[]`

    The  `where` clause for a database update action.

-   **elements**

    -   *Type:* array
    -   *Required:* true

    Use `options.elements` to map form element values to database columns (they must exist).
    Each key in `options.elements` has to match a form element identifier.
    The value of each key in `options.elements` is an array containing additional information.

-   **elements.\<formElementIdentifier>.mapOnDatabaseColumn**

    -   *Type:* string
    -   *Required:* true

    The value from the submitted form element with the identifier
    `<formElementIdentifier>` will be written into this database column.

-   **elements.\<formElementIdentifier>.skipIfValueIsEmpty**

    -   *Type:* bool
    -   *Default:* `false`

    Set this to true if the database column should not be written if the value from the
    submitted form element with the identifier `<formElementIdentifier>` is empty
    (e.g. for password fields). Empty means strings without content, whitespace is valid content.

-   **elements.\<formElementIdentifier>.hashed**

    -   *Type:* bool
    -   *Default:* `false`

    Set this to true if the value from the submitted form element should be hashed before
    writing into the database.

-   **elements.\<formElementIdentifier>.saveFileIdentifierInsteadOfUid**

    -   *Type:* bool
    -   *Default:* `false`

    By default, the uid of the FAL object will be written into the database column.
    Set this to true if you want to store the FAL identifier
    (e.g. `1:/user_uploads/some_uploaded_pic.jpg`) instead.

    This only applies for form elements which create a FAL object like
    `FileUpload` or `ImageUpload`.

-   **elements.\<formElementIdentifier>.dateFormat**

    -   *Type:* string
    -   *Default:* `'U'`

    If the internal datatype is `\DateTime` (true for the form element types
    `DatePicker` and `Date`), the object needs to be converted into a string.
    This option defines the format of the date. You can use any format accepted by
    the PHP `date()` function.
    Default is `'U'` (Unix timestamp).

-   **databaseColumnMappings**

    -   *Type:* array
    -   *Default:* `[]`

    Use this to map database columns to values.
    Each key within `options.databaseColumnMappings` has to match an existing database column.
    Each value in `options.databaseColumnMappings` is an array with
    additional information.

    This mapping is done *before* [elements](https://docs.typo3.org/permalink/typo3/cms-form:confval-savetodatabasefinisher-elements@14.3) are mapped.
    If you map both, the value from [elements](https://docs.typo3.org/permalink/typo3/cms-form:confval-savetodatabasefinisher-elements@14.3) will override the
    [databaseColumnMappings.\<databaseColumnName>.value](https://docs.typo3.org/permalink/typo3/cms-form:confval-savetodatabasefinisher-databasecolumnmappings-value@14.3).

-   **databaseColumnMappings.\<databaseColumnName>.value**

    -   *Type:* string
    -   *Required:* true

    The value which will be written to the database column.
    You can also use the [FormRuntime accessor feature](https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-customfinisherimplementations-accessingoptions-formruntimeaccessor@14.3)
    to access properties from the `FormRuntime`, e.g. `{<formElementIdentifier>}`.

-   **databaseColumnMappings.\<databaseColumnName>.skipIfValueIsEmpty**

    -   *Type:* bool
    -   *Default:* `false`

    Set this to true if the database column should not be written if the value from
    [databaseColumnMappings.\<databaseColumnName>.value](https://docs.typo3.org/permalink/typo3/cms-form:confval-savetodatabasefinisher-databasecolumnmappings-value@14.3) is empty.

-   **translation.propertiesExcludedFromTranslation**

    -   *Type:* array
    -   *Default:* `[]`

    Defines a list of finisher option properties to be excluded from
    translation.

    If set, these properties are not processed by the
    `TranslationService` during translation.
    This prevents the values from being replaced by
    translated equivalents, even if translations exist for those options.

    This option is usually generated when FlexForm overrides
    exist and normally does not need to be set manually in the form
    definition.

    See [Skip translation of overridden form finisher options](https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher-yaml-propertiesexcludedfromtranslation@14.3)
    for an example.

## SaveToDatabase finisher in a YAML form definition {#concepts-finishers-savetodatabasefinisher-yaml}

This finisher saves data from a submitted form into a database table.

**public/fileadmin/forms/my_form.yaml**

```yaml
identifier: example-form
label: 'example'
type: Form

finishers:
  -
    identifier: SaveToDatabase
    options:
      table: 'fe_users'
      mode: update
      whereClause:
        uid: 1
      databaseColumnMappings:
        tstamp:
          value: '{__currentTimestamp}'
        pid:
          value: 1
      elements:
        textfield-identifier-1:
          mapOnDatabaseColumn: 'first_name'
        textfield-identifier-2:
          mapOnDatabaseColumn: 'last_name'
        textfield-identifier-3:
          mapOnDatabaseColumn: 'username'
        advancedpassword-1:
          mapOnDatabaseColumn: 'password'
          skipIfValueIsEmpty: true
          hashed: true

```

## Example: adding uploads to ext:news (fal_related_files and fal_media): {#concepts-finishers-savetodatabasefinisher-example-news}

**public/fileadmin/forms/my_form_with_multiple_finishers.yaml**

```yaml
-
  identifier: SaveToDatabase
  options:
    -
      table: tx_news_domain_model_news
      mode: insert
      elements:
        my-field:
          mapOnDatabaseColumn: bodytext
        imageupload-1:
          mapOnDatabaseColumn: fal_media
        fileupload-1:
          mapOnDatabaseColumn: fal_related_files
      databaseColumnMappings:
        pid:
          value: 3
        tstamp:
          value: '{__currentTimestamp}'
        datetime:
          value: '{__currentTimestamp}'
        crdate:
          value: '{__currentTimestamp}'
        hidden:
          value: 1
    -
      table: sys_file_reference
      mode: insert
      elements:
        imageupload-1:
          mapOnDatabaseColumn: uid_local
          skipIfValueIsEmpty: true
      databaseColumnMappings:
        tablenames:
          value: tx_news_domain_model_news
        fieldname:
          value: fal_media
        tstamp:
          value: '{__currentTimestamp}'
        crdate:
          value: '{__currentTimestamp}'
        showinpreview:
          value: 1
        uid_foreign:
          value: '{SaveToDatabase.insertedUids.0}'
    -
      table: sys_file_reference
      mode: insert
      elements:
        fileupload-1:
          mapOnDatabaseColumn: uid_local
          skipIfValueIsEmpty: true
      databaseColumnMappings:
        tablenames:
          value: tx_news_domain_model_news
        fieldname:
          value: fal_related_files
        tstamp:
          value: '{__currentTimestamp}'
        crdate:
          value: '{__currentTimestamp}'
        uid_foreign:
          value: '{SaveToDatabase.insertedUids.0}'
    -
      table: sys_file_reference
      mode: update
      whereClause:
        uid_foreign: '{SaveToDatabase.insertedUids.0}'
        uid_local: 0
      databaseColumnMappings:
        pid:
          value: 0
        uid_foreign:
          value: 0

```

## Using a SaveToDatabase finisher in PHP code {#apireference-finisheroptions-savetodatabasefinisher}

Developers can use the finisher key `SaveToDatabase` to create
flash message finishers in their own classes:

```php
<?php

use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher;
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
class SomeClass
{
    private function addDeleteUploadsFinisherWithMessage(FormDefinition $formDefinition, string $message)
    {
        $formDefinition->createFinisher('SaveToDatabase', [
            'table' => 'fe_users',
            'mode' => 'update',
            'whereClause' => [
                'uid' => 1,
            ],
            'databaseColumnMappings' => [
                'pid' => ['value' => 1],
            ],
            'elements' => [
                'textfield-identifier-1' => ['mapOnDatabaseColumn' => 'first_name'],
                'textfield-identifier-2' => ['mapOnDatabaseColumn' => 'last_name'],
                'textfield-identifier-3' => ['mapOnDatabaseColumn' => 'username'],
                'advancedpassword-1' => [
                    'mapOnDatabaseColumn' => 'password',
                    'skipIfValueIsEmpty' => true,
                    'hashed' => true
                ],
            ],
        ]);
    }
}

```

This finisher is implemented in `\TYPO3\CMS\Form\Domain\Finishers\SaveToDatabaseFinisher`.

## Multiple database operations {#concepts-finishers-savetodatabasefinisher-multiple}

You can use options to perform multiple database operations.

Example form definition file (performs inserts):

**public/fileadmin/forms/my_form_with_multiple_finishers.yaml**

```yaml
-
  identifier: SaveToDatabase
  options:
    -
      table: tx_news_domain_model_news
      mode: insert
      elements:
        my-field:
          mapOnDatabaseColumn: bodytext
        imageupload-1:
          mapOnDatabaseColumn: fal_media
        fileupload-1:
          mapOnDatabaseColumn: fal_related_files
      databaseColumnMappings:
        pid:
          value: 3
        tstamp:
          value: '{__currentTimestamp}'
        datetime:
          value: '{__currentTimestamp}'
        crdate:
          value: '{__currentTimestamp}'
        hidden:
          value: 1
    -
      table: sys_file_reference
      mode: insert
      elements:
        imageupload-1:
          mapOnDatabaseColumn: uid_local
          skipIfValueIsEmpty: true
      databaseColumnMappings:
        tablenames:
          value: tx_news_domain_model_news
        fieldname:
          value: fal_media
        tstamp:
          value: '{__currentTimestamp}'
        crdate:
          value: '{__currentTimestamp}'
        showinpreview:
          value: 1
        uid_foreign:
          value: '{SaveToDatabase.insertedUids.0}'
    -
      table: sys_file_reference
      mode: insert
      elements:
        fileupload-1:
          mapOnDatabaseColumn: uid_local
          skipIfValueIsEmpty: true
      databaseColumnMappings:
        tablenames:
          value: tx_news_domain_model_news
        fieldname:
          value: fal_related_files
        tstamp:
          value: '{__currentTimestamp}'
        crdate:
          value: '{__currentTimestamp}'
        uid_foreign:
          value: '{SaveToDatabase.insertedUids.0}'
    -
      table: sys_file_reference
      mode: update
      whereClause:
        uid_foreign: '{SaveToDatabase.insertedUids.0}'
        uid_local: 0
      databaseColumnMappings:
        pid:
          value: 0
        uid_foreign:
          value: 0

```

Using PHP code (performs an update):

```php
<?php

use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher;
use TYPO3\CMS\Form\Domain\Model\FormDefinition;
class SomeClass
{
    private function addDeleteUploadsFinisherWithMessage(FormDefinition $formDefinition, string $message)
    {
        $formDefinition->createFinisher('SaveToDatabase', [
            'table' => 'fe_users',
            'mode' => 'update',
            'whereClause' => [
                'uid' => 1,
            ],
            'databaseColumnMappings' => [
                'pid' => ['value' => 1],
            ],
            'elements' => [
                'textfield-identifier-1' => ['mapOnDatabaseColumn' => 'first_name'],
                'textfield-identifier-2' => ['mapOnDatabaseColumn' => 'last_name'],
                'textfield-identifier-3' => ['mapOnDatabaseColumn' => 'username'],
                'advancedpassword-1' => [
                    'mapOnDatabaseColumn' => 'password',
                    'skipIfValueIsEmpty' => true,
                    'hashed' => true
                ],
            ],
        ]);
    }
}

```

You can access inserted UIDs with '{SaveToDatabase.insertedUids.\<theArrayKeyNumberInsideOptions>}'.
If you perform an insert operation, the inserted values will be stored in the FinisherVariableProvider.
\<theArrayKeyNumberInOptions> references the numeric options.\* key.