Merge pull request #6049 from kenjis/fix-docs-database/configuration.rst

docs: improve database/configuration.rst

user_guide_src/source/database/configuration.rst

@@ -6,6 +6,10 @@ Database Configuration
     :local:
     :depth: 2
 
+***********
+Config File
+***********
+
 CodeIgniter has a config file that lets you store your database
 connection values (username, password, database name, etc.). The config
 file is located at **app/Config/Database.php**. You can also set
@@ -22,6 +26,9 @@ while connecting to specify a group name.
 .. note:: The default location of the SQLite3 database is in the ``writable`` folder.
     If you want to change the location, you must set the full path to the new folder.
 
+DSN
+===
+
 Some database drivers (such as PDO, PostgreSQL, Oracle, ODBC) might
 require a full DSN string to be provided. If that is the case, you
 should use the 'DSN' configuration setting, as if you're using the
@@ -45,6 +52,9 @@ add the config variables as a query string:
     database character set), which are present in the rest of the configuration
     fields, CodeIgniter will append them.
 
+Failovers
+=========
+
 You can also specify failovers for the situation when the main connection cannot connect for some reason.
 These failovers can be specified by setting the failover for a connection like this:
 
@@ -69,14 +79,18 @@ variable located in the config file:
     default we've used the word "default" for the primary connection,
     but it too can be renamed to something more relevant to your project.
 
+defaultGroup
+============
+
 You could modify the config file to detect the environment and automatically
 update the `defaultGroup` value to the correct one by adding the required logic
 within the class' constructor:
 
 .. literalinclude:: configuration/008.php
 
-Configuring With .env File
---------------------------
+**************************
+Configuring with .env File
+**************************
 
 You can also save your configuration values within a **.env** file with the current server's
 database settings. You only need to enter the values that change from what is in the
@@ -87,10 +101,9 @@ default group's configuration settings. The values should be name following this
     database.default.password = '';
     database.default.database = 'ci4';
 
-As with all other
-
+**********************
 Explanation of Values:
-----------------------
+**********************
 
 ==============  ===========================================================================================================
  Name Config    Description
@@ -100,34 +113,28 @@ Explanation of Values:
 **username**    The username used to connect to the database.
 **password**    The password used to connect to the database.
 **database**    The name of the database you want to connect to.
-**DBDriver**    The database type. e.g.,: MySQLi, Postgre, etc. The case must match the driver name
+**DBDriver**    The database type. e.g.,: ``MySQLi``, ``Postgres``, etc. The case must match the driver name
 **DBPrefix**    An optional table prefix which will added to the table name when running
                 :doc:`Query Builder <query_builder>` queries. This permits multiple CodeIgniter
                 installations to share one database.
 **pConnect**    true/false (boolean) - Whether to use a persistent connection.
 **DBDebug**     true/false (boolean) - Whether database errors should be displayed.
 **charset**     The character set used in communicating with the database.
-**DBCollat**    The character collation used in communicating with the database
-
-                .. note:: Only used in the 'MySQLi' driver.
-
-**swapPre**     A default table prefix that should be swapped with dbprefix. This is useful for distributed
+**DBCollat**    The character collation used in communicating with the database (``MySQLi`` only)
+**swapPre**     A default table prefix that should be swapped with ``DBPrefix``. This is useful for distributed
                 applications where you might run manually written queries, and need the prefix to still be
                 customizable by the end user.
-**schema**      The database schema, default value varies by driver. Used by PostgreSQL and SQLSRV drivers.
+**schema**      The database schema, default value varies by driver. Used by ``Postgres`` and ``SQLSRV`` drivers.
 **encrypt**     Whether or not to use an encrypted connection.
-
-                - 'sqlsrv' and 'pdo/sqlsrv' drivers accept true/false
-                - 'MySQLi' and 'pdo/mysql' drivers accept an array with the following options:
-
-                    - 'ssl_key'    - Path to the private key file
-                    - 'ssl_cert'   - Path to the public key certificate file
-                    - 'ssl_ca'     - Path to the certificate authority file
-                    - 'ssl_capath' - Path to a directory containing trusted CA certificates in PEM format
-                    - 'ssl_cipher' - List of *allowed* ciphers to be used for the encryption, separated by colons (':')
-                    - 'ssl_verify' - true/false; Whether to verify the server certificate or not ('MySQLi' only)
-
-**compress**    Whether or not to use client compression (MySQL only).
+                ``SQLSRV`` drivers accept true/false
+                ``MySQLi`` drivers accept an array with the following options:
+                * ``ssl_key``    - Path to the private key file
+                * ``ssl_cert``   - Path to the public key certificate file
+                * ``ssl_ca``     - Path to the certificate authority file
+                * ``ssl_capath`` - Path to a directory containing trusted CA certificates in PEM format
+                * ``ssl_cipher`` - List of *allowed* ciphers to be used for the encryption, separated by colons (``:``)
+                * ``ssl_verify`` - true/false; Whether to verify the server certificate or not (``MySQLi`` only)
+**compress**    Whether or not to use client compression (``MySQLi`` only).
 **strictOn**    true/false (boolean) - Whether to force "Strict Mode" connections, good for ensuring strict SQL
                 while developing an application.
 **port**        The database port number. To use this value you have to add a line to the database config array.

user_guide_src/source/database/configuration/001.php

@@ -23,6 +23,7 @@ class Database extends Config
         'compress' => false,
         'strictOn' => false,
         'failover' => [],
+        'port'     => 3306,
     ];
 
     // ...

user_guide_src/source/database/configuration/002.php

@@ -1,7 +1,13 @@
 <?php
 
 // PDO
-$default['DSN'] = 'pgsql:host=localhost;port=5432;dbname=database_name';
+$default = [
+    'DSN' => 'pgsql:host=localhost;port=5432;dbname=database_name',
+    // ...
+];
 
 // Oracle
-$default['DSN'] = '//localhost/XE';
+$default = [
+    'DSN' => '//localhost/XE',
+    // ...
+];

user_guide_src/source/database/configuration/003.php

@@ -1,3 +1,6 @@
 <?php
 
-$default['DSN'] = 'DBDriver://username:password@hostname:port/database';
+$default = [
+    'DSN' => 'DBDriver://username:password@hostname:port/database',
+    // ...
+];

user_guide_src/source/database/configuration/004.php

@@ -1,6 +1,13 @@
 <?php
 
 // MySQLi
-$default['DSN'] = 'MySQLi://username:password@hostname:3306/database?charset=utf8&DBCollat=utf8_general_ci';
+$default = [
+    'DSN' => 'MySQLi://username:password@hostname:3306/database?charset=utf8&DBCollat=utf8_general_ci',
+    // ...
+];
+
 // Postgre
-$default['DSN'] = 'Postgre://username:password@hostname:5432/database?charset=utf8&connect_timeout=5&sslmode=1';
+$default = [
+    'DSN' => 'Postgre://username:password@hostname:5432/database?charset=utf8&connect_timeout=5&sslmode=1',
+    // ...
+];

user_guide_src/source/database/configuration/009.php

@@ -1,3 +1,6 @@
 <?php
 
-$default['port'] = 5432;
+$default = [
+    // ...
+    'port' => 5432,
+];