Skip to content
ZajLibrary
prod e051e98
Browse

2 · Local database

TL;DR

Section titled “TL;DR”

Objective — give the installer an empty database to migrate into: start the local MySQL/MariaDB service, create an empty utf8mb4 schema, and point .env at it with every secret double-quoted, then prove Laravel actually connects.

Background

Section titled “Background”

The installer needs an empty database to migrate into. Create it with the charset the app expects, then wire .env and prove Laravel actually connects to it.

Steps

Section titled “Steps”

1. Start the database service

Section titled “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.

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

    Terminal window
    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

Section titled “2. Verify the connection”

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

  1. Connect over TCP and print the engine version.

    Terminal window
    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.

    ErrorFix
    Can't connect through socket '/tmp/mysql.sock'Add -h 127.0.0.1 -P 3306
    Connection refusedStart the DB service from Herd
    Access deniedCheck the root password in Herd’s DB settings
    • ✅ Reconnecting after the fix returns a version.

3. Create the database

Section titled “3. Create the database”

Create the empty schema with the charset the app expects.

  1. Create the utf8mb4 database.

    Terminal window
    mysql -h 127.0.0.1 -u root -e "CREATE DATABASE \`[PROJECT_NAME]_local\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
    # Expected: no output (silent success)
    • ✅ The database exists; no error printed.

utf8mb4 matters — many CodeCanyon apps store emoji and multi-byte content and throw collation errors on a 3-byte utf8 database. No output means success.

4. Point .env at it and prove the connection

Section titled “4. Point .env at it and prove the connection”

Wire .env to the new database, then confirm Laravel sees the right one.

  1. Set the DB_* block in .env.

    DB_CONNECTION=mysql
    DB_HOST=127.0.0.1
    DB_PORT=3306
    DB_DATABASE=[PROJECT_NAME]_local
    DB_USERNAME=root
    DB_PASSWORD=""
    • ✅ .env points at [PROJECT_NAME]_local.

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

    Terminal window
    php artisan config:clear
    php artisan db:show 2>&1 | head -5
    # Expected: connection details for [PROJECT_NAME]_local with 0 tables
    • ✅ 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.

    Terminal window
    mysql -h 127.0.0.1 -u root -e "USE [PROJECT_NAME]_local; SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='[PROJECT_NAME]_local';"
    # Expected: 0 — empty and ready for the installer
    • ✅ The direct query returns 0 tables.

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

Checklist

Section titled “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.
  • 🤖 Empty schema created — with utf8mb4 / utf8mb4_unicode_ci.
  • 🤖 .env wired — DB_* set and every secret double-quoted.
  • 🤖 0 tables confirmed — db:show (or the direct query) shows an empty schema.

Storage, symlinks & SSL