Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1l2pzR-0001Dn-6m for pgsql-hackers@arkaria.postgresql.org; Fri, 22 Jan 2021 06:32:13 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1l2pzQ-0005Ob-2k for pgsql-hackers@arkaria.postgresql.org; Fri, 22 Jan 2021 06:32:12 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1l2pzP-0005OT-Kc for pgsql-hackers@lists.postgresql.org; Fri, 22 Jan 2021 06:32:11 +0000 Received: from mail-pf1-x42f.google.com ([2607:f8b0:4864:20::42f]) by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1l2pzN-0004Wj-6Q for pgsql-hackers@lists.postgresql.org; Fri, 22 Jan 2021 06:32:10 +0000 Received: by mail-pf1-x42f.google.com with SMTP id w14so3085649pfi.2 for ; Thu, 21 Jan 2021 22:32:08 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=leadboat.com; s=google; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=iC7Ei3Wy92RUW3rHe7/5Axvf+jME7kKnKkymee3GF9k=; b=GpDgem1PBowTPQFJGoh8a4fSlt8nxQLZ39IaIGen6oneMbc6PTpx3FKXHsOZq+REdA 21BiDoCrVvCh2ZWbWnil2dlhDWy7SnOQIz/5+WsVkrITfXvGSwkaNPaUjy4kZHXt/Xw6 noHTyPtzfpSbmo3H+pGZi53O9ZlKEuxa6t21g= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=iC7Ei3Wy92RUW3rHe7/5Axvf+jME7kKnKkymee3GF9k=; b=hWL8qEjT0UhLeufDApYZ6/LSJvtDoMsUILcJF5Ch7IqQ683ZlgRQwfOsiTg6x91Tjq gKROPZBmn7Ka/frwkpWS/lzBbd3TrQZpNrYwPq0/tLV57cG43H8uTqwk+3YoJhIBJoNW ax80FJ+EzqQu74XoYmwvun6mbrP6uQFS3YDkouk/h2IOeLw4xyAiAmAMh15cCBNsV3If HQvIA+dLxuEq3FOdASJ7+WStW34/gQUqrKpcd6Wi8BsnC7wEmXlmhfisXzsNHCkujEYw 6qZgncSE6izc8UvLNPHY8vh9cauzqUdX9sFA3Ey76Aq/Jy1EY15IUJdHpuGhp0W/loJ5 43WQ== X-Gm-Message-State: AOAM532GDhao+SeguIw4bJ2ml6It9zkO+FsDyFVMyhrRWXhezaLRHGm6 jXkzdT7VKq7BcniadKeeKf9d8w7sCWmbkp+K X-Google-Smtp-Source: ABdhPJy3uWbqmRQ4AFATZy1gTPvKYz553nXlH6aPkppKAj4xyudepUHI2k2boMEBplB8Yej0iqRZkA== X-Received: by 2002:a17:90a:808a:: with SMTP id c10mr3538298pjn.229.1611297126773; Thu, 21 Jan 2021 22:32:06 -0800 (PST) Received: from rfd.leadboat.com ([2600:1702:a20:5750::46]) by smtp.gmail.com with ESMTPSA id e63sm7660462pfe.216.2021.01.21.22.32.05 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 21 Jan 2021 22:32:05 -0800 (PST) Date: Thu, 21 Jan 2021 22:32:03 -0800 From: Noah Misch To: Tom Lane Cc: pgsql-hackers@lists.postgresql.org Subject: Re: Very misleading documentation for PQreset() Message-ID: <20210122063203.GA2108099@rfd.leadboat.com> References: <1095901.1611268376@sss.pgh.pa.us> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1095901.1611268376@sss.pgh.pa.us> User-Agent: Mutt/1.5.24 (2015-08-30) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk On Thu, Jan 21, 2021 at 05:32:56PM -0500, Tom Lane wrote: > I happened to notice that PQreset is documented thus: > > This function will close the connection to the server and attempt to > reestablish a new connection to the same server, using all the same > parameters previously used. > > Since we invented multi-host connection parameters, a reasonable person > would assume that "to the same server" means we promise to reconnect to > the same host we selected the first time. There is no such guarantee > though; the new connection attempt is done just like the first one, > so it will select the first suitable server in the list. > > I think we should just drop that phrase. I agree that dropping the phrase strictly improves that documentation.