Admin API Database Configuration

Overview

This document describes the configuration properties for the Admin API's primary database connection. These properties are prefixed with s2r.db and allow an operator to control how the Admin API connects to its PostgreSQL database, which is used for functions such as serving dashboard aggregations.

Configuration covers several key areas:

• Authentication: Supports both IAM-based and traditional username/password authentication.
• Connection Details: Standard host, port, and database name settings.
• Connection Pooling: Parameters to manage the size and behavior of the database connection pool.
• Timeouts: Low-level socket and connection timeouts to ensure resilience against database unresponsiveness.
• SSL: Configuration for securing the database connection.

These settings are loaded by the Admin API at startup and are critical for establishing and maintaining a stable connection to the application's database.

How It Works

The Admin API uses a connection pool to efficiently manage database connections. The properties defined here configure that pool and the underlying JDBC driver.

Authentication

The s2r.db.authMode property determines the authentication strategy.

flowchart TD
    A[Admin API Starts] --> B{Read `s2r.db.authMode`};
    B -- "iam" (default) --> C[IAM Authentication];
    C --> C1["Uses Cloud SQL Connector with<br/>`instanceConnectionName`"];
    B -- other --> D[Password Authentication];
    D --> D1["Uses standard JDBC driver with<br/>`host`, `user`, `password`"];
    C1 --> E[Connection Pool Initialized];
    D1 --> E;

• IAM Authentication (iam): This is the default mode. It uses the Cloud SQL Java connector for authentication. This method requires the s2r.db.instanceConnectionName property to be set. An IAM token is automatically managed and refreshed based on the s2r.db.iamTokenRefreshSeconds setting.
• Password Authentication: When authMode is set to a value other than iam, the system uses standard username and password authentication. This requires the s2r.db.host, s2r.db.user, and s2r.db.password properties.

Connection Pools and Timeouts

The Admin API maintains a connection pool for application queries, such as those that populate dashboards. The size and timeout behavior of this pool are configured by properties like maxPoolSize, connectionTimeoutMs, and socketTimeoutSeconds.

The socketTimeoutSeconds and connectTimeoutSeconds are particularly important for operational resilience, as they prevent the application from hanging indefinitely if the database becomes unresponsive at the network level. The default socket timeout for the Admin API is higher than for other services to accommodate slower dashboard aggregation queries.

Configuration Example

The following example shows a typical configuration for connecting to a database using IAM authentication. These properties would be set in the Admin API's configuration file.

s2r:
  db:
    authMode: "iam"
    instanceConnectionName: "<project>:<region>:<instance>"
    ipType: "PRIVATE"
    name: "soap_to_rest"
    maxPoolSize: 24
    socketTimeoutSeconds: 60

Configuration Properties

All properties are prefixed with s2r.db.

Troubleshooting

Connection Failures at Startup

The Admin API will fail to start if the database configuration is invalid. Common causes include:

• authMode is set to iam, but instanceConnectionName is not provided.
• authMode is not iam, but host, user, or password are missing.
• The database is unreachable from the Admin API due to network policies, firewalls, or incorrect host or instanceConnectionName values.

Slow Queries or Timeouts

The socketTimeoutSeconds is set to 60 seconds by default to accommodate potentially slow dashboard aggregation queries. If queries are consistently timing out, it may indicate a performance issue with the database itself. Increasing this timeout should be done with caution, as it can increase the time the application waits for a non-responsive database.

All SOAP-to-REST docs