---
title: "SCRAM-SHA-256 Quick Reference"
---

# SCRAM-SHA-256 Quick Reference

Fast reference for SCRAM-SHA-256 authentication in HeliosDB-Lite.

## Quick Setup

```bash
export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
export HELIOSDB_ADMIN_PASSWORD='a-long-random-password'

heliosdb-lite start --data-dir ./mydb \
  --auth scram-sha-256 --password "$HELIOSDB_ADMIN_PASSWORD"
```

The password applies to the built-in administrator accounts `postgres` and `helios`.

## Connect with psql

```bash
# Interactive prompt (recommended: keeps the password out of shell history)
psql "host=127.0.0.1 port=5432 user=postgres"

# Password from the environment
PGPASSWORD="$HELIOSDB_ADMIN_PASSWORD" psql "host=127.0.0.1 port=5432 user=postgres"

# With SSL (server started with --tls-cert and --tls-key)
psql "sslmode=require host=127.0.0.1 port=5432 user=postgres"
```

## User Management

Application users are SQL roles. A role with `LOGIN` and a password can authenticate
with SCRAM-SHA-256:

```sql
-- Add user
CREATE ROLE alice LOGIN PASSWORD 'a-long-random-password';

-- Change password
ALTER ROLE alice PASSWORD 'another-long-password';

-- Remove password authentication
ALTER ROLE alice PASSWORD NULL;

-- Remove user
DROP ROLE alice;
```

The built-in `postgres` and `helios` accounts take precedence: a SQL role cannot shadow
them. Connect applications as non-superuser roles so that row-level security applies.

## Authentication Methods

| `--auth` value | Use |
|----------------|-----|
| `scram-sha-256` | Recommended for every networked deployment |
| `md5` | Legacy clients only |
| `password` | Cleartext password; only over TLS |
| `trust` | Default; accepts every connection without a password. Local development only |

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "User not found" | Create the role with `CREATE ROLE ... LOGIN PASSWORD ...`, or use `postgres` |
| "Invalid password" | Reset it with `ALTER ROLE ... PASSWORD ...` |
| "requires --password to be set" | Every method except `trust` needs `--password` at startup |
| Client errors | Ensure the client supports SCRAM-SHA-256 (psql 10+) |

## Security Checklist

- Use SCRAM-SHA-256 in production
- Combine with SSL/TLS
- Use strong passwords (12+ chars)
- Rotate passwords with `ALTER ROLE`
- Keep `--listen` on `127.0.0.1` unless remote clients need access

## RFC References

- [RFC 5802 - SCRAM](https://tools.ietf.org/html/rfc5802)
- [RFC 7677 - SCRAM-SHA-256](https://tools.ietf.org/html/rfc7677)
- [PostgreSQL SCRAM](https://www.postgresql.org/docs/current/sasl-authentication.html)

## See Also

- [SCRAM-SHA-256 Authentication](/docs/lite/features/scram_sha256_authentication/)