SCRAM-SHA-256 Quick Reference

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

Quick Setup

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

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

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