Wp Sqlite Db Laravel Package

Getting Started

Minimal steps

1. Confirm the PHP extension is present: php -m | grep -i sqlite (you need pdo_sqlite). No MySQL server is needed.
2. Drop the package's db.php into wp-content/db.php. WordPress auto-detects any db.php drop-in and loads it instead of the stock wpdb MySQL path — no plugin activation required.
3. Check which flavor of db.php you have before you do anything else. Open it and look for a require of sqlite-database-integration. The modern release is a thin loader that expects the SQLite Database Integration plugin to be installed in wp-content/plugins/; older releases are a self-contained ~2k-line file. Pin one and document it — mixing the two is the #1 "why is this fataling" cause.
4. Leave DB_NAME/DB_USER/DB_HOST in wp-config.php (they're ignored, but core and plugins read them), and optionally steer the file location before wp-settings.php loads:

// wp-config.php — must be absolute paths, defined before bootstrap
define( 'DB_DIR',  dirname( __DIR__ ) . '/database/' ); // outside webroot if you can
define( 'DB_FILE', '.ht.sqlite' );

5. Run wp core install --url=... --admin_user=... as usual. The database file appears at wp-content/database/.ht.sqlite.

Where to look first

• wp-content/db.php — the WP_SQLite_DB class (historically wpdb subclass). Read query(), the MySQL→SQLite translator, and __construct() where the PDO handle and pragmas are set.
• wp-content/database/ — the DB file plus the .htaccess/index.php guard it writes.
• $wpdb->db_version() — returns the SQLite version, not MySQL. Useful for sanity checks; a trap for plugins doing version gating.

First use case

Local plugin/theme development and CI: replace "install MySQL, create a database, wire up credentials" with a committed db.php and a throwaway .ht.sqlite. Resetting state is rm plus wp core install, which makes it ideal for test harnesses, throwaway demo sites, and containers where you don't want a database service.

Implementation Patterns

Deterministic local reset Add a make/composer target that deletes and re-seeds the database file instead of dropping tables. Pair it with a fixture:

rm -f wp-content/database/.ht.sqlite*
wp core install --url=http://localhost:8080 --title=Dev --admin_user=admin \
  --admin_password=admin [email protected] --skip-email
wp import fixtures/seed.xml --authors=create

CI without a database service Docker images drop the mysql service and the wait-for-mysql step entirely; the WordPress bootstrap is a single container. This is the single biggest win of the package — cold-start CI gets noticeably shorter. Guard for the plugin requirement by vendoring the SQLite integration plugin into the image at build time rather than installing it at runtime.

Seeding a shippable demo Because the whole site is one file, you can ship a pre-populated .ht.sqlite inside a Docker image or a "try it" sandbox and get a working WordPress on first boot. Treat it as read-only in that mode: bake the file in at build time rather than letting the container write to it.

Composer / Bedrock composer require aaemnnosttv/wp-sqlite-db gets you the file; you still have to place it. Add a post-install-cmd script that copies vendor/aaemnnosttv/wp-sqlite-db/src/db.php to web/app/db.php (Bedrock's content dir), and add web/app/database/ to .gitignore unless you want the seeded DB committed.

Inspection and search-replace workflow Reach for the sqlite3 CLI where you'd normally use mysql:

sqlite3 wp-content/database/.ht.sqlite '.tables'
sqlite3 wp-content/database/.ht.sqlite '.schema wp_options'
sqlite3 wp-content/database/.ht.sqlite "select option_name from wp_options where option_name like '%cache%';"

wp search-replace and wp export/wp import still work because they go through $wpdb; it's the subcommands that shell out to mysqldump (wp db export, wp db cli, sometimes wp db query) that are unreliable.

Backups Copy the file, not the database server. If WAL is on, copy -wal and -shm alongside it, or checkpoint first. A sqlite3 .ht.sqlite .dump > backup.sql is a portable escape hatch.

Escaping SQLite Keep an export path in the project docs: wp export to WXR, or migrate back to MySQL via the integration plugin's admin tools. Design your local workflow so the SQLite file is disposable — never the system of record.

Gotchas and Tips

• mysqli_* calls bypass the drop-in. Anything that talks to mysqli/mysql directly instead of $wpdb (some caching, backup, and analytics plugins) will fatal. The drop-in ships stub polyfills so WordPress's own wp_check_php_mysql_versions() passes — so "Your PHP installation appears to be missing the MySQL extension" almost always means your db.php isn't being picked up: wrong path (wp-content/db.php, not wp-content/plugins/db.php), unreadable file, or a stale opcache.
• Regex-based query translation is whitespace- and comment-sensitive. If a raw query from a plugin fails to translate, the fix is usually to normalize it — strip /* ... */ comments, collapse newlines, avoid exotic DDL. This is the first thing to try when you see a syntax error that "works on MySQL."
• MySQL-isms that break: SHOW TABLE STATUS, information_schema lookups, FULLTEXT indexes and MATCH ... AGAINST, SPATIAL types, ALTER TABLE ... MODIFY, ON DUPLICATE KEY UPDATE (translated to INSERT OR REPLACE in most builds, which changes semantics — REPLACE deletes and re-inserts, firing different triggers and changing rowids), and ORDER BY RAND() in some versions. Audit any plugin that hand-rolls SQL.
• dbDelta() is only partially reliable. Simple CREATE TABLE/ADD COLUMN is fine; complex index definitions, UNSIGNED, collations, and foreign keys may be dropped silently. Verify schema after activation with .schema.
• Concurrency. SQLite serializes writes and gives one writer at a time. "Database is locked" under load is expected, not a bug. Mitigations: keep transactions short, add a persistent object cache, and — on Docker for macOS/Windows — use a named volume, not a bind mount, because the filesystem layer breaks SQLite's locking. Never put the DB file on NFS.
• Web exposure. Apache is protected by the generated .htaccess; Nginx is not. Add location ~* /wp-content/database/ { deny all; } or move the DB outside the webroot with DB_DIR. This is the most common security mistake with this stack.
• Permissions. The web user needs write access to both the directory and the file. Read-only container filesystems, immutable images, and serverless hosts will fail — copy the DB to a writable path at boot.
• Version-gating plugins. $wpdb->db_version() returns something like 3.45.1, and db_server_info() isn't MySQL. Plugins comparing against '5.7' will take odd branches. Don't use this stack to test those plugins.
• Constants, not filters. DB_DIR/DB_FILE (or FQDB/FQDBDIR in older builds) must be defined before bootstrap; there's no runtime filter for the path. For deeper customization, subclass the drop-in's WP_SQLite_DB in a mu-plugin-loaded file and assign your own $wpdb — the class boundary is the extension point, not a hook API.
• Debugging. SAVEQUERIES and $wpdb->last_error work normally; add define( 'WP_DEBUG', true ) and log the translated SQL when a query misbehaves. For the loader-style release, remember the engine lives in the plugin — report bugs against the right repo, and check wp plugin list shows the integration plugin active/present before blaming the drop-in.
• Multisite works but concentrates everything in one file, so one lock blocks all sites. Fine for dev, questionable for anything with real write traffic.