Rate Limiting and SSL Requirements

HeliosDB-Lite supports per-role rate limiting and SSL enforcement directly in the CREATE ROLE syntax. These features protect the database from runaway clients and ensure connections meet security requirements.

Prerequisites

HeliosDB-Lite v3.5+
For SSL enforcement: TLS-enabled connection (PostgreSQL wire protocol)

Concepts

RATE_LIMIT — Maximum queries per minute for a role. Enforced by the built-in quota manager before each query is processed.
SSL_REQUIRED — Connections for this role must use TLS. Plaintext connections are rejected at authentication time.
Quota window — Rate limits use a sliding window of 60 seconds. The counter resets automatically when the window expires.

Step 1: Create a Rate-Limited Role

CREATE ROLE api_service WITH LOGIN RATE_LIMIT 100;

This role can execute at most 100 queries per minute. The 101st query within any 60-second window returns an error.

You can also combine rate limiting with other options:

CREATE ROLE batch_worker WITH LOGIN RATE_LIMIT 500 PASSWORD 'worker_pass';

Step 2: Create an SSL-Required Role

CREATE ROLE secure_user WITH LOGIN SSL_REQUIRED;

When secure_user connects, HeliosDB checks that the connection uses TLS. If the client connected without SSL, authentication fails.

Step 3: Combine Rate Limiting and SSL

CREATE ROLE production_app WITH LOGIN RATE_LIMIT 1000 SSL_REQUIRED PASSWORD 'prod_pass';

This role requires TLS and is limited to 1,000 queries per minute.

Step 4: Observe Rate Limiting in Action

Connect as the rate-limited role and issue queries:

-- Assume connected as api_service
SELECT 1;  -- OK (count: 1/100)
SELECT 2;  -- OK (count: 2/100)
-- ... repeat ...
-- At query 101 within the same minute:
-- ERROR: Rate limit exceeded for user 'api_service' (100 queries/minute)

The error message includes the role name and the configured limit.

Step 5: Monitor Quotas

helios_user_quotas

This system view shows the current rate-limit state for each user:

SELECT * FROM helios_user_quotas;

username	requests_per_minute	current_count	window_seconds_remaining
api_service	100	47	38
batch_worker	500	312	15

Columns:

requests_per_minute: The configured limit
current_count: Queries executed in the current window
window_seconds_remaining: Seconds until the window resets and the counter goes back to 0

helios_roles

You can also see the configured options on each role:

SELECT role_name, options FROM helios_roles;

role_name	options
api_service	LOGIN,RATE_LIMIT 100
batch_worker	LOGIN,RATE_LIMIT 500
secure_user	LOGIN,SSL_REQUIRED
production_app	LOGIN,RATE_LIMIT 1000,SSL_REQUIRED

Step 6: Adjust Rate Limits

To change a rate limit, use ALTER ROLE:

ALTER ROLE api_service SET rate_limit = '200';

The new limit takes effect on the next query. The current window counter is not reset.

Step 7: Remove Rate Limiting

Drop the role and recreate it without the RATE_LIMIT option, or set the limit to 0 (unlimited):

ALTER ROLE api_service SET rate_limit = '0';

SSL Enforcement Details

How It Works

The client initiates a connection via the PostgreSQL wire protocol.
HeliosDB checks whether the role has the SSL_REQUIRED flag.
If set and the connection is not TLS-encrypted, authentication returns an error before any query can be executed.
If the connection is TLS-encrypted, authentication proceeds normally (SCRAM-SHA-256).

Verifying SSL Status

SELECT * FROM pg_stat_ssl;

pid	ssl	version	cipher	bits	client_dn	client_serial	issuer_dn
1234	true	TLSv1.3	TLS_AES_256_GCM_SHA384	256

Use Cases

Multi-Tenant SaaS

Assign different rate limits to tenant tiers:

CREATE ROLE tenant_free   WITH LOGIN RATE_LIMIT 60;
CREATE ROLE tenant_pro    WITH LOGIN RATE_LIMIT 600;
CREATE ROLE tenant_ent    WITH LOGIN RATE_LIMIT 6000 SSL_REQUIRED;

API Gateway Protection

Limit an API backend role to prevent a single service from overwhelming the database:

CREATE ROLE api_gateway WITH LOGIN RATE_LIMIT 2000;

Compliance

Enforce SSL for roles that access regulated data:

CREATE ROLE pci_user WITH LOGIN SSL_REQUIRED;
GRANT SELECT ON payment_cards TO pci_user;

Common Pitfalls

Rate limit is per-role, not per-connection — If multiple connections share the same role, they share the same quota counter. Ten connections at 10 queries each hit a limit of 100.
Window drift — The sliding window starts from the first query in the window, not from a fixed clock boundary. A burst at the end of one window followed by a burst at the start of the next can temporarily exceed the expected rate.
SSL_REQUIRED has no effect on embedded mode — The SSL check applies only to network connections (PostgreSQL wire protocol). Embedded mode does not use network sockets, so the flag is stored but not enforced.
Quota manager must be initialized — Rate limiting depends on the internal quota manager. In embedded mode this is always active. In custom deployments, ensure the EmbeddedDatabase is constructed with default configuration.
RATE_LIMIT 0 means unlimited — Setting the limit to zero effectively disables rate limiting for that role.