Cleanup database exceptions [#3622582]

Spin off from #3609986: Improve database exception messages.

Problem/Motivation

Database exceptions' hierarchy is a bit messy, and couple of them are unused. Found out in #3609986: Improve database exception messages.

Proposed resolution

Cleanup the hierarchy structure and deprecate those that are unused.
Introduce dedicated exceptions for table existence checks: SchemaTableDoesNotExistException and SchemaTableAlreadyExistsException
Introduce a SqlExecutionInfo value object that carries the details of the SQL operation that failed.
Change database wrapper exceptions to include the SqlExecutionInfo optionally.

New hierarchy structure of the database exceptions after MR merge (AI assisted in drawing the tree):

DatabaseException [interface]
├── ConnectionNotDefinedException
│   [Drupal\Core\Database\ConnectionNotDefinedException]
├── DriverNotSpecifiedException
│   [Drupal\Core\Database\DriverNotSpecifiedException]
├── InvalidQueryException
│   [Drupal\Core\Database\InvalidQueryException]
├── Query\FieldsOverlapException
│   [Drupal\Core\Database\Query\FieldsOverlapException]
├── Query\InvalidMergeQueryException
│   [Drupal\Core\Database\Query\InvalidMergeQueryException]
├── Query\NoFieldsException
│   [Drupal\Core\Database\Query\NoFieldsException]
├── Query\NoUniqueFieldException
│   [Drupal\Core\Database\Query\NoUniqueFieldException]
├── RowCountException
│   [Drupal\Core\Database\RowCountException]
├── SchemaDefinitionException
│   [Drupal\Core\Database\SchemaDefinitionException]
└── DatabaseExceptionWrapper
    [Drupal\Core\Database\DatabaseExceptionWrapper]
    ├── DatabaseAccessDeniedException
    │   [Drupal\Core\Database\DatabaseAccessDeniedException]
    ├── DatabaseConnectionRefusedException
    │   [Drupal\Core\Database\DatabaseConnectionRefusedException]
    ├── DatabaseNotFoundException
    │   [Drupal\Core\Database\DatabaseNotFoundException]
    ├── IntegrityConstraintViolationException
    │   [Drupal\Core\Database\IntegrityConstraintViolationException]
    ├── SchemaException
    │   [Drupal\Core\Database\SchemaException]
    │   ├── SchemaObjectDoesNotExistException
    │   │   [Drupal\Core\Database\SchemaObjectDoesNotExistException]
    │   │   └── SchemaTableDoesNotExistException
    │   │       [Drupal\Core\Database\Exception\SchemaTableDoesNotExistException]
    │   ├── SchemaObjectExistsException
    │   │   [Drupal\Core\Database\SchemaObjectExistsException]
    │   │   └── SchemaTableAlreadyExistsException
    │   │       [Drupal\Core\Database\Exception\SchemaTableAlreadyExistsException]
    │   ├── SchemaPrimaryKeyMustBeDroppedException
    │   │   [Drupal\Core\Database\Exception\SchemaPrimaryKeyMustBeDroppedException]
    │   ├── SchemaTableColumnSizeTooLargeException
    │   │   [Drupal\Core\Database\Exception\SchemaTableColumnSizeTooLargeException]
    │   └── SchemaTableKeyTooLargeException
    │       [Drupal\Core\Database\Exception\SchemaTableKeyTooLargeException]
    └── TransactionException
        [Drupal\Core\Database\TransactionException]
        ├── TransactionCommitFailedException
        │   [Drupal\Core\Database\TransactionCommitFailedException]
        ├── TransactionExplicitCommitNotAllowedException [deprecated]
        │   [Drupal\Core\Database\TransactionExplicitCommitNotAllowedException]
        ├── TransactionNameNonUniqueException
        │   [Drupal\Core\Database\TransactionNameNonUniqueException]
        ├── TransactionNoActiveException [deprecated]
        │   [Drupal\Core\Database\TransactionNoActiveException]
        └── TransactionOutOfOrderException
            [Drupal\Core\Database\TransactionOutOfOrderException]

Remaining tasks

User interface changes

API changes

Data model changes

Release notes snippet

For the committer

The changes to the .gitlab-ci.yml file need to be removed before merging!

Issue fork drupal-3622582

Show commands

Start within a Git clone of the project using the version control instructions.

Add & fetch this issue fork’s repository

Or, if you do not have SSH keys set up on git.drupalcode.org:

Add & fetch this issue fork’s repository

3622582-cleanup-database-exceptions changes, plain diff MR !17095
Check out this branch for the first time

Check out existing branch, if you already have it locally

About issue forks

Comments

Comment #1

11 September 2026 at 20:30

mondrake created an issue. See original summary.

Comment #2

mondrake

🇮🇹

commented 11 September 2026 at 20:30

Issue summary:

View changes

Comment #3

mondrake

🇮🇹

commented 11 September 2026 at 20:30

Issue summary:

View changes

Comment #4

11 September 2026 at 20:58

mondrake opened merge request !17095

Comment #5

mondrake

🇮🇹

commented 11 September 2026 at 21:30

Issue summary:	View changes
Status:	Active	» Needs review

Comment #6

dcam commented 5 October 2026 at 18:31

Status:

Needs review

» Needs work

I think this is mostly OK, but I did find one issue. There's a docblock reference to the deprecated TransactionNoActiveException at TransationManagerInterface::rollback(), https://git.drupalcode.org/project/drupal/-/blob/main/core/lib/Drupal/Co.... As far as I can tell only TransationManagerBase::rollback() implements this function and it does not throw TransactionNoActiveException. Maybe it did at one time. I attempted a brief search through its Git history to see if I could find out. Eventually I decided it wasn't that important and stopped. Anyway, I'm not familiar enough with the database subsystem to know for certain, but it seems like we can just delete this @throws annotation.

Comment #7

mondrake

🇮🇹

commented 5 October 2026 at 20:44

Status:

Needs work

» Needs review

Done #6 (thanks), added draft CR, linked in deprecation messages, bumped deprecation version to 12.1.

Comment #8

dcam commented 6 October 2026 at 02:00

Status:

Needs review

» Reviewed & tested by the community

Thank you for taking care of the deprecation messages. I knew there was something that I was forgetting. I did this review over several days and it slipped my mind.

Anyway, that was all the feedback I had. I'll go ahead and RTBC it so we can see what a committer says.

Comment #9

daffie commented 6 October 2026 at 13:03

Status:	Reviewed & tested by the community	» Needs work
Issue tags:		+Needs issue summary update

The code changes in the MR look good.
Just a single old deprecation that needs to be updated.
What I am missing in the IS and maybe the CR is information about the new class SqlExecutionInfo. Also why it is added. I am not saying that it wrong or anything. Just explain what is added and why it should be added.
The same for the other changes in the MR. I am getting the feeling that they should be in different issues.
A lot of exception are getting an extra parameter. Should that be documented. At least in the IS.

Comment #10

mondrake

🇮🇹

commented 7 October 2026 at 18:42

Issue summary:	View changes
Status:	Needs work	» Needs review
Issue tags:	-Needs issue summary update

Introduce dedicated exceptions for table existence checks: SchemaTableDoesNotExistException and SchemaTableAlreadyExistsException, to help simplifying #2371709: Move the on-demand-table creation into the database API.

Comment #11

7 October 2026 at 21:35

longwave-bot made their first commit to this issue’s fork.

Comment #12

longwave

he/him

English

commented 7 October 2026 at 21:39

Normalized all exceptions across all drivers as some SQLite and Postgres cases were missing before. Also improved the formatter a bit.

Parts of these commits were assisted by GPT 6.

Comment #13

mondrake

🇮🇹

commented 7 October 2026 at 22:05

Status:

Needs review

» Needs work

Couple of comments inline. Man AI-built tests are hard to follow...

Comment #14

mondrake

🇮🇹

commented 8 October 2026 at 06:24

All drivers' ExceptionHandlers now implement the pattern handleStatementException() -> rethrowNormalizedException(), but the base class does not and is now dead code for core anyway.

Can we deprecate calling the base class' handleStatementException() on the basis that it will become abstract in 13? and implement a stub rethrowNormalizedException() in the base class too that just throws?

Comment #15

daffie commented 8 October 2026 at 07:53

Priority:	Normal	» Critical
Related issues:		+#2371709: Move the on-demand-table creation into the database API

This issue has become a blocker for #2371709: Move the on-demand-table creation into the database API and that issue has the priority critical. Therefore this issue also gets the priority critical.

Comment #16

mondrake

🇮🇹

commented 8 October 2026 at 09:20

Filed a follow up.

Comment #17

longwave

he/him

English

commented 8 October 2026 at 10:02

Status:

Needs work

» Needs review

All pipelines are green.

Addressed the feedback from #13 and #14:

Replaced the per-driver unit tests with a kernel test in SchemaTableExceptionTest that triggers real table errors through query() on every driver.
Removed the duplicate pgsql unit test.
Removed the SQLite trigger case.
DatabaseExceptionWrapperTest now asserts SchemaTableDoesNotExistException.
Converted simple data providers to #[TestWith].
Simplified SqlExecutionInfoTest.

Comment #18

longwave

he/him

English

commented 8 October 2026 at 10:26

Did another self-review pass, removed a bunch of tests that were testing nothing useful or duplicates. Also removed fromThrowable() and stripFromMessage() as nothing calls them - we can reintroduce them when we need them? Hopefully this addresses @daffie's concerns in #9.

Comment #19

mondrake

🇮🇹

commented 8 October 2026 at 10:29

Lovely and neat. Thanks!

+1 for RTBC but I cannot mark.

Comment #20

longwave

he/him

English

commented 8 October 2026 at 11:25

Added two CRs, one for database driver maintainers who need to add the new exceptions, and another for the message format changes and SqlExceptionInfo.

Comment #21

daffie commented 8 October 2026 at 11:42

Status:

Needs review

» Needs work

I was a bit worried about a possible BC break with all the changes to the exceptions. Only I could not find an exception change that would be a BC break.
All the code changes look good to me.
@longwave what to do a minor documentation change in the MR, which is fine by me.
After that is it RTBC for me.

Comment #22

longwave

he/him

English

commented 8 October 2026 at 12:22

Status:

Needs work

» Needs review

Renamed the variable, updated some comments and the CR to match.

Comment #23

daffie commented 8 October 2026 at 14:40

Status:

Needs review

» Reviewed & tested by the community

The last changes from @longwave look good to me.
There is enough testing added.
All code changes look good to me.
For me it is RTBC.

Comment #24

mondrake

🇮🇹

commented 8 October 2026 at 20:50

Assigned:	Unassigned	» mondrake
Status:	Reviewed & tested by the community	» Needs work

found a small inconsistency, will update soon

Comment #25

mondrake

🇮🇹

commented 8 October 2026 at 21:43

Status:

Needs work

» Needs review

With this MR, DatabaseExceptionWrapper becomes the base exception class for any error that is thrown by the lower-level database driver client (PDO, mysqli, etc).

Based on this, IMHO

DatabaseAccessDeniedException, DatabaseConnectionRefusedException and DatabaseNotFoundException should be descendants of DatabaseExceptionWrapper, since they are triggered after the client returns an error.
Conversely, SchemaDefinitionException should no longer be a descendent of SchemaException, since that inherits from DatabaseExceptionWrapper and is triggered when execution of DML fails. But errors from the schema definition have nothing to do with the client connection. So it could be a direct implementation of the interface instead.

Made changes accordingly in the last commit.

Comment #26

mondrake

🇮🇹

commented 8 October 2026 at 21:54

Issue summary:

View changes

Updated the inheritance tree in the IS (AI assisted generation)

Comment #27

mondrake

🇮🇹

commented 9 October 2026 at 06:27

Assigned:

mondrake

» Unassigned

Comment #28

daffie commented 9 October 2026 at 09:15

Status:

Needs review

» Needs work

I have 2 remarks on the code changes:

The TransactionCommitFailedException does not need to implement DatabaseException. It gets that from extending TransactionException.
The SchemaDefinitionException is now extending SchemaException only on in the issue summary it should not be doing that.

Comment #29

daffie commented 9 October 2026 at 09:17

Issue summary:

View changes

The changes to the gtilab-ci file need to be removed before merging the code changes into the main branch.

Comment #30

mondrake

🇮🇹

commented 9 October 2026 at 09:22

@daffie can't you run the other drivers' jobs from the UI instead of changing the ci setup? Just asking, I think I saw issues in relation to this, wanted to check.

Comment #31

mondrake

🇮🇹

commented 9 October 2026 at 09:28

Issue summary:

View changes

The SchemaDefinitionException is now extending SchemaException only on in the issue summary it should not be doing that

Thanks. AI was lazy. Hopefully corrected now.

Comment #32

daffie commented 9 October 2026 at 09:30

@daffie can't you run the other drivers' jobs from the UI instead of changing the ci setup? Just asking, I think I saw issues in relation to this, wanted to check.

I am not allowed to do that. As a subsystem maintainer, I do not have that permission. There is somewhere a ticket open to fix that.

Comment #33

mondrake

🇮🇹

commented 9 October 2026 at 09:34

Status:

Needs work

» Needs review

The TransactionCommitFailedException does not need to implement DatabaseException. It gets that from extending TransactionException.

thanks for checking that. Done.

I am not allowed to do that. As a subsystem maintainer, I do not have that permission. There is somewhere a ticket open to fix that.

ok now I connect the dots, thx

Comment #34

daffie commented 9 October 2026 at 09:50

Status:

Needs review

» Reviewed & tested by the community

All my remarks have been addressed.
All code changes look good to me.
The IS and the CR's are in order.
For me it is RTBC.

Cleanup database exceptions

Problem/Motivation

Proposed resolution

Remaining tasks

User interface changes

API changes

Data model changes

Release notes snippet

For the committer

Issue fork drupal-3622582

Comments

Change record drafts

Parent issue

Child issues

Related issues

Referenced by