Runtime Database Connection Configuration

Overview

This document describes the configuration properties for the runtime service's internal database connection. These properties, prefixed with s2r.db, control how the service connects to its PostgreSQL database, which it uses for its operational data, such as mapping SOAP requests to REST backends.

The configuration supports two primary authentication and connection methods:

1. IAM Authentication: The default method, designed for use with managed cloud database services. It uses instance connection strings and automatically refreshed IAM tokens.
2. Username/Password Authentication: A standard method using a hostname, port, username, and password for direct database connections.

Proper configuration is critical for service startup and resilience, especially the socket timeout settings, which prevent connection pool exhaustion during network partitions.

How it Works

The runtime service reads properties under the s2r.db prefix at startup to configure its database connection pool. The s2r.db.authMode property determines the connection strategy.

The diagram below illustrates the two main connection paths based on the configured authentication mode.

flowchart TD
    subgraph "Runtime Service Startup"
        direction TB
        A(Read s2r.db.* properties) --> B{authMode == "iam"?};
    end

    subgraph "IAM Authentication Path"
        direction TB
        C(Connect via Cloud SQL Connector)
        D(Use `instanceConnectionName` and `ipType`)
        E(Refresh token every `iamTokenRefreshSeconds`)
    end

    subgraph "Username/Password Path"
        direction TB
        F(Connect via standard JDBC)
        G(Use `host`, `port`, `user`, and `password`)
    end

    B -- Yes --> C --> D --> E;
    B -- No --> F --> G;

• If authMode is set to iam (the default), the service uses a dedicated Cloud SQL Java connector. It relies on the instanceConnectionName to identify the target database instance and authenticates using IAM. An authentication token is automatically managed and refreshed at the interval specified by iamTokenRefreshSeconds.

• If authMode is set to any other value, the service attempts a direct connection using the standard host, port, user, and password properties.

In both modes, socket-level timeouts (socketTimeoutSeconds and connectTimeoutSeconds) are applied to ensure that connections do not hang indefinitely during network instability, which is crucial for maintaining the health of the connection pool.

Configuration Reference

All properties are prefixed with s2r.db. For example, to set the host, the full property key is s2r.db.host.

Troubleshooting

Connection Pool Exhaustion During Network Partitions

Condition: The runtime service becomes unresponsive, and logs indicate an inability to acquire a database connection from the pool, even after network connectivity to the database has been restored.

Cause: If a network partition occurs between the runtime service and the database, active connections in the pool can get stuck waiting for a response on a dead socket. Without a socket timeout, these connections will never be terminated and returned to the pool. The connection pool will eventually be exhausted as all connections become permanently "borrowed" and unusable.

Solution: Configure the s2r.db.socketTimeoutSeconds property. This sets a timeout on socket-level read operations. If the database does not respond within this period, the driver will throw an exception, which terminates the dead connection and allows the connection pool to reclaim it. This ensures the pool can recover automatically once network connectivity is restored.

All SOAP-to-REST docs