Environment Variables

RIOT-X supports configuration via environment variables for some command-line options. This allows for convenient automation and containerized deployments without exposing sensitive information in command lines.

Configuration Precedence

Configuration values are applied in the following order (later values override earlier ones):

  1. Built-in defaults - Default values defined in the application

  2. Environment variables - Values set via RIOT_* environment variables

  3. Command-line arguments - Explicit values passed as CLI options

For example, if you set RIOT_REDIS_HOST=prod-redis but also pass --host dev-redis on the command line, the command-line value dev-redis will be used.

Naming Conventions

Environment variables follow these naming patterns:

  • Single Redis connection: Use RIOT_REDIS_* (e.g., RIOT_REDIS_HOST, RIOT_REDIS_PORT)

  • Source/Target in replication: Use RIOT_SOURCE_* and RIOT_TARGET_* (e.g., RIOT_SOURCE_HOST, RIOT_TARGET_HOST)

  • URI vs individual parameters: You can use either RIOT_REDIS_URI for a complete connection string, or individual parameters like RIOT_REDIS_HOST and RIOT_REDIS_PORT. The URI takes precedence if both are specified.

Job

Variable CLI Option Default Description

RIOT_THREADS

--threads

1

Number of concurrent threads to use for batch processing.

RIOT_BATCH

--batch

50

Number of items in each batch.

RIOT_RATE

--rate

none

Limit number of items written per second (e.g., 100 or 5k).

RIOT_DRY_RUN

--dry-run

false

Enable dummy writes.

RIOT_SKIP

--skip

none

Number of failed items before failing the job.

RIOT_RETRY

--retry

10

Number of times to retry failed items: 0 → never, -1 → always.

RIOT_FLUSH

--flush

50ms

Max duration between batch flushes.

RIOT_IDLE

--idle

none

Min duration to consider reader complete (e.g., 3s 5m).

Redis Connection

Variable CLI Option Default Description

RIOT_REDIS_URI

-u, --uri

none

Redis server URI.

RIOT_REDIS_HOST

-h, --host

localhost

Redis server hostname.

RIOT_REDIS_PORT

-p, --port

6379

Redis server port.

RIOT_REDIS_SOCKET

-s, --socket

none

Redis server socket (overrides hostname and port).

RIOT_REDIS_USER

--user

none

ACL style 'AUTH username pass'. Needs password.

RIOT_REDIS_PASS

-a, --pass

none

Password to use when connecting to the Redis server.

RIOT_REDIS_TIMEOUT

--timeout

60s

Redis command timeout (e.g., 30s or 5m).

RIOT_REDIS_DB

-n, --db

0

Redis database number.

RIOT_REDIS_TLS

--tls

false

Establish a secure TLS connection.

RIOT_REDIS_INSECURE

--insecure

false

Allow insecure TLS connection by skipping cert validation.

RIOT_REDIS_TLS_VERIFY

--verify

FULL

TLS verify mode: FULL, CA, NONE.

RIOT_REDIS_KEYSTORE

--keystore

none

Path to keystore.

RIOT_REDIS_KEYSTORE_PASS

--keystore-pass

none

Keystore password.

RIOT_REDIS_TRUST

--trust

none

Path to truststore.

RIOT_REDIS_TRUST_PASS

--trust-pass

none

Truststore password.

RIOT_REDIS_CERT

--cert

none

Client certificate to authenticate with (X.509 PEM).

RIOT_REDIS_KEY

--key

none

Private key file to authenticate with (PKCS#8 PEM).

RIOT_REDIS_KEY_PASS

--key-pass

none

Private key password.

RIOT_REDIS_CACERT

--cacert

none

CA Certificate file to verify with (X.509).

RIOT_REDIS_CLIENT

--client

none

Client name used to connect to Redis.

RIOT_REDIS_CLUSTER

-c, --cluster

false

Enable Redis cluster mode.

RIOT_REDIS_RESP

--resp

Newest supported

Redis protocol version: RESP2, RESP3.

RIOT_REDIS_POOL

--pool

8

Max number of Redis connections.

RIOT_REDIS_READ_FROM

--read-from

UPSTREAM

Which Redis cluster nodes to read from.

Redis Reader

Variable CLI Option Default Description

RIOT_KEY_PATTERN

--key-pattern

none

Pattern of keys to read (default: all keys).

RIOT_KEY_TYPE

--key-type

none

Type of keys to read (default: all types).

RIOT_SCAN_COUNT

--scan-count

100

How many keys to read at once on each scan iteration.

RIOT_READ_BATCH

--read-batch

50

Number of values each reader thread should read in a pipelined call.

RIOT_READ_THREADS

--read-threads

1

Number of threads reading key values concurrently.

RIOT_READ_QUEUE

--read-queue

10000

Capacity of the key scan queue for async key prefetching.

RIOT_EVENT_QUEUE

--event-queue

10000

Capacity of the keyspace notification queue.

RIOT_MEM_LIMIT

--mem-limit

0

Max memory usage for a key to be read (e.g., 12KB, 5MB).

Database

Variable CLI Option Default Description

RIOT_TABLE

TABLE parameter

none

Fully qualified Snowflake Table or Materialized View (e.g., DB.SCHEMA.TABLE).

RIOT_MAX

--max

none

Max number of rows to import from database.

RIOT_FETCH

--fetch

none

Number of rows to return with each fetch from database.

RIOT_ROWS

--rows

none

Max number of rows the ResultSet can contain.

RIOT_QUERY_TIMEOUT

--query-timeout

none

Database query timeout duration.

RIOT_DATABASE

--database

none

Snowflake database for the specified table(s).

RIOT_SCHEMA

--schema

none

Snowflake schema for the specified table(s).

RIOT_ROLE

--role

none

Snowflake role to use.

RIOT_WAREHOUSE

--warehouse

none

Snowflake warehouse to use.

RIOT_CDC_DATABASE

--cdc-database

none

Snowflake CDC database to use for stream and temp table.

RIOT_CDC_SCHEMA

--cdc-schema

none

Snowflake CDC schema to use for stream and temp table.

RIOT_POLL

--poll

default

Snowflake stream polling interval.

RIOT_SNAPSHOT

--snapshot

INITIAL

Snapshot mode: INITIAL, NEVER, etc.

RIOT_KEY_COLUMN

--key-column

none

Table column name(s) to use as the key for the CDC event.

RIOT_GEN

--gen

none

Columns to simulate CDC activity for instead of connecting to database.

RIOT_STREAM_LIMIT

--stream-limit

10000

Max length of RDI stream. Use 0 for no limit.

RIOT_STREAM_PREFIX

--stream-prefix

data:

Key prefix for stream containing change events.

RIOT_OFFSET_PREFIX

--offset-prefix

riotx:offset:

Key prefix for offset stored in Redis.

RIOT_OFFSET_KEY

--offset-key

metadata:debezium:offsets

Key name for Debezium offset.

RIOT_JDBC_DRIVER

--jdbc-driver

none

Fully qualified name of the JDBC driver.

RIOT_JDBC_URL

--jdbc-url

none

JDBC URL to connect to the database.

RIOT_JDBC_USER

--jdbc-user

none

Login username of the database.

RIOT_JDBC_PASS

--jdbc-pass

none

Login password of the database.

RIOT_JDBC_POOL

--jdbc-pool

none

Maximum number of connections in the pool.

RIOT_JDBC_TIMEOUT

--jdbc-timeout

none

Maximum time to wait for a connection from the pool.

Replication

Variable CLI Option Default Description

RIOT_SYNC_MODE

--mode

SCAN

Replication mode: SCAN, LIVE, or LIVEONLY.

RIOT_SYNC_STRUCT

--struct

false

Enable data structure-specific replication.

RIOT_LOG_KEYS

--log-keys

false

Log keys being read and written.

RIOT_COMPARE

--compare

QUICK

Compare mode: QUICK, FULL, or NONE.

RIOT_REMOVE_SOURCE_KEYS

--remove-source-keys

false

Delete keys from source after successful replication.

RIOT_NO_TTL

--no-ttl

false

Do not propagate key expiration times.

RIOT_STREAM_ID

--stream-id

true

Propagate stream message IDs.

RIOT_STREAM_PRUNE

--stream-prune

false

Drop empty streams.

RIOT_MERGE

--merge

false

Merge collection data structures instead of overwriting them.

Source Redis

Variable CLI Option Default Description

RIOT_SOURCE_URI

Source URI parameter

none

Source server URI.

RIOT_SOURCE_USER

--source-user

none

Source ACL style 'AUTH username pass'. Needs password.

RIOT_SOURCE_PASS

--source-pass

none

Password to use when connecting to the source server.

RIOT_SOURCE_TIMEOUT

--source-timeout

60s

Source Redis command timeout (e.g., 30s or 5m).

RIOT_SOURCE_TLS

--source-tls

false

Establish a secure TLS connection to source.

RIOT_SOURCE_INSECURE

--source-insecure

false

Allow insecure TLS connection to source by skipping cert validation.

RIOT_SOURCE_TLS_VERIFY

--source-verify

FULL

Source TLS verify mode: FULL, CA, NONE.

RIOT_SOURCE_CLIENT

--source-client

none

Client name used to connect to source Redis.

RIOT_SOURCE_CLUSTER

--source-cluster

false

Enable source cluster mode.

RIOT_SOURCE_RESP

--source-resp

Newest supported

Redis protocol version used to connect to source.

RIOT_SOURCE_POOL

--source-pool

8

Max number of source Redis connections.

RIOT_SOURCE_READ_FROM

--source-read-from

UPSTREAM

Which source Redis cluster nodes to read from.

Target Redis

Variable CLI Option Default Description

RIOT_TARGET_URI

Target URI parameter

none

Target server URI.

RIOT_TARGET_USER

--target-user

none

Target ACL style 'AUTH username pass'. Needs password.

RIOT_TARGET_PASS

--target-pass

none

Password to use when connecting to the target server.

RIOT_TARGET_TIMEOUT

--target-timeout

60s

Target Redis command timeout (e.g., 30s or 5m).

RIOT_TARGET_TLS

--target-tls

false

Establish a secure TLS connection to target.

RIOT_TARGET_INSECURE

--target-insecure

false

Allow insecure TLS connection to target by skipping cert validation.

RIOT_TARGET_TLS_VERIFY

--target-verify

FULL

Target TLS verify mode: FULL, CA, NONE.

RIOT_TARGET_CLIENT

--target-client

none

Client name used to connect to target Redis.

RIOT_TARGET_CLUSTER

--target-cluster

false

Enable target cluster mode.

RIOT_TARGET_RESP

--target-resp

Newest supported

Redis protocol version used to connect to target.

RIOT_TARGET_POOL

--target-pool

8

Max number of target Redis connections.

RIOT_TARGET_READ_FROM

--target-read-from

UPSTREAM

Which target Redis cluster nodes to read from.

TLS Connection

export RIOT_SOURCE_TLS=true
export RIOT_SOURCE_INSECURE=true
export RIOT_TARGET_TLS=true
export RIOT_TARGET_INSECURE=true

riotx replicate redis://secure-source:6380 redis://secure-target:6380

Observability

Variable CLI Option Default Description

RIOT_LOG

--log-level

WARN

Set log level: ERROR, WARN, INFO, DEBUG, or TRACE.

RIOT_PROGRESS

--progress

ASCII

Progress style: ASCII, BAR, BLOCK, or NONE.

RIOT_NO_COLOR

none

false

Disable colored output in the console.

RIOT_METRICS

--metrics

false

Enable metrics.

RIOT_METRICS_JVM

--metrics-jvm

true

Enable/disable JVM metrics.

RIOT_METRICS_REDIS

--metrics-redis

false

Enable command latency metrics.

RIOT_METRICS_PORT

--metrics-port

8080

Port that Prometheus HTTP server should listen on.

Usage Examples

Basic Redis Connection

export RIOT_REDIS_HOST=my-redis-server
export RIOT_REDIS_PORT=6380
export RIOT_REDIS_USER=myuser
export RIOT_REDIS_PASS=mypassword
export RIOT_REDIS_DB=1
export RIOT_REDIS_TLS=true

riotx ping

Basic Replication

export RIOT_SOURCE_USER=myuser
export RIOT_SOURCE_PASS=mypassword
export RIOT_TARGET_USER=targetuser
export RIOT_TARGET_PASS=targetpassword
export RIOT_THREADS=4
export RIOT_BATCH=100

riotx replicate redis://source:6379 redis://target:6379

High-Throughput Replication

export RIOT_SOURCE_USER=myuser
export RIOT_SOURCE_PASS=mypassword
export RIOT_TARGET_USER=targetuser
export RIOT_TARGET_PASS=targetpassword
export RIOT_SCAN_COUNT=2000
export RIOT_READ_BATCH=200
export RIOT_READ_THREADS=8
export RIOT_READ_QUEUE=50000
export RIOT_SOURCE_POOL=16
export RIOT_THREADS=8
export RIOT_BATCH=500

riotx replicate redis://source:6379 redis://target:6379

Import

export RIOT_THREADS=8
export RIOT_BATCH=500
export RIOT_FLUSH=10ms
export RIOT_RATE=10000
export RIOT_METRICS=true
export RIOT_PROGRESS=BAR

riotx file-import mydata.csv redis://localhost:6379

Snowflake Import

export RIOT_REDIS_HOST=redis
export RIOT_REDIS_PORT=12000
export RIOT_STREAM_LIMIT=100
export RIOT_ROLE=riotx_cdc
export RIOT_WAREHOUSE=compute_wh
export RIOT_CDC_SCHEMA=cdc_schema
export RIOT_JDBC_URL="jdbc:snowflake://company.snowflakecomputing.com?private_key_file=/path/to/key.p8"
export RIOT_JDBC_USER=username
export RIOT_JDBC_PASS=password
export RIOT_TABLE=db.schema.table

riotx snowflake-import

Docker

docker run --env-file riot.env riotx/riotx:latest replicate \
  redis://source:6379 redis://target:6379

Where riot.env contains:

RIOT_THREADS=4
RIOT_BATCH=100
RIOT_SOURCE_PASS=sourcepassword
RIOT_TARGET_PASS=targetpassword
RIOT_METRICS=true
RIOT_LOG=INFO

Notes

  • Environment variables take precedence over command-line defaults but are overridden by explicit command-line arguments.

  • Boolean values can be set to true or false.

  • Duration values support suffixes like s (seconds), m (minutes), h (hours).

  • Numeric values with suffixes like k (thousand) and m (million) are supported where applicable.

  • Sensitive values like passwords should be set via environment variables rather than command-line arguments for security.