docs: improve documentation and tests for server-side prepared statements

[vlsi]

Just in case: I have added with x as (insert into rollbacktest(a, str) values(43, 'abc') returning ${cols}) select * from x test case, and it does work "as expected".

That is it might produce cached plan... error in case it is using returning *. When that happens, pgjdbc could auto re-execute the statement (e.g. if no transaction was present) and it does overcome the error automatically.

The PR depends on #1137

[codecov-io]

Codecov Report

Merging #1135 into master will increase coverage by 0.08%.
The diff coverage is n/a.

@@             Coverage Diff              @@
##             master    #1135      +/-   ##
============================================
+ Coverage     67.25%   67.34%   +0.08%     
- Complexity     3673     3684      +11     
============================================
  Files           170      170              
  Lines         15640    15638       -2     
  Branches       2531     2531              
============================================
+ Hits          10519    10531      +12     
+ Misses         3932     3922      -10     
+ Partials       1189     1185       -4

[davecramer]

there are actually a number of plans that are created, not just one. I would have to find the details, but there is some concept of different plans for different values

[vlsi]

The implementation is https://github.com/postgres/postgres/blob/9d4649ca49416111aee2c84b7e4441a0b7aa2fac/src/backend/utils/cache/plancache.c#L1034-L1057, however I was unsure if I should modify (update) this comment.

[davecramer]

Here are the change notes from 9.2:

Prepared statements used to be optimized once, without any knowledge of the parameters' values. With 9.2, the planner will use specific plans regarding to the parameters sent (the query will be planned at execution), except if the query is executed several times and the planner decides that the generic plan is not too much more expensive than the specific plans.

Which conflicts with the comment above.

[vlsi]

Ok, this summary sounds good.

[davecramer]

enables "the" reuse of

[davecramer]

I would say replace ", and it..." with "; the parameters and results are much faster to parse"

[bokken]

I think you want instanceof Integer here.

[bokken]

The additional doc is great.

[davecramer]

Should be "Even though reuse of the same PreparedStatement object is good"
That being said I'm still unsure what this statement is trying to convey ?

[vlsi]

The idea is to highlight the difference between

PreparedStatement st = con.prepare("...");
ps.executeQuery();
..
// later in code
ps.executeQuery();
...

// later in code
ps.executeQuery();

vs

PreparedStatement st = con.prepare("...");
ps.executeQuery();
ps.close()
..
// later in code
PreparedStatement st = con.prepare("...");
ps.executeQuery();
ps.close()
...

// later in code
PreparedStatement st = con.prepare("...");
ps.executeQuery();
ps.close()

Certain JDBC drivers require to use exactly the same PreparedStatement object in order to use server-prepared statements.

[davecramer]

Seems this detailed explanation might be appropriate

[davecramer]

I think "on the client and the server" sounds better

[davecramer]

that is the client side cache

[davecramer]

"balancer that is incompatible with"

[davecramer]

DDL ?

[davecramer]

I personally prefer UK spelling of "behaviour"

[davecramer]

"could cause the whole transaction to fail"

[davecramer]

is not s/b has not

[davecramer]

This makes the application

[davecramer]

in the case where replications

[davecramer]

so be careful how you use it ?

[davecramer]

don't ever use this in production

[davecramer]

Sorry one more DLL

[davecramer]

+1