postgres connection not working

[korncola]

Expected Behavior

1. better documentation of temporal-server.yaml
2. clear error why connection to postgres is not working
3. postgres connection working

Actual Behavior

1. not clear what i have to configure to make postgres work, no example, just a terse autogenerated reference
2. no clear error, just:

[Fx] Error returned: received non-nil error from function "go.temporal.io/server/temporal".ServerOptionsProvider
	/home/runner/work/temporal/temporal/temporal/fx.go:159:
sql schema version compatibility check failed: unable to read DB schema version keyspace/database: temporal error: no usable database connection found

Steps to Reproduce the Problem

• temporal standalone binaries deployed to Amazon Linux 2023
• database set up with temporal-sql-tool according to docu
• even tried root credentials of database
• triple checked db params
• verified with

temporal_visibility=> SELECT * FrOM schema_version;
 version_partition |       db_name       |       creation_time        | curr_version | min_compatible_version 
-------------------+---------------------+----------------------------+--------------+------------------------
                 0 | temporal_visibility | 2025-08-19 14:36:05.240912 | 1.9          | 0.1
(1 row)

temporal_visibility=> \c temporal
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: postgresql)
You are now connected to database "temporal" as user "root".
temporal=> SELECT * FrOM schema_version;
 version_partition | db_name  |       creation_time       | curr_version | min_compatible_version 
-------------------+----------+---------------------------+--------------+------------------------
                 0 | temporal | 2025-08-19 14:35:16.29214 | 1.17         | 1.0

• temporal-server.yaml

log:
  stdout: true
  level: debug

persistence:
  defaultStore: default
  visibilityStore: default-visibility
  numHistoryShards: 4
  datastores:
    default:
      sql:
        pluginName: "postgres12"
        databaseName: "temporal"
        connectAddr: "temporal-db.example.com:5432"
        connectProtocol: "tcp"
        user: "temporal"
        password: "redacted"
        connectAttributes:
          cache: "private"
          setup: true
        tls:
          enabled: true
          enableHostVerification: false

    default-visibility:
      sql:
        pluginName: "postgres12"
        databaseName: "temporal_visibility"
        connectAddr: "temporal-db.example.com:5432"
        connectProtocol: "tcp"
        user: "temporal"
        password: "redacted"
        connectAttributes:
          cache: "private"
          setup: true
        tls:
          enabled: true
          enableHostVerification: false

global:
  membership:
    maxJoinDuration: 30s
    broadcastAddress: "127.0.0.1"
  pprof:
    port: 7936

services:
  frontend:
    rpc:
      grpcPort: 7233
      membershipPort: 6933
      bindOnIP: '0.0.0.0'
      httpPort: 7243

  matching:
    rpc:
      grpcPort: 7235
      membershipPort: 6935
      bindOnLocalHost: true

  history:
    rpc:
      grpcPort: 7234
      membershipPort: 6934
      bindOnLocalHost: true

  worker:
    rpc:
      membershipPort: 6939

clusterMetadata:
  enableGlobalNamespace: false
  failoverVersionIncrement: 10
  masterClusterName: "active"
  currentClusterName: "active"
  clusterInformation:
    active:
      enabled: true
      initialFailoverVersion: 1
      rpcName: "frontend"
      rpcAddress: "localhost:7233"
      httpAddress: "localhost:7243"

dcRedirectionPolicy:
  policy: "noop"

Specifications

• Version: 1.28.1
• Platform: Linux

[korncola]

one example why the reference docu is bad:
connectAddr - required - the remote address of the database, e.g. "192.168.1.2".

But in https://github.com/temporalio/temporal/blob/main/docker/config_template.yaml#L124
it seems to be host:port
Discovered this cause I searched in my error debugging for a parameter to explicitly set the port

[korncola]

the problem was the part

       connectAttributes:
          cache: "private"
          setup: true

from binary setup tutorial which is not explained at all in config reference

After removing that it worked.
Also the binary setup torial is not consistent in naming of configs and binaries, the systemd units have different config and binary names than stated what config to create (ui-server.yaml vs. temporal-ui-server.yaml) and how is the binary is named in tar.gz (ui-server vs temporal-ui-server).
Am I the only one reading the docu, and tying to deploy this by hand before running k8s? :-)

So please make documentation of server config being a real reference, and the infra tutorials consistent.
Besides that, great product 👍

[bergundy]

Am I the only one reading the docu, and tying to deploy this by hand before running k8s? :-)

I imagine that users are using our https://github.com/temporalio/helm-charts to deploy typically.

I will transfer this issue to the documentation repo to be handled there.
Feel free to open a PR and fix the docs.
Thanks for reporting!