Dev Scripts

Dev Scripts

The merq-backend/scripts/ directory contains helper scripts for local development. All scripts must be run from the merq-backend/ directory.

Available Scripts

Script	Purpose
scripts/migrate.sh	Run goose SQL migrations
scripts/seed.sh	Run database seeders
scripts/dev.sh	Start the backend server locally
scripts/test_coverage.sh	Run tests and generate coverage report

---

migrate.sh

Wrapper around the cmd/goose binary for running SQL migrations.

./scripts/migrate.sh [--env=FILE] [--dir=DIR] <command> [args]

Options

Flag	Description	Default
--env=FILE	Path to env file	.env
--dir=DIR	Path to migrations directory	./migrations

Commands

Command	Description
up	Run all pending migrations (default)
down	Rollback the last migration
down-to N	Rollback all migrations to version N (use 0 to reset all)
status	Show migration status
redo	Rollback and re-apply last migration
create NAME	Create new blank SQL migration file
version	Show current applied version

Examples

# Run pending migrations with default .env
./scripts/migrate.sh

# Check status
./scripts/migrate.sh status

# Use a different env file
./scripts/migrate.sh --env=.env.development up

# Rollback last migration
./scripts/migrate.sh down

# Create a new migration
./scripts/migrate.sh create add_outlet_category

---

seed.sh

Wrapper for the cmd/seederv2 binary. Seeders are idempotent — safe to run multiple times, already-run seeders are skipped.

./scripts/seed.sh [--env=FILE] [options]

Options

Flag	Description
--env=FILE	Path to env file (default: .env)
--list	List all registered seeders and their status
--run=NAME	Run a specific seeder by name (skipped if already run)
--force=NAME	Force run a specific seeder (even if already run)

Examples

# Run all pending seeders
./scripts/seed.sh

# Use a different env file
./scripts/seed.sh --env=.env.development

# List seeder status
./scripts/seed.sh --list

# Run a specific seeder
./scripts/seed.sh --run=001_workspace

# Force re-run a seeder
./scripts/seed.sh --force=003_permissions

---

dev.sh

Start the backend server for local development. Optionally runs migrations and seeders before starting.

./scripts/dev.sh [--env=FILE] [--watch] [--port=PORT] [--migrate] [--seed]

Options

Flag	Description
--env=FILE	Path to env file (default: .env)
--watch	Enable hot-reload using air (requires: go install github.com/air-verse/air@latest)
--port=PORT	Override SERVER_PORT from env file
--migrate	Run goose migrations before starting server
--seed	Run seeders before starting server

Examples

# Start server with default .env
./scripts/dev.sh

# Use a specific env file
./scripts/dev.sh --env=.env.development

# Hot-reload mode
./scripts/dev.sh --watch

# Full setup: migrate + seed + start
./scripts/dev.sh --migrate --seed

# Development env + watch + custom port
./scripts/dev.sh --env=.env.development --watch --port=9090

---

test_coverage.sh

Run the test suite and print a coverage summary. Exits with code 1 if internal/service coverage is below 80%.

./scripts/test_coverage.sh

No flags — reads the environment from the local Go toolchain. Always runs against internal/service (primary target) and all internal/* packages (excluding config, domain, platform).

Output Example

==========================================
🧪 MERQ BACKEND TEST COVERAGE REPORT
==========================================

📦 Running tests for internal/service package...
📦 Running tests for all internal packages...

==========================================
📊 COVERAGE SUMMARY
==========================================

📁 internal/service:    82.5% ✅ (Target met!)
📁 internal/* overall:  71.3% ✅

==========================================
📋 DETAILED SERVICE COVERAGE TABLE
==========================================
| File:Line                         | Function                  | Coverage | Status |
---------------------------------------------------------------------------------------
...
✅ SUCCESS: Service coverage is 82.5% (target: 80%)

---

Switching Env Files

All scripts support --env=FILE to point to any env file in the merq-backend/ directory:

# Local default database
./scripts/dev.sh --env=.env

# Remote development database
./scripts/dev.sh --env=.env.development

# Test database
./scripts/migrate.sh --env=.env.test status

The ENV_FILE variable is also read by the Go binaries directly, so you can also set it manually:

ENV_FILE=.env.development go run cmd/goose/main.go -dir migrations status

Related Documentation

• Database Migrations — goose migration system in detail
• Local Setup — full local development setup guide
• Environment Variables — all available env vars