Skip to content

QUICKREF.md

Latest commit

 

History

History
312 lines (219 loc) · 4.38 KB

QUICKREF.md

File metadata and controls

312 lines (219 loc) · 4.38 KB

ExPgflow Quick Reference

A quick reference guide for common ex_pgflow development tasks.

Initial Setup

# Run setup script (choose your method)
./scripts/setup-dev-environment.sh

# Validate environment
make check

# Install dependencies
make deps

# Setup database
make db-create
make db-migrate

# Run tests
make test

Daily Development

# Check environment is ready
make check

# Pull latest changes
git pull

# Update dependencies
make deps

# Run migrations
make db-migrate

# Run tests
make test

# Run tests in watch mode
make test-watch

Quality Checks

# Run all quality checks
make quality

# Individual checks
make format      # Format code
make lint        # Credo linter
make dialyzer    # Type checking
make security    # Security scan

Database Management

# Create database
make db-create

# Run migrations
make db-migrate

# Reset database (drops, creates, migrates)
make db-reset

# Open PostgreSQL shell
make db-shell

Docker Commands

# Start PostgreSQL
make docker-up

# Stop PostgreSQL
make docker-down

# View logs
make docker-logs

# Reset (delete all data)
make docker-reset

Common Tasks

Running Tests

# All tests
make test

# Specific file
mix test test/pgflow/executor_test.exs

# Specific test
mix test test/pgflow/executor_test.exs:42

# With coverage
make test-coverage

# Watch mode (auto-rerun on changes)
make test-watch

Code Formatting

# Check formatting
mix format --check-formatted

# Format all files
make format

Type Checking

# Run Dialyzer
make dialyzer

# Clean and rebuild PLTs (if needed)
rm -rf priv/plts
make dialyzer

Documentation

# Generate docs
make docs

# Generate and open in browser
make docs-open

Troubleshooting

Environment Issues

# Validate environment
make check

# Re-run setup
./scripts/setup-dev-environment.sh

Database Issues

# Check PostgreSQL is running
pg_isready -h localhost

# Start PostgreSQL (Docker)
make docker-up

# Reset database
make db-reset

Dependency Issues

# Clean and reinstall
make clean-all
make deps
make compile

Test Failures

# Reset test database
MIX_ENV=test mix ecto.reset

# Run with detailed output
mix test --trace

# Run specific failing test
mix test path/to/test.exs:line_number

Environment Variables

# Database URL
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/ex_pgflow"

# Test database
export TEST_DATABASE_URL="postgresql://postgres:postgres@localhost:5432/ex_pgflow_test"

# Mix environment
export MIX_ENV=dev  # or test, prod

Git Workflow

# Create feature branch
git checkout -b feature/my-feature

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Run quality checks before pushing
make quality
make test

# Push to GitHub
git push origin feature/my-feature

Nix Commands

# Enter Nix shell
nix develop

# Update Nix flake
nix flake update

# Exit Nix shell
exit

Helpful Aliases

Add these to your ~/.bashrc or ~/.zshrc:

# ExPgflow aliases
alias pgf-test='make test'
alias pgf-check='make check'
alias pgf-quality='make quality'
alias pgf-format='make format'
alias pgf-db-reset='make db-reset'

Resources

Getting Help

# View all available make commands
make help

# Check environment
make check

# View script help
./scripts/setup-dev-environment.sh --help
./scripts/check-environment.sh --help

Common Error Solutions

"pgmq extension not found"

# Use Docker with pgmq
make docker-up

# Or use Nix
nix develop

"mix: command not found"

# Install Elixir
./scripts/setup-dev-environment.sh

# Or enter Nix shell
nix develop

"Connection refused" (PostgreSQL)

# Start PostgreSQL
make docker-up

# Or check system PostgreSQL
sudo systemctl start postgresql  # Linux
brew services start postgresql   # macOS

"Database does not exist"

make db-create
make db-migrate

Tip: Keep this file open in a terminal or editor for quick reference during development!