- Patch #19474 by Daniel: extended documentation on database configuration.

sites/default/settings.php

@@ -37,21 +37,42 @@
  *
  * Note that the $db_url variable gets parsed using PHP's built-in
  * URL parser (i.e. using the "parse_url()" function) so make sure
- * not to confuse the parser. In practice, you should avoid using
- * special characters that are not used in "normal" URLs either.
- * That is, the use of ':', '/', '@', '?', '=' and '#', ''', '"',
- * and so on is likely to confuse the parser; use alpha-numerical
- * characters instead.
+ * not to confuse the parser. If your db_user, db_password,
+ * db_hostname, or db_name contain characters used to delineate
+ * $db_url parts, you can escape them via URI hex encodings:
+ *
+ *   : = %3a   / = %2f   @ = %40
+ *   + = %2b   ( = %28   ) = %29
+ *   ? = %3f   = = %3d   & = %26
  *
  * To specify multiple connections to be used in your site (i.e. for
  * complex custom modules) you can also specify an associative array
  * of $db_url variables with the 'default' element used until otherwise
  * requested.
  *
- * If an optional $db_prefix is specified, all database table names
- * will be prepended with this string. Be sure to use valid database
- * characters only, usually alphanumeric and underscore. If no
- * prefixes are desired, set to empty string ''.
+ * You can optionally set prefixes for some or all database table names
+ * by using the $db_prefix setting. If a prefix is specified, the table
+ * name will be prepended with its value. Be sure to use valid database
+ * characters only, usually alphanumeric and underscore. If no prefixes
+ * are desired, leave it as an empty string ''.
+ *
+ * To have all database names prefixed, set $db_prefix as a string:
+ *
+ *   $db_prefix = 'main_';
+ *
+ * To provide prefixes for specific tables, set $db_prefix as an array.
+ * The array's keys are the table names and the values are the prefixes.
+ * The 'default' element holds the prefix for any tables not specified
+ * elsewhere in the array. Example:
+ *
+ *   $db_prefix = array(
+ *     'default'   => 'main_',
+ *     'users'     => 'shared_',
+ *     'sessions'  => 'shared_',
+ *     'role'      => 'shared_',
+ *     'authmap'   => 'shared_',
+ *     'sequences' => 'shared_',
+ *   );
  *
  * Database URL format:
  * $db_url = 'mysql://db_user:db_password@db_hostname/db_name';