Diagram db query strategies, include these diagrams in the requirements

[michaelhixson]

The requirements for what database query strategies are allowed and disallowed is currently confusing. For example, we say "pipelining" is permitted but we don't explain what pipelining is. There are long discussions about this in our mailing list, but those were not effective. After those discussions, I had to reject a couple of PRs that were doing batch queries instead of pipelining.

Clarify the requirements by providing diagrams, created with draw.io for example. They should show what each query strategy is and whether it's allowed.

Known strategies include:

• Sequential queries, as in many Java frameworks that use JDBC. Allowed.
• Concurrent queries (one per connection), as in many JavaScript frameworks. Allowed.
• Pipelined queries (many per connection), as in reactive-pg-client. Allowed.
• SELECT * FROM world WHERE id IN (...). Disallowed.
• Batch queries. Disallowed.

[zloster]

You could give a try to PlantUML. My quick attempt:

@startuml
title The Java and JDBC flow
autonumber
"Application thread" -> "DB connection": SQL query A
"DB connection" -> "Application thread": SQL resultset A
"Application thread" -> "DB connection": SQL query B
"DB connection" -> "Application thread": SQL resultset B
@enduml

The result is: or as ASCII art:

     ┌──────────────────┐          ┌─────────────┐
     │Application thread│          │DB connection│
     └────────┬─────────┘          └──────┬──────┘
              │       1 SQL query A       │       
              │ ─────────────────────────>│       
              │                           │       
              │     2 SQL resultset A     │       
              │ <─────────────────────────│       
              │                           │       
              │       3 SQL query B       │       
              │ ─────────────────────────>│       
              │                           │       
              │     4 SQL resultset B     │       
              │ <─────────────────────────│       
     ┌────────┴─────────┐          ┌──────┴──────┐
     │Application thread│          │DB connection│
     └──────────────────┘          └─────────────┘

Note: the title is missing from the ASCII art. Probably this is a bug.