release-22.1: server: new HTTP API to execute SQL statements

[dhartunian]

Backport 2/2 commits from #79663 and #84386.

/cc @cockroachdb/release

---

Requested by @andreimatei .

This commit introduces a new API endpoint /api/v2/sql/,
which can execute arbitrary SQL statements over HTTP.

The endpoint is authenticated, i.e. the client must provide
an appropriate X-Cockroach-API-Session: header on each request.

There is a Swagger spec to enable auto-documentation of the API.

The request payload should be submitted using JSON.

Summary of request fields:

• database: the current database, defaults to defaultdb
• application_name
• timeout: max execution time, defaults to 5s
• max_results_size: max size of results, defaults to ~10KB.
• statements: which statements to run. An array of {"sql",
  "arguments"} objects. The number of items in "arguments"
  must match the number of placehoders in "sql".
• execute: must be set to true to actually execute the SQL.
  Otherwise, the request is merely parsed to verify the syntax is correct.

Example use:

1. Generate some test data and create a user with access to it:

   $ cockroach gen example-data intro | cockroach sql --certs-dir=...
   $ cockroach sql --certs-dir=... \
       -e 'create user myuser with password abc'
       -e 'grant select on table intro.mytable to myuser'
   

2. Generate an HTTP API key, for example using the CLI (an HTTP
   request to /api/v2/login is also possible):

   $ cockroach session-auth login myuser  --certs-dir=certs
   

   (this prints out the session key, assign it manually to the $APIKEY env var.)

3. Run some HTTP API queries from the shell using curl. For example:

   $ curl -k -H "X-Cockroach-API-Session: $APIKEY" \
       -H "Content-Type: application/json" \
       --data-binary '{"database":"intro",
       "statements":[{"sql":"SELECT v FROM mytable WHERE l%2 = 0"}],
       "execute": true}' \
       https://127.0.0.1:8080/api/v2/sql/
   

Example output:

{"num_statements": 1,
 "execution": {
   "retries":0,
   "txn_results": [
{
  "statement": 1,
  "tag": "SELECT",
  "start":"2022-04-08T15:55:30.659257101Z",
  "columns": [{"name":"v", "type":"STRING", "oid":25}],
  "rows": [
   {"v":"..."},
   {"v":"..."},
   {"v":"..."}
  ],
  "end":"2022-04-08T15:55:30.665283699Z"
}
  ]
}}

This currently executes using the "internal executor" and thus
does not support SQL sessions and transaction control. Some consequences:

• SET statements are ineffective.
• BEGIN/COMMIT/ABORT/SAVEPOINT etc are ineffective.

Security note: We place this logic under /api/v2 and not
/_admin/v1 because the latter uses session cookies and is thus
susceptible to CSRF.
The /api/v2 tree requires an explicit header and thus blocks CSRF.

Release note (api change): A new /api/v2/sql/ endpoints enable
execution of simple SQL queries over HTTP.

---

Fixes #84385.

Release note (bug fix): The SQL execution HTTP endpoint did not
properly support queries with multiple result values. This is now
fixed. This bug was introduced when the feature was first implemented.

---

Release justification: this is a high-priority need for SQL Observability and makes it easier to port over functionality in DB Console. Furthermore, this endpoint is purely additive and can only be opted into by new frontend code.

[blathers-crl]

Thanks for opening a backport.

Please check the backport criteria before merging:

• Patches should only be created for serious issues or test-only changes.
• Patches should not break backwards-compatibility.
• Patches should change as little code as possible.
• Patches should not change on-disk formats or node communication protocols.
• Patches should not add new functionality.
• Patches must not add, edit, or otherwise modify cluster versions; or add version gates.

If some of the basic criteria cannot be satisfied, ensure that the exceptional criteria are satisfied within.

• There is a high priority need for the functionality that cannot wait until the next release and is difficult to address in another way.
• The new functionality is additive-only and only runs for clusters which have specifically “opted in” to it (e.g. by a cluster setting).
• New code is protected by a conditional check that is trivial to verify and ensures that it only runs for opt-in clusters.
• The PM and TL on the team that owns the changed code have signed off that the change obeys the above rules.

Add a brief release justification to the body of your PR to justify this backport.

Some other things to consider:

• What did we do to ensure that a user that doesn’t know & care about this backport, has no idea that it happened?
• Will this work in a cluster of mixed patch versions? Did we test that?
• If a user upgrades a patch version, uses this feature, and then downgrades, what happens?

[cockroach-teamcity]

This change is 

[knz]

👍 but don't you need to wrap up the convo around authn before this merges?

[knz]

you'll need to backport #84386 too.

[maryliag]

As long as tests are passing and the necessary other PRs are also backported:

Reviewable status: complete! 1 of 0 LGTMs obtained (waiting on @abarganier and @xinhaoz)

[dhartunian]

Auth code backport will be merged right after this one: #85553

[dhartunian]

I added @knz's bugfix PR (#84386) into this backport as well.