From b48c1d731640b5818ce1464d62326abe84a8a6d2 Mon Sep 17 00:00:00 2001 From: Hideyuki MORI Date: Thu, 21 May 2026 23:51:02 +0900 Subject: [PATCH] =?UTF-8?q?docs(cli):=20setupDatabase.php=20=E3=82=92=20ca?= =?UTF-8?q?nonical=E3=80=81initSQLite.php=20=E3=82=92=20legacy=20=E3=81=A8?= =?UTF-8?q?=E3=81=97=E3=81=A6=E6=98=8E=E6=96=87=E5=8C=96=E3=81=99=E3=82=8B?= =?UTF-8?q?=20(#294)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit cli/initSQLite.php と cli/setupDatabase.php は SQLite path で重複機能を 持ち、どちらをいつ使うかが docs に明示されていなかった (FT6 F-1)。 - docs/development/cli.md を新規作成: 両 CLI の役割、--env/--yes/--help オプション、idempotency、3 箇所に重複する schema source-of-truth への cross-ref、composer setup ショートカットを一括説明 - docs/deployment/server-install.md の "Confirmed Short Path" と "SQLite Option" を更新: setupDatabase.php を先頭に、initSQLite.php は backwards-compat として後置。SQLite case でも canonical installer を NENE_DB_TYPE=SQLite3 で使うパターンに統一 initSQLite.php を残す方針 (deprecation は別 Issue)。本 PR は docs のみ。 Closes #294. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/deployment/server-install.md | 22 +++++---- docs/development/cli.md | 75 +++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 9 deletions(-) create mode 100644 docs/development/cli.md diff --git a/docs/deployment/server-install.md b/docs/deployment/server-install.md index 1e12409..ed4f975 100644 --- a/docs/deployment/server-install.md +++ b/docs/deployment/server-install.md @@ -30,13 +30,15 @@ Then create the sample database tables. For MySQL, use the general setup command php cli/setupDatabase.php --env=.env --yes ``` -For SQLite3 fallback, initialize the SQLite file explicitly: +For SQLite3 fallback, the same canonical installer works once `NENE_DB_TYPE=SQLite3` is in your `.env`: ```sh -php cli/initSQLite.php +php cli/setupDatabase.php --env=.env --yes ``` -Both commands are safe to run more than once. They create the current sample `users` and `todos` tables when missing and insert the default `admin` sample user only when that user does not already exist. +The legacy `cli/initSQLite.php` script remains available for older deployment scripts (see `docs/development/cli.md`). + +The setup command is idempotent: it creates the current sample `users` and `todos` tables when missing and inserts the default `admin` sample user only when that user does not already exist. ## Requirements @@ -213,23 +215,25 @@ The browser health endpoint returns the same idea through the NeNe JSON envelope When no database environment variables are provided, NeNe can fall back to SQLite-oriented defaults. -When you intentionally use `NENE_DB_TYPE=SQLite3`, initialize the SQLite sample data from the repository root: +For the SQLite case, use the same canonical installer as MySQL with `NENE_DB_TYPE=SQLite3` in your env file: ```sh -php cli/initSQLite.php +php cli/setupDatabase.php --env=.env --yes ``` -This creates the SQLite database file under `data/`, creates the `users` and `todos` tables, and inserts the default `admin` sample user. You can also use the general setup command with an env file that sets `NENE_DB_TYPE=SQLite3`: +This creates the SQLite database file under `data/`, creates the `users` and `todos` tables, and inserts the default `admin` sample user. It is idempotent — re-running it is safe. + +`cli/initSQLite.php` is the older SQLite-only path that predates the general installer. It is kept for backwards compatibility, but new deployment guides should prefer `cli/setupDatabase.php` (see `docs/development/cli.md` for the canonical vs legacy split). If you do use the legacy path: ```sh -php cli/setupDatabase.php --env=.env --yes +php cli/initSQLite.php --yes ``` -The SQLite database file is a generated runtime artifact and is not committed to Git. If the sample login stops matching the expected `admin / admin` credentials, move the old file aside and initialize it again: +The SQLite database file is a generated runtime artifact and is not committed to Git. If the sample login stops matching the expected `admin / admin` credentials, move the old file aside and re-install: ```sh mv data/nene.db data/nene.db.bak -php cli/initSQLite.php +php cli/setupDatabase.php --env=.env --yes ``` SQLite is useful for a very small sample deployment or quick hosting verification. MySQL is recommended once the application stores real service data. diff --git a/docs/development/cli.md b/docs/development/cli.md new file mode 100644 index 0000000..13b212b --- /dev/null +++ b/docs/development/cli.md @@ -0,0 +1,75 @@ +# CLI Tools + +NeNe ships two command-line scripts under `cli/`. This page describes when to use each one. + +## `cli/setupDatabase.php` (canonical) + +```sh +php cli/setupDatabase.php [--env=.env] [--yes] [--help] +``` + +The canonical installer for both **MySQL** and **SQLite** runtimes. Reads `NENE_DB_TYPE` (default `SQLite3` when no env is loaded) to decide which adapter to use, then calls `Nene\Xion\DatabaseInstaller::install()` to create the sample tables (`users`, `todos`) and insert the default `admin` development account. + +Options: + +- `--env=PATH` — load a dotenv-style file before NeNe initializes configuration. Process environment variables take priority over the file. When `PATH` is explicitly passed and does not exist, the script exits with an error rather than silently falling back to the process environment. +- `--yes` — skip the interactive confirmation prompt. Required for CI / non-interactive deployment. +- `--help` — show usage and exit. + +Recommended one-liner for first-run deployment: + +```sh +php cli/setupDatabase.php --env=.env --yes +``` + +Or via the Composer shortcut: + +```sh +composer setup +``` + +The script is **idempotent** — running it again on an installed database is a no-op (CREATE TABLE IF NOT EXISTS + INSERT WHERE NOT EXISTS). It also prints a final health summary (`Health: API=OK DB=OK Schema=OK`) so deployment scripts can grep for the result. + +For `--yes` + bad DB credentials, the script exits non-zero with a clear error (e.g. `Database setup failed: SQLSTATE[HY000] [2002] php_network_getaddresses: getaddrinfo for ... failed`). + +## `cli/initSQLite.php` (legacy) + +```sh +php cli/initSQLite.php [--yes] [--help] +``` + +Older, SQLite-only initializer that predates `setupDatabase.php`. It hard-codes the SQLite adapter and embeds its own copy of the schema, so it does not honor `NENE_DB_TYPE` and is not used by `composer setup`. + +Kept for backwards compatibility with existing deployment scripts. New deployment guides should use `cli/setupDatabase.php` instead, even for the SQLite case: + +```sh +NENE_DB_TYPE=SQLite3 php cli/setupDatabase.php --env=.env --yes +``` + +If you do invoke `cli/initSQLite.php` directly, the `--yes` and `--help` flags work the same way as for `setupDatabase.php`. + +## When to use which + +| Scenario | Use | +| --- | --- | +| Standard deployment (MySQL or SQLite) | `php cli/setupDatabase.php --env=.env --yes` (or `composer setup`) | +| CI / Ansible / Docker provisioning | same as above, `--yes` is essential | +| Existing scripts that already call `cli/initSQLite.php` | keep working; migrate to `setupDatabase.php` at the next maintenance window | +| Fresh contributor running locally | `composer setup` (shortest) | +| Reset and reinstall sample data | `setupDatabase.php` is idempotent; just re-run it. Soft-delete the existing rows first if you want a clean slate, or `docker compose down -v` to drop the MySQL volume entirely. | + +## Schema source-of-truth (three sites) + +Both scripts pull from independent copies of the CREATE TABLE statements: + +- `docker/mysql/init/001_schema.sql` — MySQL container's first-boot init. +- `cli/initSQLite.php` — embedded SQLite DDL (legacy path). +- `class/xion/DatabaseInstaller.php` — embedded MySQL + SQLite DDL (canonical path used by `cli/setupDatabase.php`). + +When you add or alter a table, **edit all three** in the same change. CI does not enforce parity. See `docs/development/docker.md` "Schema Parity Between SQLite and MySQL" for the full rationale and the table-set comparison commands. + +## Related + +- `docs/deployment/server-install.md` — full deployment walkthrough. +- `docs/development/docker.md` — local Docker setup, including `NENE_*` environment variables. +- `composer.json` — `setup`, `test`, `test:http`, `analyze`, `format`, `check` shortcuts.