feat: savepoints

[olavloite]

Adds support for savepoints to the Connection API. This will be surfaced to users through the JDBC driver and PGAdapter.

Savepoints use the internal retry mechanism for read/write transactions to emulate actual savepoints:

• Setting a savepoint is supported in both read/write and read-only transactions. Savepoints in a read-only transaction are no-ops and are guaranteed to always work. They are supported purely for compatibility reasons. That is; if a framework automatically uses savepoints, this feature ensures that the framework does not fail if it uses savepoints in combination with a read-only transaction.
• Releasing a savepoint removes it from the transaction. This is an in-mem operation only that is guaranteed to always work, assuming that the application uses an existing savepoint name.
• Rolling back to a savepoint is supported for both read-only and read/write transactions. For read-only transactions it is a no-op and is guaranteed to always work. Rolling back to a savepoint in a read/write transaction is also always guaranteed to work. However, resuming the transaction after rolling back to a savepoint in a read/write transaction can fail if the underlying data has been modified, or if one or more of the statements before the savepoint that was rolled back to returns non-deterministic data. Note that rolling back to a savepoint does not remove the savepoint from the transaction. It is therefore possible to roll back to the same savepoint multiple times.

[thiagotnunes]

I imagine you already picked the best data structure here, but wondering if you considered any other like Deque for stack like popping or a TreeMap for fast retrieval of elements.

[olavloite]

I considered a couple of different options, but landed on LinkedList both for simplicity, but also because it aligns with how SAVEPOINT works. They are strictly ordered by an index (i.e. a map structure makes less sense, as there is no mapping between a key and a value other than a simple index key), and removing a savepoint from the list always means removing everything after it as well. That means that cutting one node in the middle of the list is a cheap operation.
That being said; a transaction is unlikely to ever have more than a handful of savepoints, meaning that the chosen data structure won't have any practical effect on the performance.

• Deque was indeed one that I considered, but I dropped it as we need to be able to peek multiple steps back, which is not supported by a pure Deque implementation.
• TreeMap or similar would not really be a good fit, as the key in this case is just an index. The savepoint names also do not need to be unique (in PostgreSQL).

[thiagotnunes]

I think you mean internal locks, as we don't allow for "SQL" locks in Cloud Spanner?

[olavloite]

Added

[thiagotnunes]

What happens if I commit after a rollbackToSavepoint? (I assume it would potentially work with the statements up to the given savepoint, if nothing has changed, but just verifying my understanding)

[olavloite]

Your understanding is correct. The idea is that a savepoint will allow you to reset the transaction to a valid point and then either continue or commit, instead of having to abort the entire transaction.

[thiagotnunes]

Nice test

[olavloite]

Thanks :-)

[gcf-merge-on-green]

Merge-on-green attempted to merge your PR for 6 hours, but it was not mergeable because either one of your required status checks failed, one of your required reviews was not approved, or there is a do not merge label. Learn more about your required status checks here: https://help.github.com/en/github/administering-a-repository/enabling-required-status-checks. You can remove and reapply the label to re-run the bot.