When attempting to upgrade PostgreSQL from version 9.0 to 9.1.2, you might encounter this specific error:

FATAL:  database files are incompatible with server
DETAIL:  The data directory was initialized by PostgreSQL version 9.0, which is not compatible with this version 9.1.2.

PostgreSQL maintains strict version compatibility for its data directory format. The error occurs because:

• The data directory was initialized with PostgreSQL 9.0
• You're trying to start it with PostgreSQL 9.1.2
• The internal storage formats are incompatible between major versions

Here's the correct way to upgrade using pg_upgrade:

# First, stop both PostgreSQL instances
brew services stop postgresql@9.0
brew services stop postgresql@9.1

# Create a new data directory for 9.1
initdb /usr/local/var/postgres9.1 -E utf8

# Run pg_upgrade with correct parameters
pg_upgrade \
  -b /usr/local/Cellar/postgresql@9.0/9.0.4/bin \
  -B /usr/local/Cellar/postgresql@9.1/9.1.2/bin \
  -d /usr/local/var/postgres \
  -D /usr/local/var/postgres9.1 \
  -v

If pg_upgrade fails, consider these approaches:

Option 1: Dump and Restore

pg_dumpall -p 5432 -U postgres > dump.sql
psql -p 5433 -U postgres -f dump.sql

Option 2: Use Homebrew's Migration Tools

brew postgresql-upgrade-database

• Verify both old and new PostgreSQL versions are installed
• Check file permissions on data directories
• Review PostgreSQL logs for additional clues
• Ensure no PostgreSQL processes are running during upgrade

Always:

• Backup your databases before attempting upgrades
• Test the upgrade process on a staging environment first
• Consider waiting for point releases (9.1.x) rather than jumping major versions

When attempting to start PostgreSQL after a Homebrew upgrade, many developers encounter this frustrating error:

FATAL:  database files are incompatible with server
DETAIL:  The data directory was initialized by PostgreSQL version 9.0, 
which is not compatible with this version 9.1.2.

The standard pg_upgrade approach often fails with Homebrew installations because:

• Homebrew maintains multiple versioned directories
• The tool expects specific version compatibility ranges
• Environment paths differ from standard PostgreSQL installations

Here's the complete solution that has worked for many developers:

Step 1: Identify Current and Target Versions

# Check current running version
psql --version

# List available Homebrew formulae
brew search postgresql

Step 2: Dump Your Existing Data

# Create backup directory
mkdir ~/postgres_backup

# Dump all databases
pg_dumpall > ~/postgres_backup/pre_upgrade_backup.sql

Step 3: Clean Installation Process

# Unlink current installation
brew unlink postgresql

# Install specific version
brew install postgresql@9.1

# Initialize new data directory
initdb /usr/local/var/postgres9.1 -E utf8

Step 4: Restore Your Data

# Start new server
pg_ctl -D /usr/local/var/postgres9.1 start

# Restore from backup
psql -f ~/postgres_backup/pre_upgrade_backup.sql postgres

For those who prefer pg_upgrade, this modified command often succeeds:

pg_upgrade \
  -d /usr/local/var/postgres \
  -D /usr/local/var/postgres9.1 \
  -b /usr/local/Cellar/postgresql/9.0.4/bin \
  -B /usr/local/Cellar/postgresql@9.1/9.1.2/bin \
  -O "-c search_path=public"

After migration, confirm everything works:

# Connect to new server
psql -U postgres

# Check version and data
SELECT version();
\list
\dt

• Not stopping all PostgreSQL instances before upgrade
• Forgetting to backup the original data directory
• Mixing binaries from different installation methods
• Overlooking extension compatibility issues