explorer-monorepo/docs/DATABASE_CONNECTION_GUIDE.md

Database Connection Guide

Important: Two Different Database Users

There are two separate database systems:

1. Blockscout Database (for Blockscout explorer)

   • User: blockscout
   • Password: blockscout
   • Database: blockscout

2. Custom Explorer Backend Database (for tiered architecture)

   • User: explorer
   • Password: L@ker$2010
   • Database: explorer

Correct Connection Command

For the custom explorer backend (tiered architecture), use:

PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer -c "SELECT 1;"

NOT:

# ❌ Wrong - this is for Blockscout
PGPASSWORD='blockscout' psql -h localhost -U blockscout -d explorer -c "SELECT 1;"

Step-by-Step Database Setup

1. Test Connection

# Test connection to custom explorer database
PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer -c "SELECT version();"

2. Check if Tables Exist

# Check for track schema tables
PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer -c "
SELECT table_name 
FROM information_schema.tables 
WHERE table_schema = 'public' 
AND table_name IN ('wallet_nonces', 'operator_roles', 'addresses', 'token_transfers')
ORDER BY table_name;
"

3. Run Migration (if tables don't exist)

cd explorer-monorepo
PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer \
  -f backend/database/migrations/0010_track_schema.up.sql

4. Verify Migration

# Should return 4 or more
PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer -c "
SELECT COUNT(*) as table_count 
FROM information_schema.tables 
WHERE table_schema = 'public' 
AND table_name IN ('wallet_nonces', 'operator_roles', 'addresses', 'token_transfers', 'analytics_flows', 'operator_events');
"

Troubleshooting

If Connection Fails

1. Check if PostgreSQL is running:

   systemctl status postgresql
   

2. Check if user exists:

   # Connect as postgres superuser
   sudo -u postgres psql -c "\du"
   

   You should see both blockscout and explorer users.

3. Check if database exists:

   sudo -u postgres psql -c "\l"
   

   You should see both blockscout and explorer databases.

4. Create user and database if missing:

   sudo -u postgres psql << EOF
   CREATE USER explorer WITH PASSWORD 'L@ker\$2010';
   CREATE DATABASE explorer OWNER explorer;
   GRANT ALL PRIVILEGES ON DATABASE explorer TO explorer;
   \q
   EOF
   

If Password Authentication Fails

1. Verify password is correct:

   • Custom explorer: L@ker$2010
   • Blockscout: blockscout

2. Check pg_hba.conf:

   sudo cat /etc/postgresql/*/main/pg_hba.conf | grep -E "(local|host.*explorer)"
   

   Should allow password authentication for local connections.

3. Reload PostgreSQL:

   sudo systemctl reload postgresql
   

Quick Fix Script

Use the provided script:

cd explorer-monorepo
export DB_PASSWORD='L@ker$2010'
bash scripts/fix-database-connection.sh

This script will:

• Test the connection
• Check for existing tables
• Run migration if needed
• Provide next steps

After Database is Connected

1. Restart API server with database:

   pkill -f api-server
   cd explorer-monorepo/backend
   export DB_PASSWORD='L@ker$2010'
   export JWT_SECRET='your-secret-here'
   ./bin/api-server
   

2. Verify health endpoint:

   curl http://localhost:8080/health
   

   Should show database as "ok" instead of "error".

3. Test authentication:

   curl -X POST http://localhost:8080/api/v1/auth/nonce \
     -H 'Content-Type: application/json' \
     -d '{"address":"0x1234567890123456789012345678901234567890"}'
   

Summary

• Custom Explorer Backend: Use explorer user with password L@ker$2010
• Blockscout: Use blockscout user with password blockscout
• They are separate systems with separate databases