Database abstraction layer topic / landing page needs more info

1. +++ b/core/includes/database.inc
   @@ -18,123 +18,160 @@
   + * @sec sec_entity Querying entities
   

   I question if this belongs in the database documentation. It's part of the entity system, NOT the Database component. The database component should be seen as a stand-alone library; there's only a few technical reasons it isn't yet, because we've not fully unwound it. Assume that DBTNG will eventually move to \Drupal\Component\ and potentially even its own repository.

   A warning to not use the DB API directly for querying entities is fine, but the actual documentation of how to do so belongs elsewhere.

2. +++ b/core/includes/database.inc
   @@ -18,123 +18,160 @@
   + * - Retrieve the entity query object (which implements
   + *   \Drupal\Core\Entity\Query\QueryInterface) appropriate to the entity type:
   + *   @code
   + *   // If you have a $container variable:
   + *   $container->get('entity.query')->get('your_entity_type');
   + *   // If you don't:
   + *   $query = \Drupal::entityQuery('your_entity_type');
   + *   @endcode
   

   Except most of the time you should get the entity.query service injected rather than accessing the container directly or calling the global. (This is a global problem of how to document things, not specific to this case.)

3. +++ b/core/includes/database.inc
   @@ -18,123 +18,160 @@
   + * abstraction layer provides the functions db_query() and db_query_range(),
   

   If we're updating the documentation, we should also not refer to deprecated wrapper functions and use the object form instead.

4. +++ b/core/includes/database.inc
   @@ -18,123 +18,160 @@
   + * In this context, "simple" means a query that does not involve a join, LIKE,
   

   JOINs are fairly safe in most cases. If you can get away with just using query() you should.

5. +++ b/core/includes/database.inc
   @@ -18,123 +18,160 @@
   + *   ->fields('e', array('id', 'title', 'created'))
   

   Perhaps it's time to start using the short-array syntax here, as it's actually considerably more readable. (Fewer things using (), so the code looks less like LISP.)

6. +++ b/core/includes/database.inc
   @@ -18,123 +18,160 @@
   + * consistently across databases. So, you should never use db_query() to run
   

   "So" is unnecessary in this sentence.

7. +++ b/core/includes/database.inc
   @@ -18,123 +18,160 @@
   + * an INSERT, UPDATE, or DELETE query. Instead, use functions db_insert(),
   

   As above, we should stop referring to the functions and use the methods instead.

8. +++ b/core/includes/database.inc
   @@ -18,123 +18,160 @@
   + * Drupal supports transactions, including a transparent fallback for
     * databases that do not support transactions. To start a new transaction,
   

   We're likely to remove the transparent fallback logic, as it's kinda broken right now: #2278971: Deprecate Connection::supportsTransactions()

+ * In this context, "simple" means a query that does not involve a LIKE
+ * or any SQL functions.

* For SELECT queries involving LIKE, joins, or any SQL functions, instead of
* using the db_query() and db_query_range() functions,

Complicated. What DBTNG does, if your conditions has a single operator ->condition('d.data', "% $key %", 'LIKE') then yes DBTNG can and will map your LIKE per database driver. However when using functions in the select part db_query('SELECT CONCAT(:a1, CONCAT(name, CONCAT(:a2, CONCAT(age, :a3)))) FROM {test} WHERE age = :age', then that's fine.

JOINs are very fine in a db_query().

When you absolutely must use the query builder is when the query string (without arguments) is not a fixed string; when the query string itself is dynamic. That immediately mandates db_select because otherwise you will create a sechole (even core did have a weakness relating to that although not an outright sechole).

I hope this explains it; sorry for not being able to put it into succint words. I would be glad helping in wordsmithing this. And yes, this is in the current docs and yes the current docs is incorrect.

Let's do this, we can bikeshed more later.

Committed and pushed to 8.x. Thanks!