Improve docs and tests

conn_test.go

@@ -584,6 +584,33 @@ func TestDeallocateInAbortedTransaction(t *testing.T) {
 	})
 }
 
+func TestDeallocateMissingPreparedStatementStillClearsFromPreparedStatementMap(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+
+	pgxtest.RunWithQueryExecModes(ctx, t, defaultConnTestRunner, nil, func(ctx context.Context, t testing.TB, conn *pgx.Conn) {
+		_, err := conn.Prepare(ctx, "ps", "select $1::text")
+		require.NoError(t, err)
+
+		_, err = conn.Exec(ctx, "deallocate ps")
+		require.NoError(t, err)
+
+		err = conn.Deallocate(ctx, "ps")
+		require.NoError(t, err)
+
+		_, err = conn.Prepare(ctx, "ps", "select $1::text, $2::text")
+		require.NoError(t, err)
+
+		var s1, s2 string
+		err = conn.QueryRow(ctx, "ps", "hello", "world").Scan(&s1, &s2)
+		require.NoError(t, err)
+		require.Equal(t, "hello", s1)
+		require.Equal(t, "world", s2)
+	})
+}
+
 func TestListenNotify(t *testing.T) {
 	t.Parallel()
 

pgconn/pgconn.go

@@ -875,7 +875,9 @@ readloop:
 // Deallocate deallocates a prepared statement.
 //
 // Deallocate does not send a DEALLOCATE statement to the server. It uses the PostgreSQL Close protocol message
-// directly. This has the implication that Deallocate can succeed in an aborted transaction.
+// directly. This has slightly different behavior than executing DEALLOCATE statement.
+//   - Deallocate can succeed in an aborted transaction.
+//   - Deallocating a non-existent prepared statement is not an error.
 func (pgConn *PgConn) Deallocate(ctx context.Context, name string) error {
 	if err := pgConn.lock(); err != nil {
 		return err

pgconn/pgconn_test.go

@@ -728,6 +728,22 @@ func TestConnDeallocateSucceedsInAbortedTransaction(t *testing.T) {
 	ensureConnValid(t, pgConn)
 }
 
+func TestConnDeallocateNonExistantStatementSucceeds(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+
+	pgConn, err := pgconn.Connect(ctx, os.Getenv("PGX_TEST_DATABASE"))
+	require.NoError(t, err)
+	defer closeConn(t, pgConn)
+
+	err = pgConn.Deallocate(ctx, "ps1")
+	require.NoError(t, err)
+
+	ensureConnValid(t, pgConn)
+}
+
 func TestConnExec(t *testing.T) {
 	t.Parallel()