Database Services

The framework database boundary separates three concerns: Database::load selects and stores a connection, Query prepares SQL and bind values, and ResultInterface defines driver-neutral row and metadata access. The retrieved concrete connection implementations are MySQLi and Postgre; SQLite3 evidence covers a result adapter only.

This page covers imspr/system/Database/.... It does not describe the embedded phpMyAdmin administration database surface.

[!WARNING] The retrieved evidence is source-declared, not runtime-observed: no enclosing caller, registration, lifecycle boundary, or execution record establishes deployment reachability or successful execution. The database configuration file contains source defaults, including MySQLi for the default group and SQLite3 for the tests group; these do not establish deployed values. No SQLite3 Connection implementation was retrieved.

Connection selection and storage

In imspr/system/Database/Database.php, Database::load requires a non-empty DBDriver parameter. An empty value causes an InvalidArgumentException.

For a non-qualified driver name, the loader constructs the corresponding CodeIgniter\Database\<DBDriver>\Connection class name. A qualified class name is retained and suffixed with \Connection. The loader then constructs that class with the supplied parameter array, stores it under the supplied alias, and returns the connection stored at that alias.

The loader dynamically names the requested class. A configured driver therefore still requires a corresponding loadable Connection implementation; the loader does not prove that every named driver can be instantiated.

Query and result contracts

The query abstraction is declared by imspr/system/Database/QueryInterface.php and implemented by imspr/system/Database/Query.php.

Contract Source-defined behavior
QueryInterface::setQuery Declares setQuery(string $sql, $binds = null, bool $setEscape = true) as the query setup entry point.
Query::setQuery Stores the original SQL. A scalar bind becomes a one-element array. When setEscape is true, each bind is stored with its value and escape flag.
Query::getQuery Initializes the final SQL from the original SQL when needed, compiles binds, and returns the final query string.
Query::compileBinds Leaves the SQL unchanged when there are no applicable binds or markers. Named binds are reversed before duplicate-placeholder processing. If the SQL contains any colon, compilation calls named matching; otherwise it calls simple matching. Simple matching returns the original SQL when bind and marker counts do not match.
ResultInterface collection access getResult() defaults to object output; getResultArray() and getResultObject() provide explicit array and object collection forms.
ResultInterface row access getRow() and getRowArray() provide indexed access. getNextRow() and getUnbufferedRow() provide sequential access. getCustomResultObject() requests a named class.
ResultInterface metadata and lifecycle getFieldCount(), getFieldNames(), and getFieldData() expose result metadata. dataSeek() moves the cursor, and freeResult() releases the result.

The result contract is declared in imspr/system/Database/ResultInterface.php. The SQLite3 adapter in imspr/system/Database/SQLite3/Result.php supplies driver-specific behavior for part of that contract:

  • fetchObject first retrieves an associative row and returns false when no row is available.
  • With the default stdClass target, it casts the row to an object.
  • With an Entity subclass, it populates the object through setAttributes; other requested classes receive the row fields through property assignment.
  • getFieldCount uses SQLite3 numColumns().
  • getFieldData obtains names and column types from SQLite3, maps integer, float, text, blob, and null types to labels, and sets max_length to null.
  • dataSeek supports only offset 0, which resets the native cursor. Any other offset raises DatabaseException.

Retrieved connection behavior

The retrieved peer implementations are defined in imspr/system/Database/MySQLi/Connection.php and imspr/system/Database/Postgre/Connection.php.

Implementation Connection setup Query execution Material limitations
MySQLi Connection (DBDriver = 'MySQLi') connect calls real_connect with the configured host, username, password, database, port or socket, and client flags. It applies the configured character set afterward and returns the MySQLi handle on the successful branch. execute clears prior additional result sets, applies prepQuery, and passes the prepared SQL to mysqli::query. SSL downgrade and character-set failure branches log and return false when debugging is disabled. With debugging enabled, each branch instantiates DatabaseException; the enclosing catch masks configured username and password values and rethrows mysqli_sql_exception, which is the externally visible exception type.
Postgre Connection (DBDriver = 'postgre') connect builds a DSN when needed, removes a leading pgsql: prefix, converts semicolons to spaces, and selects pg_connect or pg_pconnect from the persistent flag. After connection it checks persistent-connection health, applies the schema search path, and sets client encoding. execute passes the supplied SQL directly to pg_query with the current connection handle. A failed persistent health check or client-encoding check returns false. setDatabase accepts a database name but always returns false; this driver does not implement database switching through that method.

Updated