fix(eloquent): connect to SQLite when WordPress runs on it

[gfazioli]

Closes #110.

The problem

Eloquent::init() always registered a mysql connection built from DB_HOST, DB_NAME, DB_USER and DB_PASSWORD. WordPress Playground, WordPress Studio and any site running the SQLite Database Integration plugin have no MySQL, so every Eloquent query failed there. On playground.wordpress.net the Database demo's Eloquent ORM page threw on every example.

The fix

The SQLite Database Integration plugin defines DB_ENGINE ('sqlite') and FQDB (the database file). It keeps WordPress's tables as plain SQLite tables under their MySQL names, and its text columns are COLLATE NOCASE, so comparisons stay case-insensitive as on MySQL.

Eloquent::connection() returns a sqlite connection on FQDB when DB_ENGINE is 'sqlite' and FQDB is defined. Otherwise it returns the same mysql connection as before, unchanged.

Measured on a local WordPress Playground (SQLite Database Integration 3.0.2, WP_MySQL_On_SQLite):

• the demo's queries return their values;
• a where('user_login', 'ADMIN') finds admin;
• a row written through Eloquent is read back by $wpdb.

One limit, which goes in the docs: a table created with Eloquent's schema builder is readable by $wpdb with SELECT, but SHOW TABLES and DESCRIBE don't list it. The plugin's MySQL emulation never learns about it. Tables still belong to WordPress (WP Bones migrations, dbDelta), and Eloquent works on their data.

Tests

• tests/Unit/EloquentTest.php has 4 tests, each in its own process because the constants can be defined only once:
  • MySQL by default, unchanged;
  • DB_ENGINE mysql stays MySQL;
  • SQLite uses the FQDB file and ignores Playground's sample MySQL credentials;
  • SQLite with no FQDB falls back to MySQL.
• The whole suite passes: 152 tests.
• Live, with .claude/scripts/eloquent-live-smoke.sh in the workspace:
  • on MySQL, the bench (which now has illuminate/database) registers a mysql connection and counts the same users as $wpdb;
  • on SQLite, the published Database boilerplate ZIP is unpacked, this branch's src/ replaces its framework, and it runs in npx @wp-playground/cli from a blueprint.

Check	v2.0.10	this branch
MySQL: the bench's connection is mysql, same user count as $wpdb	✓	✓
SQLite: the Eloquent ORM page renders to the end	✓ (wpkirk-helpers 2.0.13)	✓
SQLite: the 11 examples run without an exception	✗ 11 throw (Access denied for user 'username_here')	✓
SQLite: the page shows [email protected], iPad, Book iMac, Book iPod	✗	✓

[Copilot]

Copilot review overview

🟢 Approval recommended

No unresolved blocking issues were identified.

Review effort: Lite
Findings: None

What changed in this PR

Adds SQLite-aware Eloquent connections for WordPress while preserving MySQL behavior.

Changes:

• Selects SQLite using DB_ENGINE and FQDB.
• Preserves MySQL fallback behavior.
• Adds tests for MySQL, SQLite, and fallback configurations.

File	Description
tests/​Unit/​EloquentTest.php	Tests supported connection configurations.
src/​Database/​Eloquent.php	Implements database-aware connection selection.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.