dlx-ansible/docs/POSTGRES-USER-MANAGEMENT.md

# PostgreSQL User Management

This guide covers creating and managing PostgreSQL users on the postgres server (192.168.200.103).

## Quick Reference

### Create Superuser with Random Password
```bash
ansible-playbook playbooks/create-postgres-user.yml -e "pg_username=hiveops pg_superuser=true"
```

### Create User with Specific Password
```bash
ansible-playbook playbooks/create-postgres-user.yml -e "pg_username=myapp pg_password=SecurePass123"
```

### Create Database Creator User
```bash
ansible-playbook playbooks/create-postgres-user.yml -e "pg_username=dbadmin pg_createdb=true"
```

### Create Basic User (No Special Privileges)
```bash
ansible-playbook playbooks/create-postgres-user.yml -e "pg_username=readonly"
```

## Playbook Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `pg_username` | Yes | - | PostgreSQL username to create |
| `pg_password` | No | Auto-generated | Password (random 32-char base64 if not provided) |
| `pg_superuser` | No | `false` | Grant SUPERUSER privilege |
| `pg_createdb` | No | `false` | Grant CREATEDB privilege |
| `pg_createrole` | No | `false` | Grant CREATEROLE privilege |
| `pg_login` | No | `true` | Allow user to login |
| `pg_save_credentials` | No | `false` | Save credentials to `/tmp/postgres-user-*.txt` |

## Examples

### Example 1: HiveOps Application User (Superuser)
```bash
ansible-playbook playbooks/create-postgres-user.yml \
  -e "pg_username=hiveops" \
  -e "pg_superuser=true" \
  -e "pg_save_credentials=true"
```

**Output:**
- Random password generated
- Superuser privileges
- Credentials saved to `/tmp/postgres-user-hiveops-*.txt`

### Example 2: Application User with Database Creation
```bash
ansible-playbook playbooks/create-postgres-user.yml \
  -e "pg_username=smartjournal" \
  -e "pg_createdb=true" \
  -e "pg_password=MySecurePassword123"
```

**Output:**
- Specific password used
- Can create databases
- Cannot create other users

### Example 3: Read-Only Application User
```bash
# First create the user
ansible-playbook playbooks/create-postgres-user.yml \
  -e "pg_username=reporting"

# Then grant SELECT permissions manually
ansible postgres -m shell \
  -a "psql -d mydb -c 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO reporting;'" \
  --become-user=postgres -b
```

### Example 4: Multiple Users at Once
```bash
# Create a variables file
cat > /tmp/users.yml <<EOF
---
users:
  - username: hiveops
    superuser: true
  - username: smartjournal
    createdb: true
  - username: readonly
    superuser: false
EOF

# Run for each user
for user in hiveops smartjournal readonly; do
  ansible-playbook playbooks/create-postgres-user.yml \
    -e "pg_username=$user" \
    -e "@/tmp/users.yml"
done
```

## Ad-Hoc User Management

### Change User Password
```bash
ansible postgres -m shell \
  -a "psql -c \"ALTER USER hiveops WITH PASSWORD 'new_password';\"" \
  --become-user=postgres -b
```

### Grant Superuser to Existing User
```bash
ansible postgres -m shell \
  -a "psql -c 'ALTER USER myuser WITH SUPERUSER;'" \
  --become-user=postgres -b
```

### Revoke Superuser from User
```bash
ansible postgres -m shell \
  -a "psql -c 'ALTER USER myuser WITH NOSUPERUSER;'" \
  --become-user=postgres -b
```

### List All Users
```bash
ansible postgres -m shell \
  -a "psql -c '\du'" \
  --become-user=postgres -b
```

### Drop User
```bash
ansible postgres -m shell \
  -a "psql -c 'DROP USER myuser;'" \
  --become-user=postgres -b
```

## Database Permissions

### Grant All Privileges on Database
```bash
ansible postgres -m shell \
  -a "psql -c 'GRANT ALL PRIVILEGES ON DATABASE mydb TO hiveops;'" \
  --become-user=postgres -b
```

### Grant SELECT on All Tables
```bash
ansible postgres -m shell \
  -a "psql -d mydb -c 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly;'" \
  --become-user=postgres -b
```

### Grant CREATE on Schema
```bash
ansible postgres -m shell \
  -a "psql -d mydb -c 'GRANT CREATE ON SCHEMA public TO myuser;'" \
  --become-user=postgres -b
```

## Security Best Practices

1. **Use Strong Passwords**: Always use the auto-generated passwords or strong passwords (32+ characters)
2. **Principle of Least Privilege**: Only grant necessary permissions
3. **Superuser Sparingly**: Only create superusers when absolutely necessary
4. **Save Credentials Securely**: Use `pg_save_credentials=true` and move to vault
5. **Rotate Passwords**: Change passwords periodically for sensitive accounts

## Connection Examples

### psql Command Line
```bash
psql -h 192.168.200.103 -U hiveops -d mydatabase
```

### Spring Boot (application.properties)
```properties
spring.datasource.url=jdbc:postgresql://192.168.200.103:5432/hiveops
spring.datasource.username=hiveops
spring.datasource.password=j2ONAsFC6xPHk/VhktBE1qDKwUFsZQwjZvxf/rpViaE=
```

### Python (psycopg2)
```python
import psycopg2

conn = psycopg2.connect(
    host="192.168.200.103",
    port=5432,
    database="hiveops",
    user="hiveops",
    password="j2ONAsFC6xPHk/VhktBE1qDKwUFsZQwjZvxf/rpViaE="
)
```

### Node.js (pg)
```javascript
const { Pool } = require('pg');

const pool = new Pool({
  host: '192.168.200.103',
  port: 5432,
  database: 'hiveops',
  user: 'hiveops',
  password: 'j2ONAsFC6xPHk/VhktBE1qDKwUFsZQwjZvxf/rpViaE='
});
```

## Troubleshooting

### User Already Exists
The playbook will update the existing user with new privileges/password if it already exists.

### Permission Denied
Ensure you're using `-b` (become) flag and the postgres user exists on the server.

### Connection Refused
Check that PostgreSQL is listening on the network interface:
```bash
ansible postgres -m shell \
  -a "grep listen_addresses /etc/postgresql/*/main/postgresql.conf" -b
```

Should be: `listen_addresses = '*'`

### Authentication Failed
Check `pg_hba.conf` for connection rules:
```bash
ansible postgres -m shell \
  -a "cat /etc/postgresql/*/main/pg_hba.conf" -b
```

## History

### 2026-02-14
- Created playbook for automated PostgreSQL user creation
- Initial user created: `hiveops` (superuser)
- Password: `j2ONAsFC6xPHk/VhktBE1qDKwUFsZQwjZvxf/rpViaE=`

## Related Documentation
- [PostgreSQL Official Documentation](https://www.postgresql.org/docs/)
- [Security Best Practices](https://www.postgresql.org/docs/current/auth-methods.html)
- Ansible Project: `/source/dlx-src/dlx-ansible/`
- Playbook: `playbooks/create-postgres-user.yml`