readers

Readers

Readers provide an implementation of various message readers. The service exposes an HTTP API for querying messages that have been persisted by the Writers (consumers).

Implementations

Two backend implementations are provided, each as its own binary:

Message Formats

The service supports two message formats:

SenML — structured IoT measurement records with well-known fields (n, v, vb, vs, vd, t, u).

JSON — free-form JSON records, queried by arbitrary filter expressions.

Authentication

Requests are authenticated using the Thing key:

Authorization: Thing <thing_key>

The authenticated thing determines which messages are accessible.

Configuration

PostgreSQL Reader

The service is configured using the environment variables presented in the following table. Note that any unset variables will be replaced with their default values.

TimescaleDB Reader

Uses the same environment variable names with MF_TIMESCALE_READER_ prefix (except shared vars like MF_THINGS_AUTH_GRPC_URL).

Deployment

The service itself is distributed as Docker container. Check the postgres-reader service section in docker-compose to see how the service is deployed.

To start the PostgreSQL reader service, execute the following shell script:

# Download the latest version of the service
git clone https://github.com/MainfluxLabs/mainflux

cd mainflux

# compile the postgres-reader service
make postgres-reader

# Copy binary to bin
make install

# Set the environment variables and run the service
MF_POSTGRES_READER_LOG_LEVEL=[Log level] \
MF_POSTGRES_READER_PORT=[HTTP port] \
MF_POSTGRES_READER_DB_HOST=[Database host address] \
MF_POSTGRES_READER_DB_PORT=[Database host port] \
MF_POSTGRES_READER_DB_USER=[Database user] \
MF_POSTGRES_READER_DB_PASS=[Database password] \
MF_POSTGRES_READER_DB=[Database name] \
MF_THINGS_AUTH_GRPC_URL=[Things service Auth gRPC URL] \
$GOBIN/mainfluxlabs-postgres-reader

Usage

Starting the service exposes the HTTP API for querying persisted messages. Authentication is performed using the Thing key passed in the Authorization header.

For the full API reference, see the API documentation.

gRPC API

In addition to the HTTP API, the postgres-reader exposes a gRPC API that allows other internal services to query messages by thing key.

Environment Variables (postgres-reader)

Methods

• ListJSONMessages — returns a page of JSON messages filtered by thing key and page metadata
• ListSenMLMessages — returns a page of SenML messages filtered by thing key and page metadata

Authentication is done via thing key (no user token required).

Consuming Services

Services that query the postgres-reader gRPC API (e.g. rules) use the following environment variable to locate the endpoint: