Worker Database Connection Configuration

Overview

The worker component requires a persistent database connection to perform its tasks, which include running batch rollups and replay drains. This document describes the configuration properties, prefixed with s2r.db, that control how the worker connects to and authenticates with its database.

These settings allow you to define the database endpoint, credentials, authentication method, and network resilience parameters like timeouts and SSL mode. Proper configuration is essential for the worker's stability and ability to complete long-running background jobs.

How it Works

The worker's database connection is established at startup based on the provided s2r.db properties. The primary configuration choice is the authentication method, controlled by the s2r.db.authMode property.

Authentication Modes

The system supports two primary modes for database authentication:

1. IAM Authentication (authMode: "iam"): This is the default mode. The worker uses Identity and Access Management (IAM) credentials to authenticate. This mode is often used with managed cloud database services.

   • When connecting to certain managed cloud databases that use a Java connector, the s2r.db.instanceConnectionName property should be set. This directs the driver to use a specific connection path.
   • The s2r.db.iamTokenRefreshSeconds property controls the lifetime of the temporary IAM authentication token.

2. Username/Password Authentication: By setting authMode to a value other than iam, you can configure the worker to use traditional database credentials.

   • In this mode, s2r.db.user and s2r.db.password must be provided.
   • The connection is made directly to the endpoint specified by s2r.db.host and s2r.db.port.

The following diagram illustrates the authentication flow:

flowchart TD
    subgraph "Worker Database Authentication"
        A(Worker starts) --> B{Read s2r.db.authMode};
        B -- "iam" --> C[IAM Authentication];
        B -- "other" --> D[Username/Password Authentication];
        C --> E["Connect using IAM credentials.<br/>If instanceConnectionName is set,<br/>uses a specific cloud database connector."];
        D --> F[Connect using s2r.db.user and s2r.db.password];
        E --> G([Database Connection]);
        F --> G;
    end

Timeouts and Resilience

The worker is designed to handle long-running batch processes that can be significantly slower than typical API request queries. The timeout settings are configured to accommodate these workloads and improve resilience against network instability.

• socketTimeoutSeconds: This timeout is set to a high value by default (120 seconds) to prevent premature termination of slow batch statements, such as data rollups or replay drains. It must be configured to exceed the duration of the slowest expected database query.
• connectTimeoutSeconds: This timeout governs the initial connection attempt to the database. It is based on a default value from the platform's socket resilience library, designed to handle transient network outages during startup.

Configuration Reference

All properties are prefixed with s2r.db. For example, to set the host, the full property name would be s2r.db.host.

Troubleshooting

Long-Running Jobs Fail with Timeout

The worker executes potentially slow batch operations like data rollups and replays. If these jobs fail, check the logs for timeout errors.

Cause: The s2r.db.socketTimeoutSeconds value may be too low for the duration of the database queries being executed.

Solution: Profile your slowest batch queries and set s2r.db.socketTimeoutSeconds to a value greater than the longest expected query time. The default is 120 seconds.

All SOAP-to-REST docs