2 · Local database

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 2 · Local database
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/02-database/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 3
- part_number: 2 (legacy stepNumber frontmatter)
- legacy_step_number: 2
- est_time: ~10 min
- description: Confirm the Phase 2 local MySQL/MariaDB database is running, utf8mb4, and wired through .env so the installer can connect.
- tags: codecanyon, laravel, database, mysql

## Execution rules (binding)
- This is Part 2 of phase 3 (~10 min) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 2 · Local database

## TL;DR

**Objective** — confirm the local DB provisioned in Phase 2 is running, uses `utf8mb4`, and is the database `.env` points Laravel at. Create it only if it is missing (for a local-only workflow or a skipped Phase 2), then prove the installer can connect.

**Steps at a glance:**
1. **Start the database service** — In Herd → Services → Database, start `Local_MySQL` or `Local_MariaDB` (wait
   for the green dot).
2. **Verify the connection** — Herd Pro requires a TCP connection (`-h 127.0.0.1`), not a socket.
3. **Confirm or create the database** — Phase 2 Step 1 should already have created it; this step verifies charset/collation and creates only if missing.
4. **Confirm `.env` points at it and prove the connection** — Phase 2 Step 5 activated local `.env`; this step confirms Laravel resolves the right DB and table count.

:::note[User part + done-when]
**👤 User part** — start the database service in the Herd app when it is not already running. That GUI toggle is a local-machine service action; everything after that is terminal-runnable and agent-verifiable.

**Done when** the DB service is running, `mysql -h 127.0.0.1` connects without a socket error, the Phase 2 local DB exists (or was created only because it was missing), charset/collation are `utf8mb4` / `utf8mb4_unicode_ci`, `.env` `DB_*` resolves to that DB with double-quoted secrets, and table count is interpreted correctly for fresh vs resumed state. &nbsp;·&nbsp; **⏱ ~10 min** &nbsp;·&nbsp; 🔀 mixed (👤 start service, 🤖 verify + create only if missing).
:::

## Background

The installer needs a reachable local database before page 4 runs. Phase 2 owns the provisioning and `.env` template activation; this page is the local readiness checkpoint that catches a stopped DB service, wrong charset, stale config cache, or `.env` pointing at the wrong schema.

Use `Zaj-PROJECT.md` as the non-secret source for the local DB row: DB engine/version, host/port, database name, username, charset/collation, and last verified date. Do not put passwords there; keep secret values in the vault.

:::note[Resuming an already-set-up project?]
If a prior session already completed the installer, this DB may already contain tables. Verify that state with evidence and record it as `VERIFIED-STATE`; do **not** empty, recreate, or rewire a populated DB just to satisfy a fresh-run check. A fresh install expects `0` tables here; a resumed install expects the existing table count.
:::

## Steps

### 1. Start the database service

In **Herd → Services → Database**, start `Local_MySQL` or `Local_MariaDB` (wait for the green dot). Homebrew (`brew services start mysql` / `mariadb`), DBngin, and MAMP all work too.

:::note[Who does this]
🔀 **User + Agent** — if Herd's GUI is the only control surface, the user starts the DB service there. If Homebrew/DBngin/MAMP CLI is available, the agent can start it from the terminal. In both cases, the agent verifies the TCP connection before moving on.
:::

<Steps>

1. **Start the service** and wait for its green dot — or use a terminal alternative.

   ```bash
   brew services start mysql   # or: brew services start mariadb
   # Expected: "Successfully started" (skip if you started it from the Herd GUI)
   ```

   - ✅ The local DB engine is running.

</Steps>

:::note[MySQL vs MariaDB — the classic commands work on both]
Herd Pro ships **MariaDB** by default since late 2024, but the classic `mysql` / `mysqldump` clients talk to both engines over the wire-compatible protocol. The guide uses `mysql -h 127.0.0.1` throughout, which works regardless of which engine you installed. The newer `mariadb` / `mariadb-dump` commands only exist on MariaDB and are optional.
:::

### 2. Verify the connection

Herd Pro requires a **TCP** connection (`-h 127.0.0.1`), not a socket.

<Steps>

1. **Connect over TCP and print the engine version.**

   ```bash
   mysql -h 127.0.0.1 -P 3306 -u root -e "SELECT VERSION();"
   # Expected: a single version string (e.g. 11.x-MariaDB or 8.x)
   ```

   - ✅ A version prints — no socket error.

2. **If it fails**, map the error to its fix.

   | Error | Fix |
   |---|---|
   | `Can't connect through socket '/tmp/mysql.sock'` | Add `-h 127.0.0.1 -P 3306` |
   | `Connection refused` | Start the DB service from Herd |
   | `Access denied` | Check the root password in Herd's DB settings |

   - ✅ Reconnecting after the fix returns a version.

</Steps>

### 3. Confirm or create the database

Phase 2 Step 1 should already have created the local database and user. Run the idempotent create anyway: it is a no-op when the DB exists, and it only creates the schema if Phase 2 was skipped or you are doing a local-only workflow.

<Steps>

1. **Confirm the `utf8mb4` database exists, creating it only if missing.**

   ```bash
   mysql -h 127.0.0.1 -u root -e "CREATE DATABASE IF NOT EXISTS \`[project]_local_db\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
   # Expected: no output (silent success; no-op if Phase 2 already created it)
   ```

   - ✅ The database exists; no error printed. If Phase 2 already created it, this command changed nothing.

2. **Verify the charset and collation.**

   ```bash
   mysql -h 127.0.0.1 -u root -N -e "SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME='[project]_local_db';"
   # Expected: utf8mb4  utf8mb4_unicode_ci
   ```

   - ✅ The local DB is charset-safe for the installer.

</Steps>

Use the exact local DB name from Phase 2 if your project used a different suffix. `utf8mb4` matters — many CodeCanyon apps store emoji and multi-byte content and throw collation errors on a 3-byte `utf8` database.

### 4. Confirm `.env` points at it and prove the connection

Phase 2 Step 5 laid down and activated the local `.env`. Confirm the live file resolves to the provisioned local DB, then prove Laravel can use it.

<Steps>

1. **Confirm the `DB_*` block in `.env`.**

   ```ini
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=[project]_local_db
   DB_USERNAME=[project]_local_user
   DB_PASSWORD=""
   ```

   - ✅ `.env` points at the Phase 2 local DB. `root` with an empty password is the simplest local example, but a dedicated per-env user/password from Phase 2 is valid and preferred.

2. **Clear the stale config cache, then check the connection.**

   ```bash
   php artisan config:clear
   php artisan db:show 2>&1 | head -5
   # Expected: connection details for [project]_local_db; 0 tables for fresh install, or the existing table count when resuming
   ```

   - ✅ `db:show` reports the right database.

3. **If `db:show` looks wrong, confirm with a direct query** — it can report tables from a different project on the same server.

   ```bash
   DB_NAME=$(grep '^DB_DATABASE=' .env | cut -d= -f2 | tr -d '"')
   mysql -h 127.0.0.1 -u root -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='${DB_NAME}';"
   # Expected: 0 tables (fresh install) — OR the existing table count if the installer already ran (resuming)
   ```

   - ✅ The direct query returns the correct table count for this project state.

</Steps>

:::caution[Double-quote every secret in .env]
Unquoted values containing `#`, spaces, or special characters get truncated or misparsed by the dotenv reader. Quote them:

```ini
DB_PASSWORD="p@ss word#1"
```
:::

One more reason to trust the direct query over the artisan helper:

:::caution[`db:show` can lie — confirm with a direct query]
When config is cached or `information_schema` leaks across databases, `php artisan db:show` sometimes reports tables from a *different* project on the same server. If it looks wrong, use the direct `mysql` query in substep 3 to confirm the table count belongs to the intended schema.
:::

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **👤 DB service running** — green dot in Herd, or `brew services`.
- [ ] **🤖 Connects over TCP** — `mysql -h 127.0.0.1` connects without a socket error.
- [ ] **🤖 Local schema confirmed** — exists or was created only if missing, with `utf8mb4` / `utf8mb4_unicode_ci`.
- [ ] **🤖 `.env` verified** — `DB_*` resolves to the Phase 2 local DB and every secret is double-quoted.
- [ ] **🤖 Table count interpreted** — `0` for a fresh install, or an existing table count accepted with evidence when resuming.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the local DB engine/version, host/port, DB name, DB user, charset/collation, and verification date; passwords stay only in the vault.

:::next[Next step]
[Storage, symlinks & SSL](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/03-herd-ssl/)
:::

# 2 · Local database

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/02-database/

## TL;DR

**Objective** — confirm the local DB provisioned in Phase 2 is running, uses `utf8mb4`, and is the database `.env` points Laravel at. Create it only if it is missing (for a local-only workflow or a skipped Phase 2), then prove the installer can connect.

**Steps at a glance:**
1. **Start the database service** — In Herd → Services → Database, start `Local_MySQL` or `Local_MariaDB` (wait
   for the green dot).
2. **Verify the connection** — Herd Pro requires a TCP connection (`-h 127.0.0.1`), not a socket.
3. **Confirm or create the database** — Phase 2 Step 1 should already have created it; this step verifies charset/collation and creates only if missing.
4. **Confirm `.env` points at it and prove the connection** — Phase 2 Step 5 activated local `.env`; this step confirms Laravel resolves the right DB and table count.

:::note[User part + done-when]
**👤 User part** — start the database service in the Herd app when it is not already running. That GUI toggle is a local-machine service action; everything after that is terminal-runnable and agent-verifiable.

**Done when** the DB service is running, `mysql -h 127.0.0.1` connects without a socket error, the Phase 2 local DB exists (or was created only because it was missing), charset/collation are `utf8mb4` / `utf8mb4_unicode_ci`, `.env` `DB_*` resolves to that DB with double-quoted secrets, and table count is interpreted correctly for fresh vs resumed state. &nbsp;·&nbsp; **⏱ ~10 min** &nbsp;·&nbsp; 🔀 mixed (👤 start service, 🤖 verify + create only if missing).
:::

## Background

The installer needs a reachable local database before page 4 runs. Phase 2 owns the provisioning and `.env` template activation; this page is the local readiness checkpoint that catches a stopped DB service, wrong charset, stale config cache, or `.env` pointing at the wrong schema.

Use `Zaj-PROJECT.md` as the non-secret source for the local DB row: DB engine/version, host/port, database name, username, charset/collation, and last verified date. Do not put passwords there; keep secret values in the vault.

:::note[Resuming an already-set-up project?]
If a prior session already completed the installer, this DB may already contain tables. Verify that state with evidence and record it as `VERIFIED-STATE`; do **not** empty, recreate, or rewire a populated DB just to satisfy a fresh-run check. A fresh install expects `0` tables here; a resumed install expects the existing table count.
:::

## Steps

### 1. Start the database service

In **Herd → Services → Database**, start `Local_MySQL` or `Local_MariaDB` (wait for the green dot). Homebrew (`brew services start mysql` / `mariadb`), DBngin, and MAMP all work too.

:::note[Who does this]
🔀 **User + Agent** — if Herd's GUI is the only control surface, the user starts the DB service there. If Homebrew/DBngin/MAMP CLI is available, the agent can start it from the terminal. In both cases, the agent verifies the TCP connection before moving on.
:::

<Steps>

1. **Start the service** and wait for its green dot — or use a terminal alternative.

   ```bash
   brew services start mysql   # or: brew services start mariadb
   # Expected: "Successfully started" (skip if you started it from the Herd GUI)
   ```

   - ✅ The local DB engine is running.

</Steps>

:::note[MySQL vs MariaDB — the classic commands work on both]
Herd Pro ships **MariaDB** by default since late 2024, but the classic `mysql` / `mysqldump` clients talk to both engines over the wire-compatible protocol. The guide uses `mysql -h 127.0.0.1` throughout, which works regardless of which engine you installed. The newer `mariadb` / `mariadb-dump` commands only exist on MariaDB and are optional.
:::

### 2. Verify the connection

Herd Pro requires a **TCP** connection (`-h 127.0.0.1`), not a socket.

<Steps>

1. **Connect over TCP and print the engine version.**

   ```bash
   mysql -h 127.0.0.1 -P 3306 -u root -e "SELECT VERSION();"
   # Expected: a single version string (e.g. 11.x-MariaDB or 8.x)
   ```

   - ✅ A version prints — no socket error.

2. **If it fails**, map the error to its fix.

   | Error | Fix |
   |---|---|
   | `Can't connect through socket '/tmp/mysql.sock'` | Add `-h 127.0.0.1 -P 3306` |
   | `Connection refused` | Start the DB service from Herd |
   | `Access denied` | Check the root password in Herd's DB settings |

   - ✅ Reconnecting after the fix returns a version.

</Steps>

### 3. Confirm or create the database

Phase 2 Step 1 should already have created the local database and user. Run the idempotent create anyway: it is a no-op when the DB exists, and it only creates the schema if Phase 2 was skipped or you are doing a local-only workflow.

<Steps>

1. **Confirm the `utf8mb4` database exists, creating it only if missing.**

   ```bash
   mysql -h 127.0.0.1 -u root -e "CREATE DATABASE IF NOT EXISTS \`[project]_local_db\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
   # Expected: no output (silent success; no-op if Phase 2 already created it)
   ```

   - ✅ The database exists; no error printed. If Phase 2 already created it, this command changed nothing.

2. **Verify the charset and collation.**

   ```bash
   mysql -h 127.0.0.1 -u root -N -e "SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME='[project]_local_db';"
   # Expected: utf8mb4  utf8mb4_unicode_ci
   ```

   - ✅ The local DB is charset-safe for the installer.

</Steps>

Use the exact local DB name from Phase 2 if your project used a different suffix. `utf8mb4` matters — many CodeCanyon apps store emoji and multi-byte content and throw collation errors on a 3-byte `utf8` database.

### 4. Confirm `.env` points at it and prove the connection

Phase 2 Step 5 laid down and activated the local `.env`. Confirm the live file resolves to the provisioned local DB, then prove Laravel can use it.

<Steps>

1. **Confirm the `DB_*` block in `.env`.**

   ```ini
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=[project]_local_db
   DB_USERNAME=[project]_local_user
   DB_PASSWORD=""
   ```

   - ✅ `.env` points at the Phase 2 local DB. `root` with an empty password is the simplest local example, but a dedicated per-env user/password from Phase 2 is valid and preferred.

2. **Clear the stale config cache, then check the connection.**

   ```bash
   php artisan config:clear
   php artisan db:show 2>&1 | head -5
   # Expected: connection details for [project]_local_db; 0 tables for fresh install, or the existing table count when resuming
   ```

   - ✅ `db:show` reports the right database.

3. **If `db:show` looks wrong, confirm with a direct query** — it can report tables from a different project on the same server.

   ```bash
   DB_NAME=$(grep '^DB_DATABASE=' .env | cut -d= -f2 | tr -d '"')
   mysql -h 127.0.0.1 -u root -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='${DB_NAME}';"
   # Expected: 0 tables (fresh install) — OR the existing table count if the installer already ran (resuming)
   ```

   - ✅ The direct query returns the correct table count for this project state.

</Steps>

:::caution[Double-quote every secret in .env]
Unquoted values containing `#`, spaces, or special characters get truncated or misparsed by the dotenv reader. Quote them:

```ini
DB_PASSWORD="p@ss word#1"
```
:::

One more reason to trust the direct query over the artisan helper:

:::caution[`db:show` can lie — confirm with a direct query]
When config is cached or `information_schema` leaks across databases, `php artisan db:show` sometimes reports tables from a *different* project on the same server. If it looks wrong, use the direct `mysql` query in substep 3 to confirm the table count belongs to the intended schema.
:::

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **👤 DB service running** — green dot in Herd, or `brew services`.
- [ ] **🤖 Connects over TCP** — `mysql -h 127.0.0.1` connects without a socket error.
- [ ] **🤖 Local schema confirmed** — exists or was created only if missing, with `utf8mb4` / `utf8mb4_unicode_ci`.
- [ ] **🤖 `.env` verified** — `DB_*` resolves to the Phase 2 local DB and every secret is double-quoted.
- [ ] **🤖 Table count interpreted** — `0` for a fresh install, or an existing table count accepted with evidence when resuming.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the local DB engine/version, host/port, DB name, DB user, charset/collation, and verification date; passwords stay only in the vault.

:::next[Next step]
[Storage, symlinks & SSL](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/03-herd-ssl/)
:::

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.

Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.

EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

TL;DR

Objective — confirm the local DB provisioned in Phase 2 is running, uses utf8mb4, and is the database .env points Laravel at. Create it only if it is missing (for a local-only workflow or a skipped Phase 2), then prove the installer can connect.

Steps at a glance:

Start the database service — In Herd → Services → Database, start Local_MySQL or Local_MariaDB (wait for the green dot).
Verify the connection — Herd Pro requires a TCP connection (-h 127.0.0.1), not a socket.
Confirm or create the database — Phase 2 Step 1 should already have created it; this step verifies charset/collation and creates only if missing.
Confirm .env points at it and prove the connection — Phase 2 Step 5 activated local .env; this step confirms Laravel resolves the right DB and table count.

Background

The installer needs a reachable local database before page 4 runs. Phase 2 owns the provisioning and .env template activation; this page is the local readiness checkpoint that catches a stopped DB service, wrong charset, stale config cache, or .env pointing at the wrong schema.

Use Zaj-PROJECT.md as the non-secret source for the local DB row: DB engine/version, host/port, database name, username, charset/collation, and last verified date. Do not put passwords there; keep secret values in the vault.

Steps

1. Start the database service

In Herd → Services → Database, start Local_MySQL or Local_MariaDB (wait for the green dot). Homebrew (brew services start mysql / mariadb), DBngin, and MAMP all work too.

Start the service and wait for its green dot — or use a terminal alternative.

brew services start mysql   # or: brew services start mariadb
# Expected: "Successfully started" (skip if you started it from the Herd GUI)

✅ The local DB engine is running.

2. Verify the connection

Herd Pro requires a TCP connection (-h 127.0.0.1), not a socket.

Connect over TCP and print the engine version.

mysql -h 127.0.0.1 -P 3306 -u root -e "SELECT VERSION();"
# Expected: a single version string (e.g. 11.x-MariaDB or 8.x)

✅ A version prints — no socket error.

If it fails, map the error to its fix.

Error Fix
Can't connect through socket '/tmp/mysql.sock' Add -h 127.0.0.1 -P 3306
Connection refused Start the DB service from Herd
Access denied Check the root password in Herd’s DB settings
- ✅ Reconnecting after the fix returns a version.

Error	Fix
`Can't connect through socket '/tmp/mysql.sock'`	Add `-h 127.0.0.1 -P 3306`
`Connection refused`	Start the DB service from Herd
`Access denied`	Check the root password in Herd’s DB settings

3. Confirm or create the database

Phase 2 Step 1 should already have created the local database and user. Run the idempotent create anyway: it is a no-op when the DB exists, and it only creates the schema if Phase 2 was skipped or you are doing a local-only workflow.

Confirm the utf8mb4 database exists, creating it only if missing.

mysql -h 127.0.0.1 -u root -e "CREATE DATABASE IF NOT EXISTS \`[project]_local_db\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
# Expected: no output (silent success; no-op if Phase 2 already created it)

✅ The database exists; no error printed. If Phase 2 already created it, this command changed nothing.

Verify the charset and collation.

mysql -h 127.0.0.1 -u root -N -e "SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME='[project]_local_db';"
# Expected: utf8mb4  utf8mb4_unicode_ci

✅ The local DB is charset-safe for the installer.

Use the exact local DB name from Phase 2 if your project used a different suffix. utf8mb4 matters — many CodeCanyon apps store emoji and multi-byte content and throw collation errors on a 3-byte utf8 database.

4. Confirm `.env` points at it and prove the connection

Phase 2 Step 5 laid down and activated the local .env. Confirm the live file resolves to the provisioned local DB, then prove Laravel can use it.

Confirm the DB_* block in .env.
```
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=[project]_local_db
DB_USERNAME=[project]_local_user
DB_PASSWORD=""
```
- ✅ .env points at the Phase 2 local DB. root with an empty password is the simplest local example, but a dedicated per-env user/password from Phase 2 is valid and preferred.

Clear the stale config cache, then check the connection.

php artisan config:clear
php artisan db:show 2>&1 | head -5
# Expected: connection details for [project]_local_db; 0 tables for fresh install, or the existing table count when resuming

✅ db:show reports the right database.

If db:show looks wrong, confirm with a direct query — it can report tables from a different project on the same server.

DB_NAME=$(grep '^DB_DATABASE=' .env | cut -d= -f2 | tr -d '"')
mysql -h 127.0.0.1 -u root -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='${DB_NAME}';"
# Expected: 0 tables (fresh install) — OR the existing table count if the installer already ran (resuming)

✅ The direct query returns the correct table count for this project state.

One more reason to trust the direct query over the artisan helper:

Checklist

Do not mark this step done until every box below is checked.

👤 DB service running — green dot in Herd, or brew services.
🤖 Connects over TCP — mysql -h 127.0.0.1 connects without a socket error.
🤖 Local schema confirmed — exists or was created only if missing, with utf8mb4 / utf8mb4_unicode_ci.
🤖 .env verified — DB_* resolves to the Phase 2 local DB and every secret is double-quoted.
🤖 Table count interpreted — 0 for a fresh install, or an existing table count accepted with evidence when resuming.
🤖 Project state updated — Zaj-PROJECT.md records the local DB engine/version, host/port, DB name, DB user, charset/collation, and verification date; passwords stay only in the vault.

Storage, symlinks & SSL

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 2 · Local database
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/02-database/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 3
- part_number: 2 (legacy stepNumber frontmatter)
- legacy_step_number: 2
- est_time: ~10 min
- description: Confirm the Phase 2 local MySQL/MariaDB database is running, utf8mb4, and wired through .env so the installer can connect.
- tags: codecanyon, laravel, database, mysql

## Execution rules (binding)
- This is Part 2 of phase 3 (~10 min) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 2 · Local database

## TL;DR

**Objective** — confirm the local DB provisioned in Phase 2 is running, uses `utf8mb4`, and is the database `.env` points Laravel at. Create it only if it is missing (for a local-only workflow or a skipped Phase 2), then prove the installer can connect.

**Steps at a glance:**
1. **Start the database service** — In Herd → Services → Database, start `Local_MySQL` or `Local_MariaDB` (wait
   for the green dot).
2. **Verify the connection** — Herd Pro requires a TCP connection (`-h 127.0.0.1`), not a socket.
3. **Confirm or create the database** — Phase 2 Step 1 should already have created it; this step verifies charset/collation and creates only if missing.
4. **Confirm `.env` points at it and prove the connection** — Phase 2 Step 5 activated local `.env`; this step confirms Laravel resolves the right DB and table count.

:::note[User part + done-when]
**👤 User part** — start the database service in the Herd app when it is not already running. That GUI toggle is a local-machine service action; everything after that is terminal-runnable and agent-verifiable.

**Done when** the DB service is running, `mysql -h 127.0.0.1` connects without a socket error, the Phase 2 local DB exists (or was created only because it was missing), charset/collation are `utf8mb4` / `utf8mb4_unicode_ci`, `.env` `DB_*` resolves to that DB with double-quoted secrets, and table count is interpreted correctly for fresh vs resumed state. &nbsp;·&nbsp; **⏱ ~10 min** &nbsp;·&nbsp; 🔀 mixed (👤 start service, 🤖 verify + create only if missing).
:::

## Background

The installer needs a reachable local database before page 4 runs. Phase 2 owns the provisioning and `.env` template activation; this page is the local readiness checkpoint that catches a stopped DB service, wrong charset, stale config cache, or `.env` pointing at the wrong schema.

Use `Zaj-PROJECT.md` as the non-secret source for the local DB row: DB engine/version, host/port, database name, username, charset/collation, and last verified date. Do not put passwords there; keep secret values in the vault.

:::note[Resuming an already-set-up project?]
If a prior session already completed the installer, this DB may already contain tables. Verify that state with evidence and record it as `VERIFIED-STATE`; do **not** empty, recreate, or rewire a populated DB just to satisfy a fresh-run check. A fresh install expects `0` tables here; a resumed install expects the existing table count.
:::

## Steps

### 1. Start the database service

In **Herd → Services → Database**, start `Local_MySQL` or `Local_MariaDB` (wait for the green dot). Homebrew (`brew services start mysql` / `mariadb`), DBngin, and MAMP all work too.

:::note[Who does this]
🔀 **User + Agent** — if Herd's GUI is the only control surface, the user starts the DB service there. If Homebrew/DBngin/MAMP CLI is available, the agent can start it from the terminal. In both cases, the agent verifies the TCP connection before moving on.
:::

<Steps>

1. **Start the service** and wait for its green dot — or use a terminal alternative.

   ```bash
   brew services start mysql   # or: brew services start mariadb
   # Expected: "Successfully started" (skip if you started it from the Herd GUI)
   ```

   - ✅ The local DB engine is running.

</Steps>

:::note[MySQL vs MariaDB — the classic commands work on both]
Herd Pro ships **MariaDB** by default since late 2024, but the classic `mysql` / `mysqldump` clients talk to both engines over the wire-compatible protocol. The guide uses `mysql -h 127.0.0.1` throughout, which works regardless of which engine you installed. The newer `mariadb` / `mariadb-dump` commands only exist on MariaDB and are optional.
:::

### 2. Verify the connection

Herd Pro requires a **TCP** connection (`-h 127.0.0.1`), not a socket.

<Steps>

1. **Connect over TCP and print the engine version.**

   ```bash
   mysql -h 127.0.0.1 -P 3306 -u root -e "SELECT VERSION();"
   # Expected: a single version string (e.g. 11.x-MariaDB or 8.x)
   ```

   - ✅ A version prints — no socket error.

2. **If it fails**, map the error to its fix.

   | Error | Fix |
   |---|---|
   | `Can't connect through socket '/tmp/mysql.sock'` | Add `-h 127.0.0.1 -P 3306` |
   | `Connection refused` | Start the DB service from Herd |
   | `Access denied` | Check the root password in Herd's DB settings |

   - ✅ Reconnecting after the fix returns a version.

</Steps>

### 3. Confirm or create the database

Phase 2 Step 1 should already have created the local database and user. Run the idempotent create anyway: it is a no-op when the DB exists, and it only creates the schema if Phase 2 was skipped or you are doing a local-only workflow.

<Steps>

1. **Confirm the `utf8mb4` database exists, creating it only if missing.**

   ```bash
   mysql -h 127.0.0.1 -u root -e "CREATE DATABASE IF NOT EXISTS \`[project]_local_db\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
   # Expected: no output (silent success; no-op if Phase 2 already created it)
   ```

   - ✅ The database exists; no error printed. If Phase 2 already created it, this command changed nothing.

2. **Verify the charset and collation.**

   ```bash
   mysql -h 127.0.0.1 -u root -N -e "SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME='[project]_local_db';"
   # Expected: utf8mb4  utf8mb4_unicode_ci
   ```

   - ✅ The local DB is charset-safe for the installer.

</Steps>

Use the exact local DB name from Phase 2 if your project used a different suffix. `utf8mb4` matters — many CodeCanyon apps store emoji and multi-byte content and throw collation errors on a 3-byte `utf8` database.

### 4. Confirm `.env` points at it and prove the connection

Phase 2 Step 5 laid down and activated the local `.env`. Confirm the live file resolves to the provisioned local DB, then prove Laravel can use it.

<Steps>

1. **Confirm the `DB_*` block in `.env`.**

   ```ini
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=[project]_local_db
   DB_USERNAME=[project]_local_user
   DB_PASSWORD=""
   ```

   - ✅ `.env` points at the Phase 2 local DB. `root` with an empty password is the simplest local example, but a dedicated per-env user/password from Phase 2 is valid and preferred.

2. **Clear the stale config cache, then check the connection.**

   ```bash
   php artisan config:clear
   php artisan db:show 2>&1 | head -5
   # Expected: connection details for [project]_local_db; 0 tables for fresh install, or the existing table count when resuming
   ```

   - ✅ `db:show` reports the right database.

3. **If `db:show` looks wrong, confirm with a direct query** — it can report tables from a different project on the same server.

   ```bash
   DB_NAME=$(grep '^DB_DATABASE=' .env | cut -d= -f2 | tr -d '"')
   mysql -h 127.0.0.1 -u root -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='${DB_NAME}';"
   # Expected: 0 tables (fresh install) — OR the existing table count if the installer already ran (resuming)
   ```

   - ✅ The direct query returns the correct table count for this project state.

</Steps>

:::caution[Double-quote every secret in .env]
Unquoted values containing `#`, spaces, or special characters get truncated or misparsed by the dotenv reader. Quote them:

```ini
DB_PASSWORD="p@ss word#1"
```
:::

One more reason to trust the direct query over the artisan helper:

:::caution[`db:show` can lie — confirm with a direct query]
When config is cached or `information_schema` leaks across databases, `php artisan db:show` sometimes reports tables from a *different* project on the same server. If it looks wrong, use the direct `mysql` query in substep 3 to confirm the table count belongs to the intended schema.
:::

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **👤 DB service running** — green dot in Herd, or `brew services`.
- [ ] **🤖 Connects over TCP** — `mysql -h 127.0.0.1` connects without a socket error.
- [ ] **🤖 Local schema confirmed** — exists or was created only if missing, with `utf8mb4` / `utf8mb4_unicode_ci`.
- [ ] **🤖 `.env` verified** — `DB_*` resolves to the Phase 2 local DB and every secret is double-quoted.
- [ ] **🤖 Table count interpreted** — `0` for a fresh install, or an existing table count accepted with evidence when resuming.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the local DB engine/version, host/port, DB name, DB user, charset/collation, and verification date; passwords stay only in the vault.

:::next[Next step]
[Storage, symlinks & SSL](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/03-herd-ssl/)
:::

# 2 · Local database

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/02-database/

## TL;DR

**Objective** — confirm the local DB provisioned in Phase 2 is running, uses `utf8mb4`, and is the database `.env` points Laravel at. Create it only if it is missing (for a local-only workflow or a skipped Phase 2), then prove the installer can connect.

**Steps at a glance:**
1. **Start the database service** — In Herd → Services → Database, start `Local_MySQL` or `Local_MariaDB` (wait
   for the green dot).
2. **Verify the connection** — Herd Pro requires a TCP connection (`-h 127.0.0.1`), not a socket.
3. **Confirm or create the database** — Phase 2 Step 1 should already have created it; this step verifies charset/collation and creates only if missing.
4. **Confirm `.env` points at it and prove the connection** — Phase 2 Step 5 activated local `.env`; this step confirms Laravel resolves the right DB and table count.

:::note[User part + done-when]
**👤 User part** — start the database service in the Herd app when it is not already running. That GUI toggle is a local-machine service action; everything after that is terminal-runnable and agent-verifiable.

**Done when** the DB service is running, `mysql -h 127.0.0.1` connects without a socket error, the Phase 2 local DB exists (or was created only because it was missing), charset/collation are `utf8mb4` / `utf8mb4_unicode_ci`, `.env` `DB_*` resolves to that DB with double-quoted secrets, and table count is interpreted correctly for fresh vs resumed state. &nbsp;·&nbsp; **⏱ ~10 min** &nbsp;·&nbsp; 🔀 mixed (👤 start service, 🤖 verify + create only if missing).
:::

## Background

The installer needs a reachable local database before page 4 runs. Phase 2 owns the provisioning and `.env` template activation; this page is the local readiness checkpoint that catches a stopped DB service, wrong charset, stale config cache, or `.env` pointing at the wrong schema.

Use `Zaj-PROJECT.md` as the non-secret source for the local DB row: DB engine/version, host/port, database name, username, charset/collation, and last verified date. Do not put passwords there; keep secret values in the vault.

:::note[Resuming an already-set-up project?]
If a prior session already completed the installer, this DB may already contain tables. Verify that state with evidence and record it as `VERIFIED-STATE`; do **not** empty, recreate, or rewire a populated DB just to satisfy a fresh-run check. A fresh install expects `0` tables here; a resumed install expects the existing table count.
:::

## Steps

### 1. Start the database service

In **Herd → Services → Database**, start `Local_MySQL` or `Local_MariaDB` (wait for the green dot). Homebrew (`brew services start mysql` / `mariadb`), DBngin, and MAMP all work too.

:::note[Who does this]
🔀 **User + Agent** — if Herd's GUI is the only control surface, the user starts the DB service there. If Homebrew/DBngin/MAMP CLI is available, the agent can start it from the terminal. In both cases, the agent verifies the TCP connection before moving on.
:::

<Steps>

1. **Start the service** and wait for its green dot — or use a terminal alternative.

   ```bash
   brew services start mysql   # or: brew services start mariadb
   # Expected: "Successfully started" (skip if you started it from the Herd GUI)
   ```

   - ✅ The local DB engine is running.

</Steps>

:::note[MySQL vs MariaDB — the classic commands work on both]
Herd Pro ships **MariaDB** by default since late 2024, but the classic `mysql` / `mysqldump` clients talk to both engines over the wire-compatible protocol. The guide uses `mysql -h 127.0.0.1` throughout, which works regardless of which engine you installed. The newer `mariadb` / `mariadb-dump` commands only exist on MariaDB and are optional.
:::

### 2. Verify the connection

Herd Pro requires a **TCP** connection (`-h 127.0.0.1`), not a socket.

<Steps>

1. **Connect over TCP and print the engine version.**

   ```bash
   mysql -h 127.0.0.1 -P 3306 -u root -e "SELECT VERSION();"
   # Expected: a single version string (e.g. 11.x-MariaDB or 8.x)
   ```

   - ✅ A version prints — no socket error.

2. **If it fails**, map the error to its fix.

   | Error | Fix |
   |---|---|
   | `Can't connect through socket '/tmp/mysql.sock'` | Add `-h 127.0.0.1 -P 3306` |
   | `Connection refused` | Start the DB service from Herd |
   | `Access denied` | Check the root password in Herd's DB settings |

   - ✅ Reconnecting after the fix returns a version.

</Steps>

### 3. Confirm or create the database

Phase 2 Step 1 should already have created the local database and user. Run the idempotent create anyway: it is a no-op when the DB exists, and it only creates the schema if Phase 2 was skipped or you are doing a local-only workflow.

<Steps>

1. **Confirm the `utf8mb4` database exists, creating it only if missing.**

   ```bash
   mysql -h 127.0.0.1 -u root -e "CREATE DATABASE IF NOT EXISTS \`[project]_local_db\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
   # Expected: no output (silent success; no-op if Phase 2 already created it)
   ```

   - ✅ The database exists; no error printed. If Phase 2 already created it, this command changed nothing.

2. **Verify the charset and collation.**

   ```bash
   mysql -h 127.0.0.1 -u root -N -e "SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME='[project]_local_db';"
   # Expected: utf8mb4  utf8mb4_unicode_ci
   ```

   - ✅ The local DB is charset-safe for the installer.

</Steps>

Use the exact local DB name from Phase 2 if your project used a different suffix. `utf8mb4` matters — many CodeCanyon apps store emoji and multi-byte content and throw collation errors on a 3-byte `utf8` database.

### 4. Confirm `.env` points at it and prove the connection

Phase 2 Step 5 laid down and activated the local `.env`. Confirm the live file resolves to the provisioned local DB, then prove Laravel can use it.

<Steps>

1. **Confirm the `DB_*` block in `.env`.**

   ```ini
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=[project]_local_db
   DB_USERNAME=[project]_local_user
   DB_PASSWORD=""
   ```

   - ✅ `.env` points at the Phase 2 local DB. `root` with an empty password is the simplest local example, but a dedicated per-env user/password from Phase 2 is valid and preferred.

2. **Clear the stale config cache, then check the connection.**

   ```bash
   php artisan config:clear
   php artisan db:show 2>&1 | head -5
   # Expected: connection details for [project]_local_db; 0 tables for fresh install, or the existing table count when resuming
   ```

   - ✅ `db:show` reports the right database.

3. **If `db:show` looks wrong, confirm with a direct query** — it can report tables from a different project on the same server.

   ```bash
   DB_NAME=$(grep '^DB_DATABASE=' .env | cut -d= -f2 | tr -d '"')
   mysql -h 127.0.0.1 -u root -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='${DB_NAME}';"
   # Expected: 0 tables (fresh install) — OR the existing table count if the installer already ran (resuming)
   ```

   - ✅ The direct query returns the correct table count for this project state.

</Steps>

:::caution[Double-quote every secret in .env]
Unquoted values containing `#`, spaces, or special characters get truncated or misparsed by the dotenv reader. Quote them:

```ini
DB_PASSWORD="p@ss word#1"
```
:::

One more reason to trust the direct query over the artisan helper:

:::caution[`db:show` can lie — confirm with a direct query]
When config is cached or `information_schema` leaks across databases, `php artisan db:show` sometimes reports tables from a *different* project on the same server. If it looks wrong, use the direct `mysql` query in substep 3 to confirm the table count belongs to the intended schema.
:::

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **👤 DB service running** — green dot in Herd, or `brew services`.
- [ ] **🤖 Connects over TCP** — `mysql -h 127.0.0.1` connects without a socket error.
- [ ] **🤖 Local schema confirmed** — exists or was created only if missing, with `utf8mb4` / `utf8mb4_unicode_ci`.
- [ ] **🤖 `.env` verified** — `DB_*` resolves to the Phase 2 local DB and every secret is double-quoted.
- [ ] **🤖 Table count interpreted** — `0` for a fresh install, or an existing table count accepted with evidence when resuming.
- [ ] **🤖 Project state updated** — `Zaj-PROJECT.md` records the local DB engine/version, host/port, DB name, DB user, charset/collation, and verification date; passwords stay only in the vault.

:::next[Next step]
[Storage, symlinks & SSL](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/03-herd-ssl/)
:::