Document the recommended ways to obtain the database connection object

Rebased against 11.x

Seems to have CI failures.

Have not reviewed.

Marios Anagnostopoulos → made their first commit to this issue’s fork.

There doesn't appear to be any open threads and reviewing the text I think that makes sense.

The examples for when to use for what test type is good. Wonder if this should also be updated https://www.drupal.org/docs/drupal-apis/database-api/instantiating-a-dat... →

Will leave the Follow up tag but it's from 5 years ago I think the issue being discussed then may be fixed as far as referencing the database from functional?

The Needs Review Queue Bot → tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

This does not mean that the patch needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide → to find step-by-step guides for working with issues.

I'm unsure why phpstan failed, as MR introduced no code changes except docblock.

The Needs Review Queue Bot → tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

This does not mean that the patch needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide → to find step-by-step guides for working with issues.

Not sure how to fix the problem with phpstan. When I try to manually check the changed file it tells me [ERROR] No files found to analyse.

For now let's tell the bot to skip this one.

Thanks for looking into the bot check issue.
I'm restoring the status before the bot checks.

Added some comments to the MR.

+ * In Object Oriented code:
+ *  - If possible, use dependency injection to use "database" service or
+ *    $container->get('database'); to inject the database connection;

The indentation is wrong, isn't it? The dash should be in the same column as the "I" on the previous line.
Also, ending bullet points with a semi-colon is weird. They should end in a period. If this were all one sentence without bullet points, then perhaps using a semi-colon to separate the clauses would be acceptable, but it would be a really long and confusing sentence with all those clauses. Better IMO to stick with the bullet points and the conventional bullet point punctuation.

+ *  - In unit tests, we do not have a booted kernel or a built container. A
+ *    unit tests which need a database service should be converted to a
+ *    kernel test;

Instead of "A unit tests which need" it should be "A unit test that needs" or "Unit tests that need". Note the use of the singular vs plural forms, as well as the use of "that" instead of "which".

Are we still using i.e. and e.g. in documentation? I thought the community was against it, going back more than 10 years now ... I have no problems with this usage, just pointing this out because we don't want to have a regression in our usage. See for example #2760911: Use of "e.g." and "i.e." → .