Connections

Connections are named, typed configuration objects that store external system details (database credentials, API endpoints, etc.). They live in workspace YAML and are resolved automatically when used as task inputs.

Connection Types

Define reusable schemas for connections using connection_types. Each property has a type, and can be marked as required, have a default value, or be flagged as secret.

connection_types:
  postgres:
    host:
      type: string
      required: true
    port:
      type: integer
      default: 5432
    database:
      type: string
      required: true
    user:
      type: string
      required: true
    password:
      type: string
      required: true
      secret: true

Supported property types: string, text, integer, number, boolean, date, datetime.

Connections

Define named connection instances under connections. The type field references a connection type; all other fields are values.

connections:
  prod_db:
    type: postgres
    host: "db.example.com"
    port: 5432
    database: "myapp"
    user: "admin"
    password: "{{ 'ref+awsssm:///prod/db/password' | vals }}"

  staging_db:
    type: postgres
    host: "staging-db.internal"
    database: "myapp_staging"
    user: "app"
    password: "{{ 'ref+awsssm:///staging/db/password' | vals }}"

Connection values support Tera templates (e.g., {{ 'ref+...' | vals }} for secret resolution). Default values from the connection type are applied automatically for missing fields — in this example, staging_db.port will default to 5432.

Sharing a connection across workspaces

By default a connection is only usable within its own workspace. Set shared: true to allow other workspaces to reference it by qualified name (workspace.connection-name):

connections:
  clickhouse-prod:
    type: clickhouse
    shared: true
    host: ch.internal
    password: "{{ secret.ch_password }}"

A reference to an unshared connection from another workspace is rejected with 400 Bad Request at job creation for literal references; a templated flow-step value that resolves to an unshared connection is instead resolved at claim time and fails that step. See Cross-Workspace References for the full rules, including the claim-time case and how connection types are matched across workspaces.

Untyped Connections

Connections without a type field are also valid. Untyped connections skip type validation entirely and can be used for any connection-type input field:

connections:
  custom_api:
    url: "https://api.example.com"
    token: "abc123"

Using Connections as Task Inputs

When a task input field’s type matches a connection type name, the system treats it as a connection reference. At job creation time, the connection name string is automatically resolved to the full connection object.

actions:
  run-migration:
    type: script
    script: "migrate --host {{ input.db.host }} --port {{ input.db.port }} --db {{ input.db.database }}"
    input:
      db:
        type: postgres        # Expects a resolved connection object

tasks:
  deploy:
    input:
      db:
        type: postgres        # References the connection type
      env:
        type: string           # Normal input
    flow:
      migrate:
        action: run-migration
        input:
          db: "{{ input.db }}"

When triggering the task, pass the connection name as the input value:

{ "db": "prod_db", "env": "production" }

The system resolves "prod_db" to { "host": "db.example.com", "port": 5432, "database": "myapp", ... }, making the full connection object available in templates as {{ input.db.host }}, {{ input.db.port }}, etc.

In the web UI, connection-type inputs render as a searchable dropdown listing all connections of that type in the workspace — no manual typing required.

When a connection type comes from a library, use the full namespaced name: type: common.postgres (where common is the library name).

Cross-workspace

A connection-type input’s type: and the connection name it resolves may each independently belong to another workspace (type: jobs.clickhouse, default: jobs.clickhouse-prod) — the type and the connection don’t need to live in the same workspace. A foreign connection resolves only if its owner marked it shared: true. See Cross-Workspace References → Connections for the addressing rules, the shared gate, and redaction.

Resolution Flow

Task-level (at job creation):

1. merge_defaults() runs as normal (fills missing fields, applies defaults)
2. resolve_connection_inputs() scans each task input field:
   • If the field type is a connection type (not string/text/integer/number/boolean), the provided string value is looked up in workspace connections
   • The string is replaced with the connection’s values object
3. The resolved input is stored in the job — available in all templates

Action-level (at step execution): Connection inputs on individual actions within a task are resolved when the step is about to execute, during the claim and render phase.

Direct Object Pass-Through

Instead of passing a connection name string, you can pass a connection object directly:

{ "db": { "host": "localhost", "port": 5432, "database": "test" } }

When an object is passed instead of a string, the resolution lookup is skipped and the object is used as-is.

Validation

At YAML parse time (stroem validate):

• Connection type property types must be string, text, integer, number, or boolean
• Typed connections must reference an existing connection_type
• Required fields without defaults must be present in the connection
• Unknown fields produce warnings
• Empty string values produce errors
• Task input fields with non-primitive types must reference a known connection type
• A dotted (qualified) type reference, such as type: jobs.clickhouse, is not resolved offline — stroem validate emits a warning and defers the check to job creation, where the server can see every workspace