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.