Skip to content

Commit e936bb3

Browse files
kenjiskenjis
authored
Merge pull request #7555 from kenjis/fix-docs-database-configuration.rst
docs: fix database/configuration.rst
2 parents 99b93bf + faaadd6 commit e936bb3

9 files changed

Lines changed: 156 additions & 73 deletions

File tree

‎user_guide_src/source/database/configuration.rst‎

Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Database Configuration
44

55
.. contents::
66
:local:
7-
:depth: 2
7+
:depth: 3
88

99
.. note::
1010
See :ref:`requirements-supported-databases` for currently supported database drivers.
@@ -18,6 +18,9 @@ connection values (username, password, database name, etc.). The config
1818
file is located at **app/Config/Database.php**. You can also set
1919
database connection values in the **.env** file. See below for more details.
2020

21+
Setting Default Database
22+
========================
23+
2124
The config settings are stored in a class property that is an array with this
2225
prototype:
2326

@@ -26,37 +29,45 @@ prototype:
2629
The name of the class property is the connection name, and can be used
2730
while connecting to specify a group name.
2831

29-
.. note:: The default location of the SQLite3 database is in the ``writable`` folder.
32+
.. note:: The default location of the SQLite3 database is in the **writable** folder.
3033
If you want to change the location, you must set the full path to the new folder.
3134

3235
DSN
33-
===
36+
---
37+
38+
Some database drivers (such as Postgre, OCI8) requires a full DSN string to connect.
39+
But if you do not specify a DSN string for a driver that requires it, CodeIgniter
40+
will try to build it with the rest of the provided settings.
3441

35-
Some database drivers (such as PDO, PostgreSQL, Oracle, ODBC) might
36-
require a full DSN string to be provided. If that is the case, you
37-
should use the 'DSN' configuration setting, as if you're using the
38-
driver's underlying native PHP extension, like this:
42+
If you specify a DSN, you should use the ``'DSN'`` configuration setting, as if
43+
you're using the driver's underlying native PHP extension, like this:
3944

4045
.. literalinclude:: configuration/002.php
46+
:lines: 11-15
4147

42-
.. note:: If you do not specify a DSN string for a driver that requires it, CodeIgniter
43-
will try to build it with the rest of the provided settings.
48+
DSN in Universal Manner
49+
^^^^^^^^^^^^^^^^^^^^^^^
4450

4551
You can also set a Data Source Name in universal manner (URL like). In that case DSNs must have this prototype:
4652

4753
.. literalinclude:: configuration/003.php
54+
:lines: 11-14
4855

4956
To override default config values when connecting with a universal version of the DSN string,
5057
add the config variables as a query string:
5158

5259
.. literalinclude:: configuration/004.php
60+
:lines: 11-15
61+
62+
.. literalinclude:: configuration/010.php
63+
:lines: 11-15
5364

5465
.. note:: If you provide a DSN string and it is missing some valid settings (e.g., the
5566
database character set), which are present in the rest of the configuration
5667
fields, CodeIgniter will append them.
5768

5869
Failovers
59-
=========
70+
---------
6071

6172
You can also specify failovers for the situation when the main connection cannot connect for some reason.
6273
These failovers can be specified by setting the failover for a connection like this:
@@ -65,6 +76,9 @@ These failovers can be specified by setting the failover for a connection like t
6576

6677
You can specify as many failovers as you like.
6778

79+
Setting Multiple Databases
80+
==========================
81+
6882
You may optionally store multiple sets of connection
6983
values. If, for example, you run multiple environments (development,
7084
production, test, etc.) under a single installation, you can set up a
@@ -78,15 +92,15 @@ variable located in the config file:
7892

7993
.. literalinclude:: configuration/007.php
8094

81-
.. note:: The name 'test' is arbitrary. It can be anything you want. By
82-
default we've used the word "default" for the primary connection,
95+
.. note:: The name ``test`` is arbitrary. It can be anything you want. By
96+
default we've used the word ``default`` for the primary connection,
8397
but it too can be renamed to something more relevant to your project.
8498

85-
defaultGroup
86-
============
99+
Changing Databases Automatically
100+
================================
87101

88102
You could modify the config file to detect the environment and automatically
89-
update the `defaultGroup` value to the correct one by adding the required logic
103+
update the ``defaultGroup`` value to the correct one by adding the required logic
90104
within the class' constructor:
91105

92106
.. literalinclude:: configuration/008.php
@@ -125,7 +139,7 @@ Explanation of Values:
125139
=============== ===========================================================================================================
126140
Name Config Description
127141
=============== ===========================================================================================================
128-
**dsn** The DSN connect string (an all-in-one configuration sequence).
142+
**DSN** The DSN connect string (an all-in-one configuration sequence).
129143
**hostname** The hostname of your database server. Often this is 'localhost'.
130144
**username** The username used to connect to the database. (``SQLite3`` does not use this.)
131145
**password** The password used to connect to the database. (``SQLite3`` does not use this.)

‎user_guide_src/source/database/configuration/001.php‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,17 @@
66

77
class Database extends Config
88
{
9-
public $default = [
9+
// ...
10+
11+
public array $default = [
1012
'DSN' => '',
1113
'hostname' => 'localhost',
1214
'username' => 'root',
1315
'password' => '',
1416
'database' => 'database_name',
1517
'DBDriver' => 'MySQLi',
1618
'DBPrefix' => '',
17-
'pConnect' => true,
19+
'pConnect' => false,
1820
'DBDebug' => true,
1921
'charset' => 'utf8',
2022
'DBCollat' => 'utf8_general_ci',

‎user_guide_src/source/database/configuration/002.php‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
11
<?php
22

3-
// PDO
4-
$default = [
5-
'DSN' => 'pgsql:host=localhost;port=5432;dbname=database_name',
3+
namespace Config;
4+
5+
use CodeIgniter\Database\Config;
6+
7+
class Database extends Config
8+
{
69
// ...
7-
];
810

9-
// Oracle
10-
$default = [
11-
'DSN' => '//localhost/XE',
11+
// OCI8
12+
public array $default = [
13+
'DSN' => '//localhost/XE',
14+
// ...
15+
];
16+
1217
// ...
13-
];
18+
}

‎user_guide_src/source/database/configuration/003.php‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,17 @@
11
<?php
22

3-
$default = [
4-
'DSN' => 'DBDriver://username:password@hostname:port/database',
3+
namespace Config;
4+
5+
use CodeIgniter\Database\Config;
6+
7+
class Database extends Config
8+
{
9+
// ...
10+
11+
public array $default = [
12+
'DSN' => 'DBDriver://username:password@hostname:port/database',
13+
// ...
14+
];
15+
516
// ...
6-
];
17+
}

‎user_guide_src/source/database/configuration/004.php‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
11
<?php
22

3-
// MySQLi
4-
$default = [
5-
'DSN' => 'MySQLi://username:password@hostname:3306/database?charset=utf8&DBCollat=utf8_general_ci',
3+
namespace Config;
4+
5+
use CodeIgniter\Database\Config;
6+
7+
class Database extends Config
8+
{
69
// ...
7-
];
810

9-
// Postgre
10-
$default = [
11-
'DSN' => 'Postgre://username:password@hostname:5432/database?charset=utf8&connect_timeout=5&sslmode=1',
11+
// MySQLi
12+
public array $default = [
13+
'DSN' => 'MySQLi://username:password@hostname:3306/database?charset=utf8&DBCollat=utf8_general_ci',
14+
// ...
15+
];
16+
1217
// ...
13-
];
18+
}

‎user_guide_src/source/database/configuration/005.php‎

Lines changed: 49 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,51 @@
11
<?php
22

3-
$default['failover'] = [
4-
[
5-
'hostname' => 'localhost1',
6-
'username' => '',
7-
'password' => '',
8-
'database' => '',
9-
'DBDriver' => 'MySQLi',
10-
'DBPrefix' => '',
11-
'pConnect' => true,
12-
'DBDebug' => true,
13-
'charset' => 'utf8',
14-
'DBCollat' => 'utf8_general_ci',
15-
'swapPre' => '',
16-
'encrypt' => false,
17-
'compress' => false,
18-
'strictOn' => false,
19-
],
20-
[
21-
'hostname' => 'localhost2',
22-
'username' => '',
23-
'password' => '',
24-
'database' => '',
25-
'DBDriver' => 'MySQLi',
26-
'DBPrefix' => '',
27-
'pConnect' => true,
28-
'DBDebug' => true,
29-
'charset' => 'utf8',
30-
'DBCollat' => 'utf8_general_ci',
31-
'swapPre' => '',
32-
'encrypt' => false,
33-
'compress' => false,
34-
'strictOn' => false,
35-
],
36-
];
3+
namespace Config;
4+
5+
use CodeIgniter\Database\Config;
6+
7+
class Database extends Config
8+
{
9+
// ...
10+
11+
public array $default = [
12+
// ...
13+
'failover' => [
14+
[
15+
'hostname' => 'localhost1',
16+
'username' => '',
17+
'password' => '',
18+
'database' => '',
19+
'DBDriver' => 'MySQLi',
20+
'DBPrefix' => '',
21+
'pConnect' => true,
22+
'DBDebug' => true,
23+
'charset' => 'utf8',
24+
'DBCollat' => 'utf8_general_ci',
25+
'swapPre' => '',
26+
'encrypt' => false,
27+
'compress' => false,
28+
'strictOn' => false,
29+
],
30+
[
31+
'hostname' => 'localhost2',
32+
'username' => '',
33+
'password' => '',
34+
'database' => '',
35+
'DBDriver' => 'MySQLi',
36+
'DBPrefix' => '',
37+
'pConnect' => true,
38+
'DBDebug' => true,
39+
'charset' => 'utf8',
40+
'DBCollat' => 'utf8_general_ci',
41+
'swapPre' => '',
42+
'encrypt' => false,
43+
'compress' => false,
44+
'strictOn' => false,
45+
],
46+
],
47+
// ...
48+
];
49+
50+
// ...
51+
}

‎user_guide_src/source/database/configuration/006.php‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66

77
class Database extends Config
88
{
9-
public $test = [
9+
// ...
10+
11+
public array $test = [
1012
'DSN' => '',
1113
'hostname' => 'localhost',
1214
'username' => 'root',

‎user_guide_src/source/database/configuration/007.php‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
11
<?php
22

3-
$defaultGroup = 'test';
3+
namespace Config;
4+
5+
use CodeIgniter\Database\Config;
6+
7+
class Database extends Config
8+
{
9+
// ...
10+
11+
public string $defaultGroup = 'test';
12+
13+
// ...
14+
}

‎user_guide_src/source/database/configuration/010.php‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<?php
2+
3+
namespace Config;
4+
5+
use CodeIgniter\Database\Config;
6+
7+
class Database extends Config
8+
{
9+
// ...
10+
11+
// Postgre
12+
public array $default = [
13+
'DSN' => 'Postgre://username:password@hostname:5432/database?charset=utf8&connect_timeout=5&sslmode=1',
14+
// ...
15+
];
16+
17+
// ...
18+
}

0 commit comments

Comments
 (0)