Prepare for SQLite Database Integration 3.1's randomized database path

[chubes4]

Summary

SQLite Database Integration 3.1 changes where it stores the database by default (WordPress/sqlite-database-integration#502):

• New managed databases live at wp-content/database/.ht.<32-hex>/.ht.sqlite, and wp-content/database/db-path.php returns that path.
• An existing wp-content/database/.ht.sqlite is moved into that location the first time the plugin loads, unless an explicit path is configured.
• Explicit paths will use a new DB_PATH constant (#512, still open). DB_DIR, DB_FILE, FQDB and FQDBDIR become deprecated.

Studio is unaffected today because it pins v3.0.2 (scripts/download-wp-server-files.ts). Studio doesn't define any database path constant, though, so if it moves to 3.1 as things stand, every existing site's database gets moved on its next start. At that point the Studio code below, which opens wp-content/database/.ht.sqlite directly, would read a missing or empty file.

Studio code that hard-codes the path

• phpMyAdmin: apps/cli/lib/native-php/phpmyadmin.ts
• Blueprint runner --db-path: apps/cli/lib/native-php/blueprints.ts
• Collation repair: apps/cli/lib/sqlite-collations.ts
• WAL/journal-mode conversion: apps/cli/lib/sqlite-journal-mode.ts
• Site server (dbSqlite): apps/studio/src/site-server.ts
• SQLite detection: packages/common/lib/sqlite-integration.ts
• Pull runtime start options: apps/cli/lib/pull/runtime-start-options.ts
• Pull/reprint: apps/cli/commands/pull-reprint.ts (and ~L951–964)
• Backup import, target path: apps/cli/lib/import-export/import/importers/importer.ts (and the Playground importer at ~L415)
• Playground archive detection: apps/cli/lib/import-export/import/validators/playground-validator.ts
• AI system prompt (tells the agent where the database is): apps/cli/ai/system-prompt.ts

Suggested fix

Do this as part of the SQLite 3.1 bump, not separately:

1. Define DB_PATH as wp-content/database/.ht.sqlite for Studio sites, once Bump Playground dependencies to version 0.9.37 #512 lands (or use whatever name it ends up with). The plugin then leaves Studio's database where it is, and none of the places above need to change. The SQLite maintainers suggested this as the simplest option for Studio.
2. If Studio would rather adopt the randomized layout, replace the places above with a single helper that resolves the database through db-path.php and falls back to .ht.sqlite.

Option 1 needs a decision on whether the fixed path is acceptable for sites that are copied or deployed as-is. The randomized path is defense in depth against the database being downloadable over the web. Studio sites are local, but Push and exports move them elsewhere.

Related consumers to check before the bump

• Importing a Playground export into Studio: Playground already runs plugin trunk, so its exports have used the new layout since late September. The validator and importer match any wp-content/database/**/.ht.sqlite and move it to the fixed path, so this probably works, but nobody has tested it with a new-layout export.
• Anything that exports a Studio site's .ht.sqlite and loads it into Playground (for example a browser preview): Playground now looks for db-path.php first, so it's worth confirming it still picks up a plain .ht.sqlite that gets added after boot.
• Downstream services that run a pinned Studio CLI and read wp-content/database/.ht.sqlite from its sites: they need to move their pin in step with this change.

Acceptance criteria

• Studio on SQLite 3.1 starts existing and new sites, and every place listed above finds the database.
• A Playground export made with the randomized layout imports into Studio.

---

AI assistance: Claude (Anthropic) via OpenCode/Kimaki found these places and drafted this issue at Chris Huber's direction. Chris reviewed it.