Committing a transaction while there are still active savepoints leaves the stack in inconsistent state

We’d need voidClientTransaction() to be public in #3384999: Introduce a Schema::executeDdlStatement method, better make it so now so we can also add it to the interface.

Thanks for review @daffie, addressed all your points.

@daffie if we add @internal, then I think we should remove the method from the interface.

Funnily, I tried to find guidance on use of @internal in Drupal, but I could not find any in the coding standards.

To me, @internal means 'hey developer do not use this method in your code, it may change without notice'. But in this case, we will be actually recommending to use this method to database driver developers when they need to void the transaction stack. So I'm not sure adding @internal is actually the right thing to do.

BTW, we already have the same issue with ::unpile() and ::rollback(), and we did this in the docblock:

  /**
   * Removes a Drupal transaction from the stack.
   *
   * The unpiled item does not necessarily need to be the last on the stack.
   * This method should only be called by a Transaction object going out of
   * scope.
   *
   * This method should only be called internally by a database driver.
   *
   * @param string $name
   *   The name of the transaction.
   * @param string $id
   *   The id of the transaction.
   *
   * @throws \Drupal\Core\Database\TransactionOutOfOrderException
   *   If a Drupal Transaction with the specified name does not exist.
   * @throws \Drupal\Core\Database\TransactionCommitFailedException
   *   If the commit of the root transaction failed.
   */
  public function unpile(string $name, string $id): void;

if we just add

   * This method should only be called internally by a database driver.

also to the new method will it be enough?

Done #13 in the last commit to the MR.

Ah sorry, I commented in Slack but did not copy here:

@daffie
that was not the change... the change was to add the same text to the docbloc about not to call the method outside db drivers. Personally I stand in favour of adding the method to the interface - mysqli driver will need to call it, as it will Connection::executeDdlStatement when we get to it.

@catch the

general problem of 'interfaces, but only supposed to be called by a tiny subset of code'

is a nice one, and one that one may argue is a language limitation of PHP. I was thinking about an assert on the backtrace and looking for the namespace of the caller... but yes, it's not for here.