[nicdavidson]

Refs #131

What

• Document choosing and changing the system database #131: adds a "Choosing and Changing the System Database" page under DreamFactory Configuration. It covers the supported engines (SQLite, MySQL/MariaDB, PostgreSQL, SQL Server) with their DB_CONNECTION values, default ports and PHP drivers. It gives .env settings and database/user creation per engine, the apply steps (config:clear, df:setup, optimize:clear, restart), and a rollback. It also gives the steps for moving an existing SQLite install to another engine with a secured package export and import. It recommends SQLite for trials and development only.
• Adds short cross-links to the new page from basic-configuration.md, linux-installation.md and upgrading-migrating-dreamfactory.md. The upgrade page also gets a note that a database dump only restores into the same engine.

Behavior change

Documentation only. DreamFactory behavior does not change. The docs now state that SQLite is for trials and development, and that production installs should use MySQL/MariaDB, PostgreSQL or SQL Server. They also give a documented way to move from SQLite to one of those engines. No existing page, flow or link is removed or rerouted.

Tests

• Docs build (yarn build): OK docs build. 0 failures on the base branch (known-failures.txt), so nothing is newly broken.
• The build only proves the site compiles. onBrokenLinks is set to warn, so a broken link would not fail it. A reviewer checked every new link target and the SQL Server anchor by hand, and they all exist.
• Command names and options (df:env, df:setup, df:import-pkg --password), default ports, optional keys and the list of what a package carries were checked by review against config/database.php and the df-core source (Setup.php, Env.php, ImportPackage.php, Exporter.php, Importer.php, Package.php).
• Not run: the SQLite-to-MySQL/PostgreSQL move was not run on a live instance, and no migration findings file was produced. The "What to check afterwards" section is therefore deliberately conservative: it tells readers to confirm service credentials, user passwords, app API keys, scripts and lookups after the import. It does not claim that any of them carry over intact. A secured export is required.

Scope

• In: docs/getting-started/dreamfactory-configuration/system-database.md (new), plus small edits to basic-configuration.md, linux-installation.md and upgrading-migrating-dreamfactory.md.
• Out: any code change (export/import behavior, df:env), a cross-engine dump tool, a Docker compose rewrite, and fixes for the issues listed below.
• Repos changed: dreamfactorysoftware/df-docs only.
• The edits to existing pages are small and do not overlap the hunks of open PRs Add runtime log level override: system/server_setting, admin UI, docs #138 (basic-configuration.md) and Upgrade guide: restore licensed composer files on commercial installs #127 (upgrading-migrating-dreamfactory.md).
• Review suggestions not applied (left for a follow-up):
  • Add a final step to delete the temporary admin that df:setup creates.
  • Change the SQL Server note from "new install" to "new or freshly created system database", so people moving to SQL Server don't skip it.

Related issues (not fixed here)

• SQL Server system DB: admin UI service create fails with Batch Error (NULL into service_cache_config.cache_enabled) df-core#184 (fix in fix(models): store null cache_enabled as false on service create df-core#192): on a SQL Server system database, creating a service fails because cache_enabled is NULL. This affects the SQL Server recommendation. The page does not mention it.
• UsageAggregator::dateExpression() uses MySQL DATE_FORMAT on SQL Server, /_internal/ai/usage returns 500 df-ai#13, McpUsageAggregator::dateExpression() uses MySQL DATE_FORMAT on SQL Server, /_internal/ai/mcp-usage returns 500 df-mcp-server#88, dreamfactorysoftware/df-ai-guardian#1: MySQL-only DATE_FORMAT in usage and dashboard endpoints breaks them on non-MySQL system databases.

Existing bugs found but not fixed

• docusaurus.config sets onBrokenLinks: "warn", so broken internal links do not fail the docs build.
• On SQL Server, config/database.php has no env key for trust_server_certificate. Self-signed certificates need a manual code edit, which the page documents as a workaround.

---

Factory gate

• Result on the branch: OK docs build
• New failures vs base: none (0 tests already fail on base and are excluded)
• New tests that fail on base and pass here: none

Open review notes (not blocking, from the factory's final review)

• system-database.md:142 (move step 5): the temporary admin created by df:setup stays on the instance after the import. Add a step 8: "Sign in as an imported admin and delete the temporary admin."
• system-database.md:72: the SQL Server note says "on a new install". Moving to SQL Server hits the same three problems on its empty database, so say "on a new or freshly created system database" so readers following the move procedure don't skip it.

[netlify]

✅ Deploy Preview for dreamfactory-docs ready!

Name	Link
🔨 Latest commit	310a3ff
🔍 Latest deploy log	https://app.netlify.com/projects/dreamfactory-docs/deploys/6ae2f7dcf7f20bc50f42e793
😎 Deploy Preview	https://deploy-preview-140--dreamfactory-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.