### Install dbdump from Source

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Clone the repository and use the 'just' command to install dbdump. This method requires Go 1.24+ and 'just' to be installed.

```bash
git clone https://github.com/helgesverre/dbdump.git
cd dbdump
just install
```

--------------------------------

### Running Initial Benchmark Session

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Example command to run a benchmark test on the 'testdb' database for 5 iterations and record the median throughput.

```bash
# 1. Create baseline before optimization
just bench testdb 5
# Note median: 115.23 MB/s

# 2. Make optimization (increase buffer size)

```

--------------------------------

### Run Integration Tests Manually

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Provides a step-by-step guide to running integration tests manually, including starting Docker databases, generating test data, executing the integration test script, and cleaning up afterwards.

```bash
# 1. Start databases
just test-docker-up

# 2. Generate test data
just test-data-small

# 3. Run integration tests
./test/integration-test.sh

# 4. Cleanup
just test-docker-down
```

--------------------------------

### Install dbdump using Go

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Install the dbdump command-line tool using Go version 1.24 or later. Ensure your Go environment is set up correctly.

```bash
go install github.com/helgesverre/dbdump/cmd/dbdump@latest
```

--------------------------------

### Integration Test Output Example

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Example output from the dbdump integration test suite, showing build, Docker Compose startup, and test results.

```text
========================================
dbdump Integration Test Suite
========================================

[INFO] Building dbdump...
[INFO] Starting Docker Compose...
[INFO] Waiting for mysql80 to be ready on port 3308...
[INFO] mysql80 is ready!

Testing against: mysql80 (port 3308)
----------------------------------------
[INFO] Testing security features on mysql80...
  Testing: Password not in process list... ✓
  Testing: Dump file permissions 0600... ✓
  Testing: Special characters in password... ✓

========================================
Test Results
========================================
Tests Run:    56
Tests Passed: 56
Tests Failed: 0
========================================

[INFO] All tests passed! ✓
```

--------------------------------

### Install MySQL Client Tools

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Provides commands to install the MySQL client tools on different operating systems (macOS, Ubuntu/Debian, CentOS/RHEL). This is a prerequisite for database connection troubleshooting.

```bash
# macOS
brew install mysql-client

# Ubuntu/Debian
sudo apt-get install mysql-client

# CentOS/RHEL
sudo yum install mysql
```

--------------------------------

### GitHub Actions Workflow for Integration Tests

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Example GitHub Actions workflow to checkout code, set up Go, build dbdump, start test databases, generate data, run integration tests, and clean up.

```yaml
name: Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.24'
      
      - name: Build
        run: go build -o bin/dbdump ./cmd/dbdump
      
      - name: Start test databases
        run: docker compose up -d

      - name: Wait for databases
        run: sleep 30

      - name: Generate test data
        run: ./test/generate-sample-data.sh small 127.0.0.1 3308 testdb

      - name: Run integration tests
        run: ./test/integration-test.sh

      - name: Cleanup
        if: always()
        run: docker compose down -v
```

--------------------------------

### Start Docker Compose Environment

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Manage the Docker Compose environment for test databases. Use `up -d` to start, `logs -f` to view, and `down` to stop. Add `-v` to `down` to remove volumes for a clean slate.

```bash
# Start all databases
docker compose up -d

# Start specific database
docker compose up -d mysql80

# View logs
docker compose logs -f mysql80

# Stop all
docker compose down

# Stop and remove volumes (clean slate)
docker compose down -v
```

--------------------------------

### Download and Install dbdump for Linux (ARM64)

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Download the pre-built binary for Linux on ARM64 architecture. Extract the archive, make the executable, and move it to your system's PATH.

```bash
curl -LO https://github.com/helgesverre/dbdump/releases/download/vX.Y.Z/dbdump-vX.Y.Z-linux-arm64.tar.gz
tar -xzf dbdump-vX.Y.Z-linux-arm64.tar.gz
chmod +x dbdump-vX.Y.Z-linux-arm64
sudo mv dbdump-vX.Y.Z-linux-arm64 /usr/local/bin/dbdump
```

--------------------------------

### SSH Tunneling example with private key

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Demonstrates setting up an SSH tunnel for database dumps using a specific private key. The --auto flag enables smart defaults for the dump process.

```bash
dbdump dump -H 127.0.0.1 -P 3306 -u root -d mydb \
  --ssh-host bastion.example.com \
  --ssh-user deploy \
  --ssh-key ~/.ssh/id_ed25519 \
  --auto
```

--------------------------------

### Download and Install dbdump for Linux (AMD64)

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Download the pre-built binary for Linux on AMD64 architecture. Extract the archive, make the executable, and move it to your system's PATH.

```bash
curl -LO https://github.com/helgesverre/dbdump/releases/download/vX.Y.Z/dbdump-vX.Y.Z-linux-amd64.tar.gz
tar -xzf dbdump-vX.Y.Z-linux-amd64.tar.gz
chmod +x dbdump-vX.Y.Z-linux-amd64
sudo mv dbdump-vX.Y.Z-linux-amd64 /usr/local/bin/dbdump
```

--------------------------------

### Install mysqldump (Windows)

Source: https://github.com/helgesverre/dbdump/blob/main/website/index.html

Install the MySQL client tools, including mysqldump, on Windows using the winget package manager.

```powershell
winget install Oracle.MySQL
```

--------------------------------

### Run Full Test Suite

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Executes all tests, including building the binary, starting Docker, generating data, and running all test suites. This is the recommended command for complete verification.

```bash
just test-all
```

--------------------------------

### Run Integration Tests

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Execute the integration tests, which build the binary and start Docker Compose locally.

```bash
# Run the integration tests (builds the binary and starts Docker Compose locally)
./test/integration-test.sh
```

--------------------------------

### Global User Config Example

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Define a global configuration file to specify tables to exclude across all projects.

```yaml
name: "My Global Config"
exclude:
  exact:
    - activity_logs
    - user_sessions
    - notifications
  patterns:
    - "temp_*"
    - "*_backup"
    - "old_*"
```

--------------------------------

### Download and Install dbdump for macOS (Intel)

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Download the pre-built binary for macOS with Intel processors. Extract the archive, make the executable, and move it to your system's PATH.

```bash
curl -LO https://github.com/helgesverre/dbdump/releases/download/vX.Y.Z/dbdump-vX.Y.Z-darwin-amd64.tar.gz
tar -xzf dbdump-vX.Y.Z-darwin-amd64.tar.gz
chmod +x dbdump-vX.Y.Z-darwin-amd64
sudo mv dbdump-vX.Y.Z-darwin-amd64 /usr/local/bin/dbdump
```

--------------------------------

### Install mysqldump (Ubuntu/Debian)

Source: https://github.com/helgesverre/dbdump/blob/main/website/index.html

Install the mysql-client package, which includes mysqldump, on Ubuntu or Debian-based Linux distributions using apt-get.

```bash
sudo apt-get install mysql-client
```

--------------------------------

### Verify mysqldump Installation

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Ensure that the underlying 'mysqldump' utility is installed and available.

```bash
mysqldump --version
```

--------------------------------

### Project configuration file example

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Specifies project-specific exclusion rules for database dumps in a YAML file. These settings take precedence over global configurations but can be overridden by CLI flags.

```yaml
name: "My Project"

exclude:
  exact:
    - audits
    - activity_logs
    - custom_noisy_table
  patterns:
    - "temp_*"
    - "*_cache"
    - "old_*"
```

--------------------------------

### Download and Install dbdump for macOS (Apple Silicon)

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Download the pre-built binary for macOS with Apple Silicon. Extract the archive, make the executable, and move it to your system's PATH.

```bash
curl -LO https://github.com/helgesverre/dbdump/releases/download/vX.Y.Z/dbdump-vX.Y.Z-darwin-arm64.tar.gz
tar -xzf dbdump-vX.Y.Z-darwin-arm64.tar.gz
chmod +x dbdump-vX.Y.Z-darwin-arm64
sudo mv dbdump-vX.Y.Z-darwin-arm64 /usr/local/bin/dbdump
```

--------------------------------

### Dumping Production Data for Local Development

Source: https://github.com/helgesverre/dbdump/blob/main/website/index.html

This example demonstrates how to dump production data for use in a local development environment, utilizing environment variables for sensitive information like passwords.

```bash
export DBDUMP_MYSQL_PWD=secret
dbdump dump -H db.example.com -u readonly -d myapp_prod --auto -o dev-db.sql
```

--------------------------------

### Verify dbdump Installation

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Check if the dbdump command is installed and accessible by running the help command.

```bash
dbdump --help
```

--------------------------------

### Install mysqldump (macOS)

Source: https://github.com/helgesverre/dbdump/blob/main/website/index.html

Install the mysql-client package, which includes mysqldump, on macOS using the Homebrew package manager.

```bash
brew install mysql-client
```

--------------------------------

### dbdump list command - Output Format

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Example output format for the 'dbdump list' command, showing table names, sizes, and row counts.

```text
Tables in database 'mydb':

Table Name                               Size         Rows
----------------------------------------------------------------------
users                                   15.2 MB       12500
orders                                 125.3 MB       85000
products                                 8.1 MB        2500
sessions                               450.0 MB      150000
telescope_entries                      1.2 GB        500000

Total: 5 tables
```

--------------------------------

### Manual Security Test Steps

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Manually test security features by starting a database, generating data, running dbdump with environment variables, and verifying process list and file permissions.

```bash
# Start database
docker-compose up -d mysql80

# Generate test data
./test/generate-sample-data.sh small 127.0.0.1 3308 testdb

# Test with environment variable
export DBDUMP_MYSQL_PWD=testpass123
./bin/dbdump dump -H 127.0.0.1 -P 3308 -u root -d testdb --auto

# Verify password not in process list
ps aux | grep dbdump  # Should NOT show password

# Verify file permissions
ls -la testdb_*.sql  # Should show -rw------- (600)
```

--------------------------------

### Download and Install dbdump Binary (Windows)

Source: https://github.com/helgesverre/dbdump/blob/main/website/index.html

Download and extract the dbdump binary for Windows. The script then adds the extracted directory to the user's PATH environment variable.

```powershell
# Download and extract
Invoke-WebRequest -Uri https://github.com/helgesverre/dbdump/releases/download/vX.Y.Z/dbdump-vX.Y.Z-windows-amd64.zip -OutFile dbdump.zip
Expand-Archive dbdump.zip -DestinationPath $HOME\dbdump -Force

# Add to PATH (run once)
$env:PATH += ";$HOME\dbdump"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$HOME\dbdump", "User")
```

--------------------------------

### Install mysqldump (CentOS/RHEL)

Source: https://github.com/helgesverre/dbdump/blob/main/website/index.html

Install the mysql package, which includes mysqldump, on CentOS or RHEL-based Linux distributions using yum.

```bash
sudo yum install mysql
```

--------------------------------

### Automated Regression Testing in CI

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Example YAML configuration for adding automated regression testing to a CI pipeline.

```yaml

```

--------------------------------

### Remote Dump Over SSH with Gzip Compression

Source: https://github.com/helgesverre/dbdump/blob/main/website/index.html

This example combines SSH tunneling with gzip compression for securely backing up a remote database and storing the compressed output.

```bash
dbdump dump -H mysql80 -P 3306 -u root -d mydb \
  --ssh-host bastion.example.com \
  --ssh-user deploy \
  --ssh-key ~/.ssh/id_ed25519 \
  --compress gzip \
  --auto
```

--------------------------------

### Integration Test Execution

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Commands to run the full integration test suite, which starts Docker Compose locally, and to clean up afterwards.

```bash
# Run the full integration test suite (starts Docker Compose locally)
./test/integration-test.sh

# Cleanup
docker compose down -v
```

--------------------------------

### Troubleshooting: Clean Docker Environment

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

This command cleans up the Docker environment, removing containers and networks, which is often a necessary step before running tests or starting fresh.

```bash
# Clean Docker
just test-docker-clean
```

--------------------------------

### Pre-Release Checklist: Build All Platforms

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Compile the application for all target platforms as part of the pre-release process to ensure cross-platform compatibility.

```bash
# 3. Build all platforms
just build-all
```

--------------------------------

### Creating a Test Database with Realistic Data

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

This script creates a MySQL database named 'benchmark_small' and populates a 'users' table with 100,000 records for performance testing.

```bash
# Create test database with realistic data
mysql -u root << EOF
CREATE DATABASE IF NOT EXISTS benchmark_small;
USE benchmark_small;

CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(255),
    email VARCHAR(255),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

# Insert test data
INSERT INTO users (name, email)
SELECT
    CONCAT('User ', n),
    CONCAT('user', n, '@example.com')
FROM (
    SELECT a.N + b.N * 10 + c.N * 100 + d.N * 1000 AS n
    FROM
        (SELECT 0 AS N UNION SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 4 UNION SELECT 5 UNION SELECT 6 UNION SELECT 7 UNION SELECT 8 UNION SELECT 9) a,
        (SELECT 0 AS N UNION SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 4 UNION SELECT 5 UNION SELECT 6 UNION SELECT 7 UNION SELECT 8 UNION SELECT 9) b,
        (SELECT 0 AS N UNION SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 4 UNION SELECT 5 UNION SELECT 6 UNION SELECT 7 UNION SELECT 8 UNION SELECT 9) c,
        (SELECT 0 AS N UNION SELECT 1 UNION SELECT 2 UNION SELECT 3 UNION SELECT 4 UNION SELECT 5 UNION SELECT 6 UNION SELECT 7 UNION SELECT 8 UNION SELECT 9) d
) numbers
LIMIT 100000;
EOF
```

--------------------------------

### Troubleshooting: Run Quick Integration Tests

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

This command initiates a quick run of integration tests, useful for rapid feedback cycles during development.

```bash
# Start fresh
just test-integration-quick
```

--------------------------------

### Benchmark with Custom Host and Database

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Combines custom MySQL host and a specific database for benchmarking.

```bash
# Combine with custom database
MYSQL_HOST=remote.db just bench production 3
```

--------------------------------

### Build and Test Commands

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Commands for building the project for current or all platforms, running tests, and formatting the code.

```bash
# Build for current platform
just build

# Build for all platforms
just build-all

# Run tests
just test

# Format code
just fmt
```

--------------------------------

### Troubleshooting: Check Docker Status

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Use this command to check if Docker is currently running. If it's not, you'll need to start your Docker Desktop or equivalent application.

```bash
# Check Docker is running
docker ps

# If not, start Docker Desktop / OrbStack / etc.

# Verify Docker Compose is available
docker compose version
```

--------------------------------

### Pre-Release Checklist: Full Integration Tests

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Execute the full suite of integration tests before a release to confirm the application's stability and correctness across various scenarios.

```bash
# 2. Full integration tests
just test-integration
```

--------------------------------

### Create Database if Missing

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Create a database if it does not already exist on the MySQL server.

```bash
mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 -e "CREATE DATABASE IF NOT EXISTS testdb;"
```

--------------------------------

### Create Test Database

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Creates a new database named 'test_restore' on the MySQL server. Ensure you have the correct host, port, username, and password.

```bash
mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 -e "CREATE DATABASE test_restore;"
```

--------------------------------

### Run Default Benchmark

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Executes the default benchmark with predefined settings (testdb, 3 iterations).

```bash
just bench
```

--------------------------------

### Previewing Dumps and Table Sizes

Source: https://github.com/helgesverre/dbdump/blob/main/website/index.html

Before performing a full dump, you can preview table sizes using `dbdump list` or simulate the dump process with `--dry-run` to see which tables would be excluded.

```bash
dbdump list -H localhost -u root -d mydb        # See table sizes
```

```bash
dbdump dump -H localhost -u root -d mydb --dry-run   # Preview exclusions
```

--------------------------------

### Build Binary and Run Security Tests

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Builds the dbdump binary and then executes the security verification script. This is a manual way to run security tests without Docker if needed.

```bash
# Build binary
just build

# Run security verification
./test/verify-security.sh
```

--------------------------------

### Project Structure Overview

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Illustrates the directory structure of the dbdump project, highlighting key components like the CLI entry point, internal modules, and configuration files.

```bash
dump-tool/
├── cmd/dbdump/          # CLI entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── database/        # Database operations
│   ├── patterns/        # Pattern matching
│   └── ui/              # Interactive UI
├── configs/             # Example configurations
└── justfile             # Build commands
```

--------------------------------

### Run Benchmarks with 'just' Command

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Execute benchmark tests using the 'just' command-line tool.

```bash
just bench testdb 5
```

--------------------------------

### Generate Sample Data

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Generate sample data for testing. Specify size, host, port, and database. Environment variables can also be used for configuration.

```bash
./test/generate-sample-data.sh [size] [host] [port] [database]
```

```bash
# Generate small dataset on MySQL 8.0
./test/generate-sample-data.sh small 127.0.0.1 3308 testdb

# Generate large dataset on MariaDB
./test/generate-sample-data.sh large 127.0.0.1 3310 testdb

# Generate medium dataset using environment variable
export MYSQL_ROOT_PASSWORD=testpass123
./test/generate-sample-data.sh medium
```

--------------------------------

### Run Integration Tests with Options

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Execute the integration test suite. An optional quick smoke test can be run by setting TEST_QUICK=1.

```bash
# Run full test suite on all databases
./test/integration-test.sh

# Optional quick smoke test (MySQL 8.0 only; local compose is cleaned up automatically)
TEST_QUICK=1 ./test/integration-test.sh
```

--------------------------------

### Run Quick Integration Test

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Performs a faster integration test using a small dataset on MySQL 8.0 only. The local Docker Compose environment is automatically cleaned up after execution.

```bash
just test-integration-quick
```

--------------------------------

### Establish Baseline Benchmark

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Creates a baseline benchmark run with 5 iterations for statistical confidence. Note the median throughput from the output.

```bash
# Create baseline with 5 iterations for statistical confidence
just bench testdb 5

# Note the median throughput from the output
# Example: Median throughput: 115.23 MB/s
```

--------------------------------

### Benchmark with Custom MySQL Host

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Runs the benchmark using a custom MySQL host specified by the MYSQL_HOST environment variable.

```bash
# Use different MySQL host
MYSQL_HOST=prod.example.com just bench
```

--------------------------------

### Run dbdump with a Configuration File

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Perform a database dump using a specified configuration file. This allows for pre-defined settings for the dump process.

```bash
dbdump dump -H localhost -u root -d mydb --config ./project.yaml
```

--------------------------------

### Analyze CPU Profile

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Uses the go tool pprof to analyze a CPU profile file.

```bash
# Analyze
go tool pprof bin/dbdump cpu.prof
```

--------------------------------

### Run Quick Benchmark

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Performs a quick benchmark, typically a single iteration.

```bash
just bench-quick
```

--------------------------------

### GitHub Actions Workflow for Performance Benchmarking

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

This workflow automates performance benchmarking for pull requests. It sets up Go, loads a test database, runs benchmarks, and uploads results.

```yaml
name: Performance Benchmark

on: [pull_request]

jobs:
  benchmark:
    runs-on: ubuntu-latest
    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: root
          MYSQL_DATABASE: test
        options: >-
          --health-cmd="mysqladmin ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=3

    steps:
      - uses: actions/checkout@v2

      - name: Set up Go
        uses: actions/setup-go@v2
        with:
          go-version: '1.24'

      - name: Load test database
        run: |
          mysql -h 127.0.0.1 -u root -proot test < test/fixtures/benchmark.sql

      - name: Run benchmark
        run: just bench test 5

      - name: Upload results
        uses: actions/upload-artifact@v2
        with:
          name: benchmark-results
          path: benchmark-results/
```

--------------------------------

### Performance Benchmarking: Generate Large Dataset

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

These commands are used for manual performance benchmarking. First, bring up the Docker environment and generate a large dataset for testing.

```bash
# Generate large dataset
just test-docker-up
just test-data-large
```

--------------------------------

### Benchmark with Custom MySQL Credentials

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Runs the benchmark using custom MySQL user and password specified by environment variables.

```bash
# Use different credentials
MYSQL_USER=readonly MYSQL_PASSWORD=secret just bench
```

--------------------------------

### Pre-Release Checklist: Manual Smoke Test

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Perform a manual smoke test by running the dbdump command with specific parameters. This is a final check before releasing the software.

```bash
# 4. Manual smoke test
export DBDUMP_MYSQL_PWD=testpass123
./bin/dbdump dump -H 127.0.0.1 -P 3308 -u root -d testdb --auto
```

--------------------------------

### Rebuild and Run with CPU Profiling

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Rebuilds the project after adding CPU profiling instrumentation and then runs the executable.

```bash
# Rebuild and run
just build
./bin/dbdump dump -H 127.0.0.1 -u root -d testdb --auto
```

--------------------------------

### Dump database using a project configuration file

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Dumps the database using settings defined in a project-specific YAML configuration file. This allows for consistent backup configurations across a project.

```bash
dbdump dump -H localhost -u root -d mydb --config ./myproject.yaml
```

--------------------------------

### List tables with sizes

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Lists all tables in the specified database along with their sizes. This is useful for understanding database structure and identifying large tables.

```bash
dbdump list -H localhost -u root -d mydb
```

--------------------------------

### Performance Benchmarking: Compare File Sizes

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

After generating dumps with both dbdump and mysqldump, compare the resulting file sizes to evaluate compression or efficiency differences.

```bash
# Compare file sizes
ls -lh testdb_*.sql standard_dump.sql
```

--------------------------------

### Run with Memory Profiling

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Executes the dbdump binary with memory profiling enabled using GODEBUG environment variable.

```bash
# Run with memory profiling
GODEBUG=gctrace=1 ./bin/dbdump dump -H 127.0.0.1 -u root -d testdb --auto
```

--------------------------------

### Build with Memory Profiling

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Builds the dbdump executable with necessary flags for memory profiling.

```bash
# Build with profiling
go build -o bin/dbdump ./cmd/dbdump
```

--------------------------------

### Troubleshooting Benchmark Script Permissions and Dependencies

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Checks and sets execute permissions for the benchmark script and verifies the presence of required command-line tools like 'bc' and 'mysql'.

```bash
# Check script permissions
ls -la scripts/benchmark.sh
# Should show: -rwxr-xr-x

# Make executable if needed
chmod +x scripts/benchmark.sh

# Verify dependencies
which bc  # Required for calculations
which mysql  # Required for database stats
```

--------------------------------

### Create Global Configuration

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Sets up a global configuration file for dbdump, defining default exclusions for tables. This configuration is automatically applied to subsequent dump commands.

```bash
# Create your global config
cat > ~/.dbdump.yaml << EOF
name: "My Global Defaults"
exclude:
  exact:
    - activity_logs
    - user_sessions
  patterns:
    - "temp_*"
    - "*_old"
EOF

# Now all your dumps will use this config
dbdump dump -H localhost -u root -d mydb
```

--------------------------------

### Dump Production Database for Local Development

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Creates a SQL dump of a production database and saves it to a file, intended for transfer and use in a local development environment. Requires SSH access for file transfer.

```bash
# On production server
dbdump dump \
  -H localhost \
  -u produser \
  -d production_db \
  --auto \
  -o prod-for-dev.sql

# Transfer file
scp prod-for-dev.sql dev@localhost:~

# On development machine
mysql -u root mydb < prod-for-dev.sql
```

--------------------------------

### Benchmark All Local Test Databases

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Executes benchmarks across all configured local test databases.

```bash
just bench-all
```

--------------------------------

### Benchmark with Custom MySQL Port

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Runs the benchmark using a custom MySQL port specified by the MYSQL_PORT environment variable.

```bash
# Use a different port
MYSQL_PORT=3307 just bench testdb 3
```

--------------------------------

### Wait for MySQL Database to be Ready

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Continuously check if the MySQL server is accessible and ready to accept connections.

```bash
while ! mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 -e "SELECT 1" &>/dev/null; do
    echo "Waiting for MySQL..."
    sleep 2
done
echo "MySQL is ready!"
```

--------------------------------

### Benchmark Specific Database with Custom Iterations

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Runs a benchmark on a specified database for a custom number of iterations.

```bash
just bench mydb 5
```

--------------------------------

### Verify Restored Tables

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Shows all tables within the 'test_restore' database to confirm that the restore operation was successful. This is a crucial step in verifying the integrity of the restored data.

```bash
mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 test_restore -e "SHOW TABLES;"
```

--------------------------------

### Add CPU Profiling to Main

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Temporarily adds CPU profiling instrumentation to the main Go program.

```go
import "runtime/pprof"

# In main():
f, _ := os.Create("cpu.prof")
pprof.StartCPUProfile(f)
defer pprof.StopCPUProfile()
```

--------------------------------

### Pre-Release Checklist: Security Verification

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Run the security verification command as part of the pre-release checklist to ensure all security-related tests pass.

```bash
# 1. Security verification
just verify-security
```

--------------------------------

### Restore SQL Dump to a New Database

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Create a new database and restore a SQL dump file into it using mysql client commands.

```bash
mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 -e "CREATE DATABASE test_restore;"
mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 test_restore < test_dump.sql
```

--------------------------------

### Run Integration Tests with Verbose Output

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Execute integration tests using a bash script and enable verbose output for debugging.

```bash
bash -x ./test/integration-test.sh
```

--------------------------------

### Run dbdump through SSH Bastion

Source: https://github.com/helgesverre/dbdump/blob/main/website/index.html

Create a database dump using dbdump by connecting through an SSH bastion host. This is useful for accessing databases on private networks.

```bash
dbdump dump -H mysql80 -P 3306 -u root -d mydb \
  --ssh-host bastion.example.com \
  --ssh-user deploy \
  --auto
```

--------------------------------

### dbdump dump command - With Project Config

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Perform a database dump using a project-specific configuration file.

```bash
dbdump dump -H localhost -u root -d mydb --config ./project-config.yaml
```

--------------------------------

### List Saved Connection Profiles

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Displays all connection profiles saved in the default configuration file. This command is useful for reviewing existing profiles before use.

```bash
dbdump config list
```

--------------------------------

### Basic dbdump Dump Command

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Execute a basic database dump using dbdump. It connects to the specified host and database with the provided user credentials.

```bash
# Set password securely via environment variable
export DBDUMP_MYSQL_PWD=yourpassword

# Dump database (interactive)
dbdump dump -H localhost -u root -d mydb
```

--------------------------------

### Analyze Memory Profile

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Uses the go tool pprof to analyze a memory profile file.

```bash
# Analyze memory profile (if instrumented)
go tool pprof bin/dbdump mem.prof
```

--------------------------------

### Compare Benchmark Runs Using Diff

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Compares two specific benchmark summary files to identify differences.

```bash
diff benchmark-results/benchmark_testdb_20251021_120000_summary.txt \
     benchmark-results/benchmark_testdb_20251021_130000_summary.txt
```

--------------------------------

### List Database Tables and Perform Dry Run

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Inspects database tables and their sizes before executing a full dump. The `list` command shows table information, and `dump --dry-run` simulates the dump process without creating a file.

```bash
# See all tables and sizes
dbdump list -H localhost -u root -d mydb

# Do a dry run
dbdump dump -H localhost -u root -d mydb --dry-run

# If happy, do the real dump
dbdump dump -H localhost -u root -d mydb
```

--------------------------------

### dbdump with Stream Compression

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Create a compressed database dump using a specified compression method like gzip.

```bash
dbdump dump -u root -p yourpassword -d mydatabase --compress gzip
```

--------------------------------

### Verifying Database Existence and Table Count

Source: https://github.com/helgesverre/dbdump/blob/main/BENCHMARKING.md

Commands to list all databases accessible by the root MySQL user and to check if a specific database exists and contains tables.

```bash
# List available databases
mysql -u root -e "SHOW DATABASES"

# Verify database exists
mysql -u root -e "USE testdb; SELECT COUNT(*) FROM information_schema.tables"
```

--------------------------------

### Generate Large Dataset for Benchmarking

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Use a script to generate a large dataset for performance testing of the dbdump tool.

```bash
./test/generate-sample-data.sh large 127.0.0.1 3308 testdb
```

--------------------------------

### Provide Password via Command-Line Flag (Least Secure)

Source: https://github.com/helgesverre/dbdump/blob/main/SECURITY.md

This method is the least secure and should only be used for local development or testing. Passwords provided this way can appear in shell history and process lists.

```bash
dbdump dump -H 127.0.0.1 -u root -p yourpassword -d mydb
```

--------------------------------

### List All Tables in a Database

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Use dbdump to list all tables within a specified database.

```bash
./bin/dbdump list -H 127.0.0.1 -P 3308 -u root -d testdb
```

--------------------------------

### Restore Database from SQL Dump

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Restores the 'test_restore' database from a SQL dump file. The wildcard '*' in the filename allows for versioned dump files. Ensure the dump file is accessible.

```bash
mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 test_restore < testdb_*.sql
```

--------------------------------

### Dump database with streaming compression

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Dumps the database and streams the output with compression. Supports auto-detection, gzip, and zstd. The --auto flag uses smart defaults.

```bash
dbdump dump -H localhost -u root -d mydb --auto --compress gzip
```

--------------------------------

### Troubleshooting: View Container Logs

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

This command displays the logs for a specific Docker container, which can help in diagnosing issues with services like MySQL.

```bash
# View container logs
docker compose logs mysql80
```

--------------------------------

### Basic dbdump Usage (Interactive)

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Perform a database dump using interactive mode, specifying connection details and the database name.

```bash
dbdump dump -u root -p yourpassword -d mydatabase
```

--------------------------------

### Verify Temporary Defaults File Usage

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Confirms that the code correctly handles authentication for subprocesses by using a temporary defaults file, as indicated by 'defaults-extra-file' in the dumper.go file.

```bash
grep 'defaults-extra-file' internal/database/dumper.go
# Should find temporary defaults file handling
```

--------------------------------

### Troubleshooting: Restart Docker Containers

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

These commands are used to clean up and restart Docker containers, often resolving issues related to service startup or state corruption.

```bash
# Restart containers
just test-docker-clean
just test-docker-up
```

--------------------------------

### dbdump with Output File

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Specify a file name for the database dump output.

```bash
dbdump dump -u root -p yourpassword -d mydatabase -o backup.sql
```

--------------------------------

### Dump Database with Auto Mode (Excluding Tables)

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Use dbdump in auto mode to create a dump, excluding noisy tables. Set the password via environment variable.

```bash
export DBDUMP_MYSQL_PWD=testpass123
./bin/dbdump dump -H 127.0.0.1 -P 3308 -u root -d testdb --auto -o auto_dump.sql
```

--------------------------------

### Verify File Permissions

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Ensures that dump files are created with owner-only read/write permissions (0600). This test requires Docker to be running with a test database.

```bash
./bin/dbdump dump ... -o test.sql
stat test.sql  # Should show 0600 (-rw-------)
```

--------------------------------

### Auto mode dump with custom output file

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Performs a database dump using smart defaults and saves the output to a specified file. The --auto flag simplifies the dump process by using sensible defaults.

```bash
dbdump dump -H localhost -u root -d mydb --auto -o daily-backup.sql
```

--------------------------------

### Test Exclusion Pattern

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Demonstrates how to test an exclusion pattern using `dbdump list` and `dbdump dump --dry-run`. This helps verify that the pattern correctly identifies tables to be excluded.

```bash
# List tables first
dbdump list -H localhost -u root -d mydb

# Dry run with pattern
dbdump dump -H localhost -u root -d mydb --exclude-pattern "your_pattern_*" --dry-run
```

--------------------------------

### Manual Security and Data Integrity Testing

Source: https://github.com/helgesverre/dbdump/blob/main/README.md

Demonstrates testing security by ensuring passwords are not exposed in the process list and verifying file permissions and data integrity for triggers and events.

```bash
# Test security (password not in process list)
export DBDUMP_MYSQL_PWD=testpass123
./bin/dbdump dump -H 127.0.0.1 -P 3308 -u root -d testdb --auto
ps aux | grep dbdump  # Should NOT show password

# Verify file permissions (should be 0600)
ls -la testdb_*.sql

# Test data integrity (triggers and events are included; routines are intentionally omitted)
grep -i "CREATE TRIGGER" testdb_*.sql
grep -i "CREATE EVENT" testdb_*.sql
```

--------------------------------

### dbdump with Standard MySQL Password Variable

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Alternatively, use the standard MYSQL_PWD environment variable for the password.

```bash
export MYSQL_PWD=yourpassword
dbdump dump -H localhost -u root -d mydatabase
```

--------------------------------

### GitHub Actions CI Configuration

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

This YAML configuration defines a GitHub Actions workflow for running tests. It includes steps for checking out code, setting up Go, and executing security and integration tests.

```yaml
name: Tests

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-go@v4
        with:
          go-version: '1.24'
      - name: Security Tests
        run: just verify-security

  integration:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-go@v4
        with:
          go-version: '1.24'
      - name: Integration Tests
        run: just test-integration-clean
```

--------------------------------

### Run dbdump in Interactive Mode

Source: https://github.com/helgesverre/dbdump/blob/main/website/index.html

Perform a database dump using dbdump in interactive mode, prompting the user to select tables. Connects to localhost as root user for the 'mydb' database.

```bash
dbdump dump -H localhost -u root -d mydb
```

--------------------------------

### dbdump with Environment Variable for Password

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Securely provide the MySQL password using the DBDUMP_MYSQL_PWD environment variable.

```bash
export DBDUMP_MYSQL_PWD=yourpassword
dbdump dump -H localhost -u root -d mydatabase
```

--------------------------------

### Test dbdump Across Different MySQL/MariaDB Versions

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Run the dbdump command against different MySQL and MariaDB versions by specifying different ports.

```bash
./bin/dbdump dump -H 127.0.0.1 -P 3307 -u root -d testdb --auto
./bin/dbdump dump -H 127.0.0.1 -P 3308 -u root -d testdb --auto
./bin/dbdump dump -H 127.0.0.1 -P 3309 -u root -d testdb --auto
./bin/dbdump dump -H 127.0.0.1 -P 3310 -u root -d testdb --auto
```

--------------------------------

### Performance Benchmarking: Time Standard mysqldump

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Compare the performance of dbdump against the standard mysqldump utility by timing its execution for generating a database dump.

```bash
# Compare with standard mysqldump
export MYSQL_PWD=testpass123
time mysqldump -h 127.0.0.1 -P 3308 -u root testdb > standard_dump.sql
```

--------------------------------

### Search and Count SQL Events and Triggers

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Use grep to search for specific SQL commands like CREATE EVENT or count occurrences of trigger names in a dump file.

```bash
grep -i "CREATE EVENT" test_dump.sql
```

```bash
grep -c "after_order_insert" test_dump.sql
```

--------------------------------

### Create Project-Specific Configuration for Laravel

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Generates a configuration file tailored for a Laravel application, specifying common tables to exclude. This file can then be used with the dbdump command.

```bash
# Create project config
cat > laravel-config.yaml << EOF
name: "Laravel App"
exclude:
  exact:
    - jobs
    - failed_jobs
    - password_resets
    - personal_access_tokens
  patterns:
    - "cache_*"
    - "session_*"
EOF

# Use it
dbdump dump -H localhost -u root -d laravel_db --config laravel-config.yaml --auto
```

--------------------------------

### Benchmark Standard mysqldump Performance

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Measure the time taken by the standard mysqldump utility for comparison.

```bash
time mysqldump -h 127.0.0.1 -P 3308 -u root -ptestpass123 testdb > standard_dump.sql
```

--------------------------------

### Cleanup Restored Database

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Drop the restored database using the mysql client.

```bash
mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 -e "DROP DATABASE test_restore;"
```

--------------------------------

### Validate YAML Configuration File

Source: https://github.com/helgesverre/dbdump/blob/main/USER-GUIDE.md

Uses the `yq` tool to validate the syntax of a YAML configuration file. This is helpful for troubleshooting 'failed to load config file' errors.

```bash
# Install yq if needed
brew install yq

# Validate
yq eval ~/.dbdump.yaml
```

--------------------------------

### Troubleshooting: Make Scripts Executable

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Ensure that shell scripts have execute permissions before running them. This command grants execute permissions to files in the 'test' directory.

```bash
# Make scripts executable
chmod +x test/*.sh
```

--------------------------------

### Set MYSQL_PWD Environment Variable (Fallback)

Source: https://github.com/helgesverre/dbdump/blob/main/SECURITY.md

As an alternative, the standard MYSQL_PWD environment variable can be used. dbdump falls back to this for compatibility if DBDUMP_MYSQL_PWD is not set.

```bash
export MYSQL_PWD=yourpassword
dbdump dump -H 127.0.0.1 -u root -d mydb
```

--------------------------------

### Rebuild dbdump and Regenerate Test Data

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Clean the project, rebuild the dbdump binary, and regenerate test data for integration tests.

```bash
just clean && just build
./test/generate-sample-data.sh small 127.0.0.1 3308 testdb
```

--------------------------------

### Verify No '-p' Password Flag Usage

Source: https://github.com/helgesverre/dbdump/blob/main/TESTING_GUIDE.md

Checks the source code to ensure that the insecure '-p<password>' flag pattern is not used in the dumper.go file.

```bash
grep '"-p' internal/database/dumper.go
# Should return nothing (no -p flag usage)
```

--------------------------------

### Verify Database Restoration

Source: https://github.com/helgesverre/dbdump/blob/main/test/README.md

Check tables, triggers, events, and procedures in the restored database using mysql client commands.

```bash
mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 test_restore -e "SHOW TABLES;"
mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 test_restore -e "SHOW TRIGGERS;"
mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 test_restore -e "SHOW EVENTS;"
mysql -h 127.0.0.1 -P 3308 -u root -ptestpass123 test_restore -e "SHOW PROCEDURE STATUS WHERE Db = 'test_restore';"
```