Document SQLite database storage and DB_PATH

README.md

@@ -14,7 +14,7 @@ It is a monorepo that includes the following components:
 - **MySQL parser** — An exhaustive MySQL parser with multi-version support.
 - [**MySQL on SQLite**](packages/mysql-on-sqlite/) — A MySQL emulation layer on top of SQLite with a PDO-compatible API.
 - [**MySQL proxy**](packages/mysql-proxy/) — A MySQL binary protocol implementation to support MySQL-based projects beyond PHP.
-- **WordPress plugin** — A plugin that adds SQLite support to WordPress.
+- [**WordPress plugin**](packages/plugin-sqlite-database-integration/) — A plugin that adds SQLite support to WordPress.
 - **Test suites** — A set of extensive test suites to cover MySQL syntax and functionality.
 
 The monorepo packages are placed under the `packages` directory.

bin/build-sqlite-plugin-zip.sh

@@ -27,6 +27,7 @@ rm "$PLUGIN_DIR/wp-includes/database"
 cp -R "$DIR/packages/mysql-on-sqlite/src" "$PLUGIN_DIR/wp-includes/database"
 
 # Remove dev-only files.
+rm -f "$PLUGIN_DIR/README.md"
 rm -rf "$PLUGIN_DIR/composer.json"
 rm -rf "$PLUGIN_DIR/vendor"
 rm -rf "$PLUGIN_DIR/node_modules"

packages/plugin-sqlite-database-integration/README.md

@@ -0,0 +1,93 @@
+# SQLite Database Integration
+
+Run WordPress on SQLite.
+
+## Overview
+
+The plugin provides a `wp-content/db.php` database drop-in powered by
+[MySQL on SQLite](../mysql-on-sqlite/). WordPress and plugins continue to use the
+`wpdb` API while the driver translates and emulates MySQL queries for SQLite.
+
+## Usage
+
+To set up SQLite, do the following steps in your WordPress admin:
+
+1. Install and activate the plugin.
+2. Open **Settings > SQLite integration** and select **Install SQLite database**.
+
+On multisite installs, use Network Admin.
+
+> [!IMPORTANT]
+> Enabling SQLite creates a separate SQLite database. It does not migrate data
+> from MySQL or MariaDB. Disabling it reconnects WordPress to the original database.
+
+See [readme.txt](readme.txt) for the plugin FAQ and changelog.
+
+## Database storage
+
+By default, the SQLite database is stored in a **randomized path** under
+`WP_CONTENT_DIR . '/database'`. The full path is recorded in `db-path.php`
+and exposed by the `DB_PATH` constant at runtime.
+
+For example:
+
+1. Database path: `WP_CONTENT_DIR . '/database/.ht.020a33c5d9e5407e8e93b43e55abf62e/.ht.sqlite'`
+2. Recorded in: `WP_CONTENT_DIR . '/database/db-path.php'` as `return __DIR__ . '/...';`
+3. Exposed by: `DB_PATH`
+
+The random path makes the database location difficult to guess when it is not
+otherwise protected.
+
+To properly **secure the SQLite database**, define the `DB_PATH` constant to an
+**explicit path** that is protected from public web access. An explicit `DB_PATH`
+value is used as-is without randomization. Define it in `wp-config.php`:
+
+```php
+// Use protected DB path that is not exposed by the web server.
+define( 'DB_PATH', '/private/wordpress/database.sqlite' );
+```
+
+> [!CAUTION]
+> An explicit `DB_PATH` must point to a **protected** location that your web server
+> does not expose. Store the database outside the web root and make sure it's protected.
+
+The value of `DB_PATH` must be an absolute path to the SQLite database file, or `:memory:`
+for an in-memory SQLite database. The database directory must be writable by PHP. Changing
+`DB_PATH` selects a different database without moving an existing one.
+
+Integrations should always read `DB_PATH` after WordPress loads instead of assuming
+a fixed database path.
+
+## Development
+
+Run these commands from the repository root:
+
+```bash
+composer install
+composer run check-cs
+composer run wp-test-sqlite-plugin-php
+composer run wp-test-sqlite-plugin-php-multisite
+```
+
+See the [repository README](../../README.md#quick-start) for the WordPress test
+environment commands.
+
+Build an installable plugin ZIP with:
+
+```bash
+composer run build-sqlite-plugin-zip
+```
+
+The archive is written to `build/plugin-sqlite-database-integration.zip`.
+
+## Requirements
+
+- **WordPress:** 6.4+
+- **PHP:** 7.2+
+- **PHP extensions:** `pdo`, `pdo_sqlite`
+- **SQLite:** 3.37.0+
+
+## License
+
+SQLite Database Integration is licensed under the
+[GNU General Public License v2 or later](LICENSE).

packages/plugin-sqlite-database-integration/readme.txt

@@ -9,7 +9,7 @@ License:           GPLv2 or later
 License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 Tags:              sqlite, database
 
-Run WordPress on SQLite instead of MySQL or MariaDB.
+Run WordPress on SQLite.
 
 == Description ==
 
@@ -48,6 +48,31 @@ No. Enabling SQLite starts a fresh WordPress installation in a separate database
 
 Disabling the plugin reconnects WordPress to the previous database. Content created while using SQLite is not transferred back.
 
+= Where is the SQLite database stored? =
+
+By default, the SQLite database is stored in a **randomized path** under `WP_CONTENT_DIR . '/database'`. The full path is recorded in `db-path.php` and exposed by the `DB_PATH` constant at runtime.
+
+For example:
+
+1. Database path: `WP_CONTENT_DIR . '/database/.ht.020a33c5d9e5407e8e93b43e55abf62e/.ht.sqlite'`
+2. Recorded in: `WP_CONTENT_DIR . '/database/db-path.php'` as `return __DIR__ . '/...';`
+3. Exposed by: `DB_PATH`
+
+The random path makes the database location difficult to guess when it is not otherwise protected. We recommend setting `DB_PATH` to an **explicit, protected path** outside the web root that your web server does not expose.
+
+Integrations should always read `DB_PATH` after WordPress loads instead of assuming a fixed database path.
+
+= How can I configure the database location? =
+
+To properly **secure the SQLite database**, define the `DB_PATH` constant to an **explicit path** that is protected from public web access. An explicit `DB_PATH` value is used as-is without randomization. Define it in `wp-config.php`:
+
+    // Use protected DB path that is not exposed by the web server.
+    define( 'DB_PATH', '/private/wordpress/database.sqlite' );
+
+**Caution:** An explicit `DB_PATH` must point to a **protected** location that your web server does not expose. Store the database outside the web root and make sure it's protected.
+
+The value of `DB_PATH` must be an absolute path to the SQLite database file, or `:memory:` for an in-memory SQLite database. The database directory must be writable by PHP. Changing `DB_PATH` selects a different database without moving an existing one.
+
 = What does the plugin require? =
 
 In addition to the WordPress and PHP versions listed above, the plugin requires the PDO SQLite PHP extension and SQLite 3.37.0 or newer. The setup screen also needs write access to the `wp-content` directory and will detect conflicting database drop-ins.