# 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:

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

**NOT:**
```bash
# ❌ 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

```bash
# 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

```bash
# 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)

```bash
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

```bash
# 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:**
   ```bash
   systemctl status postgresql
   ```

2. **Check if user exists:**
   ```bash
   # Connect as postgres superuser
   sudo -u postgres psql -c "\du"
   ```
   
   You should see both `blockscout` and `explorer` users.

3. **Check if database exists:**
   ```bash
   sudo -u postgres psql -c "\l"
   ```
   
   You should see both `blockscout` and `explorer` databases.

4. **Create user and database if missing:**
   ```bash
   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:**
   ```bash
   sudo cat /etc/postgresql/*/main/pg_hba.conf | grep -E "(local|host.*explorer)"
   ```
   
   Should allow password authentication for local connections.

3. **Reload PostgreSQL:**
   ```bash
   sudo systemctl reload postgresql
   ```

## Quick Fix Script

Use the provided script:

```bash
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:**
   ```bash
   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:**
   ```bash
   curl http://localhost:8080/health
   ```
   
   Should show database as "ok" instead of "error".

3. **Test authentication:**
   ```bash
   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