Support DB_PATH as the primary database path constant - #512

Resolve DB_PATH, db-path.php, or a legacy .ht.sqlite database at runtime,
retaining FQDB compatibility for older integration plugin versions. Export
and table listing check that the database exists before opening it. Import
uses the configured location and initializes secret-path storage only when
no location has been recorded.

Report invalid plugin database settings as command errors. Keep storage
initialization out of the plugin loader and cover the storage behavior with
Behat scenarios.

WordPress/sqlite-database-integration#502
WordPress/sqlite-database-integration#512

## Motivation for the change, related issues

The SQLite integration is adopting **`DB_PATH`** as its primary database
path setting. Playground currently supplies only `DB_DIR` and `DB_FILE`
when `dataSqlPath` is set.

## Implementation details

Define `DB_PATH` from `dataSqlPath`, keeping the matching legacy
constants for older SQLite plugin versions.

## Testing Instructions (or ideally a Blueprint)

Boot with `dataSqlPath` set to a custom SQLite file and confirm
WordPress opens that file. Verified with SQLite integration v2.1.16,
bundled trunk, and the build from PR
[#512](WordPress/sqlite-database-integration#512).

Related:
WordPress/sqlite-database-integration#512.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* WordPress boot now uses the provided SQL data path to configure its
database location, improving support for custom database setups.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Use the existing installation-directory copy for SQLite databases. It
already includes the database files and db-path.php, including the
randomized directories introduced for SQLite Database Integration 3.1.

Remove the separate fixed-filename snapshot and its validity and cleanup
logic. Cache reuse now depends on the installation directory existing,
so an incomplete copy within a suite no longer triggers a rebuild based
on the missing snapshot. Each suite still starts with an empty cache.

Add a focused regression test for path preservation and independent
databases across a cold installation and two warm restores.

WordPress/sqlite-database-integration#502
WordPress/sqlite-database-integration#512

Resolve DB_PATH, db-path.php, or a legacy .ht.sqlite database at runtime,
retaining FQDB compatibility for older integration plugin versions. Export
and table listing check that the database exists before opening it. Import
uses the configured location and initializes secret-path storage only when
no location has been recorded.

Report invalid plugin database settings as command errors. Keep storage
initialization out of the plugin loader and cover the storage behavior with
Behat scenarios.

WordPress/sqlite-database-integration#502
WordPress/sqlite-database-integration#512

Resolve DB_PATH, db-path.php, or a legacy .ht.sqlite database at runtime,
retaining FQDB compatibility for older integration plugin versions. Export
and table listing check that the database exists before opening it. Import
uses the configured location and initializes secret-path storage only when
no location has been recorded.

Report invalid plugin database settings as command errors. Keep storage
initialization out of the plugin loader and cover the storage behavior with
Behat scenarios.

WordPress/sqlite-database-integration#502
WordPress/sqlite-database-integration#512

Resolve DB_PATH, db-path.php, or a legacy .ht.sqlite database at runtime,
retaining FQDB compatibility for older integration plugin versions. Export
and table listing check that the database exists before opening it. Import
uses the configured location and initializes secret-path storage only when
no location has been recorded.

Report invalid plugin database settings as command errors. Keep storage
initialization out of the plugin loader and cover the storage behavior with
Behat scenarios.

WordPress/sqlite-database-integration#502
WordPress/sqlite-database-integration#512

Resolve DB_PATH, db-path.php, or a legacy .ht.sqlite database at runtime,
retaining FQDB compatibility for older integration plugin versions. Export
and table listing check that the database exists before opening it. Import
uses the configured location and initializes secret-path storage only when
no location has been recorded.

Report invalid plugin database settings as command errors. Keep storage
initialization out of the plugin loader and cover the storage behavior with
Behat scenarios.

WordPress/sqlite-database-integration#502
WordPress/sqlite-database-integration#512

Resolve DB_PATH, db-path.php, or a legacy .ht.sqlite database at runtime,
retaining FQDB compatibility for older integration plugin versions. Export
and table listing check that the database exists before opening it. Import
uses the configured location and initializes secret-path storage only when
no location has been recorded.

Report invalid plugin database settings as command errors. Keep storage
initialization out of the plugin loader and cover the storage behavior with
Behat scenarios.

WordPress/sqlite-database-integration#502
WordPress/sqlite-database-integration#512

## Why

Adminer hardcodes `/wordpress/wp-content/database/.ht.sqlite`, so it can
open the wrong database when WordPress uses randomized storage or an
explicit `DB_PATH`.

## What changes

Use **Playground's runtime database metadata** for automatic login and
database selection in both Core and Gutenberg sites. Playground records
the path after WordPress initializes, preferring `DB_PATH` over legacy
`FQDB`. Update the database guide accordingly.

## How to test this

**Platforms:** macOS or Windows, using the current head. Local
validation ran on Apple Silicon macOS.

**Starting state:** An initialized Core or Gutenberg site using legacy
fixed storage, randomized storage, or an explicit `DB_PATH`. The latter
two require a SQLite integration build with the new storage support; set
`DB_PATH` before WordPress first loads.

1. Click **Start dev server**, then **wp-admin**. Create a draft post
with a distinctive title.
2. Click **DB inspect (Adminer)**. It should open without credentials
and list the site's WordPress tables.
3. Find the draft in `wp_posts`. Adminer's database path should match
the site's configured or generated SQLite path.
4. Repeat for the other launch mode and storage layouts.

**What must not have happened:** Adminer must not select or create a
second database at the old fixed path.

## Risks and limitations

No new automated regression test is included; validation relies on the
live checks below and Playground's existing metadata contract. Windows
was not run locally. The interface is unchanged.

<details>
<summary>Validation details</summary>

Tested WordPress 7.0.1 and bundled Adminer on Electron 43.6.0 in both
Core document-root and Gutenberg plugin-mount modes. The latter used a
small activation-probe plugin.

Storage cases covered the bundled SQLite plugin, released SQLite
integration 3.0.2, and revision
`4163f69f3d543ec7d6085bbb0c4e0c36b36c0156` with randomized storage and
explicit `DB_PATH`. The explicit path contained spaces and an apostrophe
and overrode a conflicting `FQDB`. In every case, Adminer selected
WordPress's active database and read an option written by WordPress.

An app-level check clicked **Start dev server**, launched the real
server child, and read the saved option through Adminer. Existing Node
and Electron suites, lint, and the documentation build passed.

</details>

<details>
<summary>Review outcome</summary>

0 [fix here] · 0 [follow-up]. Local review completed across all five
dimensions for the final two-file diff: head
`fbcab67c9025f01e08fe54bc678592cfd19c0801`, base
`9ee21dd4058bfb879807c54b4373d1c6e5237ce5`. No findings. The test
omission is intentional; existing suites and lint passed on the reviewed
commit.

</details>

## Related

Playground references: [Adminer
integration](https://github.com/WordPress/wordpress-playground/blob/1f92c10bd871c224baf44300d730fd22a9f83715/packages/playground/website/src/components/site-manager/site-database-panel/adminer-extensions/adminer-mysql-on-sqlite-driver.php)
and [metadata
writer](https://github.com/WordPress/wordpress-playground/blob/1f92c10bd871c224baf44300d730fd22a9f83715/packages/playground/wordpress/src/platform-mu-plugins.ts).

- Randomized storage: [SQLite integration
#502](WordPress/sqlite-database-integration#502).
- Primary `DB_PATH` support: [SQLite integration
#512](WordPress/sqlite-database-integration#512).
- Part of the compatibility tracking issue: [SQLite integration
#513](WordPress/sqlite-database-integration#513).

Co-authored-by: Francesco Bigiarini <[email protected]>

Document **randomized database storage and `DB_PATH` configuration** in
the plugin FAQ and a new plugin README, including protection from public
web access.

The new README also covers usage, requirements, and development. Link it
from the root README and exclude it from plugin release ZIPs.

Related to #502 and #512.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added setup, configuration, security, development, and licensing
guidance for the SQLite integration plugin.
* Expanded the FAQ with details on default and custom database paths,
changing database locations, and temporary in-memory databases.
* Clarified storage requirements and recommended keeping database files
in a protected location outside the web root.
  * Updated the component list to link directly to the plugin package.
* **Chores**
  * Excluded the package README from the plugin release archive.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

## Release `3.1.0`

Prepares the version numbers and release notes for `3.1.0`.

**Changelog draft:**

---

**SQLite Database Integration 3.1 is here! 🎉**

This release improves **database storage and configuration** and fixes
several MySQL compatibility issues.

## What's new

Version 3.1 improves how WordPress sites store, locate, and protect
their SQLite databases. It also fixes SQL behavior and export
compatibility:

- **Randomized database paths:** The default database location is now a
randomized directory under `wp-content/database/`, recorded in
`wp-content/database/db-path.php`.
([#502](#502))
- **`DB_PATH`:** Configure the database with one full-path constant,
also available at runtime for integrations.
([#512](#512))
- **SQL compatibility:** Fix `IF()` condition evaluation and make
`TRADITIONAL` enable its component SQL modes.
([#518](#518),
[#509](#509))
- **WordPress table collations:** Default to `utf8mb4_unicode_520_ci`
for new tables created with WordPress's charset settings, improving
exports to MariaDB. Existing tables keep their recorded collation.
([#514](#514))
- **Documentation:** A new plugin README and expanded FAQ explain
database storage and secure configuration.
([#520](#520))

For more information about database paths and secure configuration, read
the [database storage
guide](https://github.com/WordPress/sqlite-database-integration/blob/trunk/packages/plugin-sqlite-database-integration/README.md#database-storage).

## Upgrading to 3.1

Upgrading an existing SQLite site is straightforward:

1. **Back up** your SQLite database.
2. **Update the plugin** to version 3.1.

Existing `.ht.sqlite` and `.ht.sqlite.php` databases move to the
randomized layout automatically unless a database file path is
explicitly configured.

To properly **secure the database**, set `DB_PATH` in `wp-config.php` to
an absolute file path outside the web root that your web server does not
expose. Its directory must be writable by PHP. Changing `DB_PATH` does
not move an existing database.

## Breaking changes

Review these changes if you use custom database settings or
integrations:

- **Database paths:** Default database files now move to randomized
paths under `wp-content/database/`. Explicitly configured file paths
stay unchanged. Integrations, including backup and migration tools, must
read `DB_PATH` after WordPress loads instead of assuming a fixed
filename.
- **Legacy constants:** `DB_DIR` and `DB_FILE` are now deprecated. They
and the previously deprecated `FQDB` and `FQDBDIR` remain supported, but
`DB_PATH` takes precedence. Conflicting values trigger warnings.
- **Absolute paths:** Relative database file and directory paths are now
rejected. `:memory:` remains available for in-memory databases.

## Thank you

Thank you to everyone who contributed, tested, and helped update
integrations.

**Changes since 3.0.2:**
[`v3.0.2...v3.1.0`](v3.0.2...v3.1.0)

---

**PR comparison:**
[`v3.0.2...release/v3.1.0`](v3.0.2...release/v3.1.0)

## Next steps

1. **Review** the release changes and changelog draft.
2. **Merge** this pull request to complete the release.

Merging will automatically build the plugin ZIP, create a [GitHub
release](https://github.com/WordPress/sqlite-database-integration/releases),
and deploy to
[WordPress.org](https://wordpress.org/plugins/sqlite-database-integration/).