Oleh Vehera · Théodore Biadala
--- a/core/lib/Drupal/Core/Database/database.api.php
+++ b/core/lib/Drupal/Core/Database/database.api.php
 * @endcode
 * if you had a connection object variable $connection available to use. See
 * also the @link container Services and Dependency Injection topic. @endlink
+ * In Object Oriented code:
+ *  - If possible, use dependency injection to use @database service or
+ *    $container->get('database'); to inject the database connection;
+ *  - If it is not possible to use dependency injection, e.g. in a static
+      method, use \Drupal::database();
+ *    @code
+ *    $connection = \Drupal::database();
+ *    $query = $connection->query('...');
+ *    @endcode
+ *  - If services are not yet available,
+ *    \Drupal\Core\Database\Database::getConnection() can get a database
- *  - If services are not yet available,
- *    \Drupal\Core\Database\Database::getConnection() can get a database
+ *  - If services are not yet available, use
+ *    \Drupal\Core\Database\Database::getConnection() can get a database
--- a/core/lib/Drupal/Core/Database/database.api.php
+++ b/core/lib/Drupal/Core/Database/database.api.php
 * @endcode
 * if you had a connection object variable $connection available to use. See
 * also the @link container Services and Dependency Injection topic. @endlink
+ * In Object Oriented code:
+ *  - If possible, use dependency injection to use "database" service or
+ *    $container->get('database'); to inject the database connection;
--- a/core/lib/Drupal/Core/Database/database.api.php
+++ b/core/lib/Drupal/Core/Database/database.api.php
+ *  - If services are not yet available, use
+ *    \Drupal\Core\Database\Database::getConnection() can get a database
+ *    connection;
+ *    @code
+ *    use Drupal\Core\Database\Database;
+ *
+ *    // ...
+ *
+ *    $connection = Database::getConnection();
+ *    $query = $connection->query('...');
+ *    @endcode
+ *  - 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;
+ *  - In kernel and functional test classes we have
+ *    $this->container->get('database'). Some test authors might discover that
--- a/core/lib/Drupal/Core/Database/database.api.php
+++ b/core/lib/Drupal/Core/Database/database.api.php
 * @endcode
 * if you had a connection object variable $connection available to use. See
 * also the @link container Services and Dependency Injection topic. @endlink
+ * In Object Oriented code:
+ * - If possible, use dependency injection to use the "database" service.
+ *   @code
+ *   use Drupal\Core\Database\Connection;
+ *
+ *   class myClass {
+ *
+ *   protected Connection $database;
+ *
+ *   public function __construct(Connection $database) {