jackc/pgx · error

read only connection

Error message

read only connection

What it means

Target-session-attrs validation error: the candidate connection was checked with 'show transaction_read_only' and reported 'on', but target_session_attrs=read-write requires a writable primary. The connection fails validation and pgx tries the next host (or fails if none remain).

Solutions

1. Point the connection string at a primary/writable server
2. Drop the target_session_attrs=read-write requirement if a standby is acceptable

When it happens

Trigger: Thrown at pgconn/config.go:1044 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jackc/pgx@ec1a0befd2 (2026-08-04). Data as JSON: /api/errors/8328e872bda375d1. Report an issue: GitHub.

Appendix: source

Thrown at pgconn/config.go:1044

	return time.Duration(timeout) * time.Second, nil
}

func makeConnectTimeoutDialFunc(timeout time.Duration) DialFunc {
	d := makeDefaultDialer()
	d.Timeout = timeout
	return d.DialContext
}

// ValidateConnectTargetSessionAttrsReadWrite is a ValidateConnectFunc that implements libpq compatible
// target_session_attrs=read-write.
func ValidateConnectTargetSessionAttrsReadWrite(ctx context.Context, pgConn *PgConn) error {
	result, err := pgConn.Exec(ctx, "show transaction_read_only").ReadAll()
	if err != nil {
		return err
	}

	if string(result[0].Rows[0][0]) == "on" {
		return errors.New("read only connection")
	}

	return nil
}

// ValidateConnectTargetSessionAttrsReadOnly is a ValidateConnectFunc that implements libpq compatible
// target_session_attrs=read-only.
func ValidateConnectTargetSessionAttrsReadOnly(ctx context.Context, pgConn *PgConn) error {
	result, err := pgConn.Exec(ctx, "show transaction_read_only").ReadAll()
	if err != nil {
		return err
	}

	if string(result[0].Rows[0][0]) != "on" {
		return errors.New("connection is not read only")
	}

	return nil

View on GitHub (pinned to ec1a0befd2)