DB Connect can accept a database instance without breaking. Tested and documented that fact.

Author: lonnieezell

system/Database/Config.php

@@ -74,6 +74,12 @@ class Config extends BaseConfig
 	 */
 	public static function connect($group = null, bool $getShared = true)
 	{
+		// If a DB connection is passed in, just pass it back
+		if ($group instanceof BaseConnection)
+		{
+			return $group;
+		}
+
 		if (is_array($group))
 		{
 			$config = $group;

tests/system/Database/Live/ConnectTest.php

@@ -1,7 +1,6 @@
-<?php namespace CodeIgniter\Database\Live;
-
-;
+<?php namespace CodeIgniter\Database\Live;;
 
+use CodeIgniter\Config\Config;
 use CodeIgniter\Test\CIDatabaseTestCase;
 use Config\Database;
 
@@ -20,8 +19,8 @@ protected function setUp()
 		$this->group1 = $config->default;
 		$this->group2 = $config->default;
 
-		$this->group1['strictOn'] = false;
-		$this->group2['strictOn'] = true;
+		$this->group1['DBDriver'] = 'MySQLi';
+		$this->group2['DBDriver'] = 'Postgre';
 	}
 
 	public function testConnectWithMultipleCustomGroups()
@@ -39,6 +38,32 @@ public function testConnectWithMultipleCustomGroups()
 		$this->assertEquals(3, count($instances));
 	}
 
-	//--------------------------------------------------------------------
+	public function testConnectReturnsProvidedConnection()
+	{
+		// This will be the tests database
+		$db = Database::connect();
+		$this->assertInstanceOf(\CodeIgniter\Database\SQLite3\Connection::class, $db);
+
+		// Get an instance of the system's default db so we have something to test with.
+		$db1 = Database::connect($this->group1);
+		$this->assertEquals('MySQLi', $this->getPrivateProperty($db1, 'DBDriver'));
+
+		// If a connection is passed into connect, it should simply be returned to us...
+		$db2 = Database::connect($db1);
+		$this->assertSame($db1, $db2);
+	}
 
+	public function testConnectWorksWithGroupName()
+	{
+		$db = Database::connect('tests');
+		$this->assertInstanceOf(\CodeIgniter\Database\SQLite3\Connection::class, $db);
+
+		$config = config('Database');
+		$config->default['DBDriver'] = 'MySQLi';
+		Config::injectMock('Database', $config);
+
+		$db1 = Database::connect('default');
+		$this->assertNotInstanceOf(\CodeIgniter\Database\SQLite3\Connection::class, $db1);
+		$this->assertEquals('MySQLi', $this->getPrivateProperty($db1, 'DBDriver'));
+	}
 }

user_guide_src/source/database/connecting.rst

@@ -61,6 +61,37 @@ group names you are connecting to.
 
 	| $db->setDatabase($database2_name);
 
+Connecting with Custom Settings
+===============================
+
+You can pass in an array of database settings instead of a group name to get
+a connection that uses your custom settings. The array passed in must be
+the same format as the groups are defined in the configuration file::
+
+    $custom = [
+		'DSN'      => '',
+		'hostname' => 'localhost',
+		'username' => '',
+		'password' => '',
+		'database' => '',
+		'DBDriver' => 'MySQLi',
+		'DBPrefix' => '',
+		'pConnect' => false,
+		'DBDebug'  => (ENVIRONMENT !== 'production'),
+		'cacheOn'  => false,
+		'cacheDir' => '',
+		'charset'  => 'utf8',
+		'DBCollat' => 'utf8_general_ci',
+		'swapPre'  => '',
+		'encrypt'  => false,
+		'compress' => false,
+		'strictOn' => false,
+		'failover' => [],
+		'port'     => 3306,
+	];
+    $db = \Config\Database::connect($custom); 
+
+
 Reconnecting / Keeping the Connection Alive
 ===========================================