Add setInstance() support for runtime database switching

从 system/Database/Config.php 开始，阅读现有的 Config::connect() 流程，包括 ensureFactory()、factory 加载调用以及实例存储。将提议的 setInstance() 行为与该流程进行比较，并确定自定义配置以及后续 connect('tenant') 调用的验收情况。

PHP Version

8.3

CodeIgniter4 Version

4.6.1

CodeIgniter4 Installation Method

Composer (using codeigniter4/appstarter)

Which operating systems have you tested for this bug?

Windows

Which server did you use?

apache

Database

MySQL

What happened?

I would like to request a new method in Config\Database that allows developers to set or override a database connection instance at runtime without modifying the framework core.

This is especially useful when a project needs dynamic database switching, such as in:

Multi-tenant SaaS applications

ERP systems with client-specific databases

“Switch DB per request” API requirements

Dynamic “connect with custom credentials” scenarios

Currently, CodeIgniter 4 allows Database::connect($group) but there is no official method to replace or inject a database instance for a given group.

Proposed Method

Add this method in system/Database/Config.php:

public static function setInstance(string $group, array $config)
{
static::ensureFactory();

$connection = static::$factory->load($config, $group);

static::$instances[$group] = $connection;

return $connection;

}

Why this is needed

Today, Database::connect() always loads config from app/Config/Database.php.

To use a custom connection (hostname, username, password, database), we must create a fake group name or override config objects — both are hacky.

Dynamic DB switching is common in modern SaaS, ERP, and enterprise applications.

This addition would provide a clean, supported API for runtime DB instance control.

Example Use Case
$dbConfig = [
'DSN' => '',
'hostname' => $tenantHost,
'username' => $tenantUser,
'password' => $tenantPass,
'database' => $tenantDb,
'DBDriver' => 'MySQLi',
'DBPrefix' => '',
];

$connection = \Config\Database::setInstance('tenant', $dbConfig);

$db = \Config\Database::connect('tenant');

This gives developers the power to switch databases safely and officially.

Backward Compatibility

This method does not change any existing behavior.

It only adds a new optional utility method.

No BC breaks.

Conclusion

This feature will make CodeIgniter 4 significantly more flexible for advanced and enterprise applications that require dynamic DB switching.

Thank you for considering this enhancement! 🙏

Steps to Reproduce

I would like to request a new method in Config\Database that allows developers to set or override a database connection instance at runtime without modifying the framework core.

This is especially useful when a project needs dynamic database switching, such as in:

Multi-tenant SaaS applications

ERP systems with client-specific databases

“Switch DB per request” API requirements

Dynamic “connect with custom credentials” scenarios

Currently, CodeIgniter 4 allows Database::connect($group) but there is no official method to replace or inject a database instance for a given group.

Proposed Method

Add this method in system/Database/Config.php:

public static function setInstance(string $group, array $config)
{
static::ensureFactory();

$connection = static::$factory->load($config, $group);

static::$instances[$group] = $connection;

return $connection;

}

Why this is needed

Today, Database::connect() always loads config from app/Config/Database.php.

To use a custom connection (hostname, username, password, database), we must create a fake group name or override config objects — both are hacky.

Dynamic DB switching is common in modern SaaS, ERP, and enterprise applications.

This addition would provide a clean, supported API for runtime DB instance control.

Example Use Case
$dbConfig = [
'DSN' => '',
'hostname' => $tenantHost,
'username' => $tenantUser,
'password' => $tenantPass,
'database' => $tenantDb,
'DBDriver' => 'MySQLi',
'DBPrefix' => '',
];

$connection = \Config\Database::setInstance('tenant', $dbConfig);

$db = \Config\Database::connect('tenant');

This gives developers the power to switch databases safely and officially.

Backward Compatibility

This method does not change any existing behavior.

It only adds a new optional utility method.

No BC breaks.

Conclusion

This feature will make CodeIgniter 4 significantly more flexible for advanced and enterprise applications that require dynamic DB switching.

Thank you for considering this enhancement! 🙏

Expected Output

I would like to request a new method in Config\Database that allows developers to set or override a database connection instance at runtime without modifying the framework core.

This is especially useful when a project needs dynamic database switching, such as in:

Multi-tenant SaaS applications

ERP systems with client-specific databases

“Switch DB per request” API requirements

Dynamic “connect with custom credentials” scenarios

Currently, CodeIgniter 4 allows Database::connect($group) but there is no official method to replace or inject a database instance for a given group.

Proposed Method

Add this method in system/Database/Config.php:

public static function setInstance(string $group, array $config)
{
static::ensureFactory();

$connection = static::$factory->load($config, $group);

static::$instances[$group] = $connection;

return $connection;

}

Why this is needed

Today, Database::connect() always loads config from app/Config/Database.php.

To use a custom connection (hostname, username, password, database), we must create a fake group name or override config objects — both are hacky.

Dynamic DB switching is common in modern SaaS, ERP, and enterprise applications.

This addition would provide a clean, supported API for runtime DB instance control.

Example Use Case
$dbConfig = [
'DSN' => '',
'hostname' => $tenantHost,
'username' => $tenantUser,
'password' => $tenantPass,
'database' => $tenantDb,
'DBDriver' => 'MySQLi',
'DBPrefix' => '',
];

$connection = \Config\Database::setInstance('tenant', $dbConfig);

$db = \Config\Database::connect('tenant');

This gives developers the power to switch databases safely and officially.

Backward Compatibility

This method does not change any existing behavior.

It only adds a new optional utility method.

No BC breaks.

Conclusion

This feature will make CodeIgniter 4 significantly more flexible for advanced and enterprise applications that require dynamic DB switching.

Thank you for considering this enhancement! 🙏

Anything else?

No response