public final class Database

Synchronized, like the two below, because a shared session is not safe to interleave – and for the network engines it is worse than interleaved transactions.

Postgres and MySql each own a Wire, and a Wire owns ONE 16KB buffer with a position and a limit, plus one output stream it builds every message in. MySql also carries the packet sequence number. Two handlers calling at once therefore write into the same message buffer, move each other’s parse position and desynchronize the sequence: that is protocol corruption, not merely one request’s work committed by another’s COMMIT.

The SQLite path delegates to Db, which is synchronized on its own monitor. Holding this one first is safe – the order is always Database then Db, never the reverse – and Db’s monitor is reentrant for the callbacks.

The one row a query is expected to return, or null when it returns none.

Its own method because the alternative is written at every call site and is wrong in the same way each time: reading get(0) off a list without looking at its size, which is an IndexOutOfBoundsException on the day the row is missing rather than the null the code above it is already written to handle. More than one row is a bug in the statement, and it is reported as one rather than silently discarded.

Runs an INSERT and answers the key the database generated for it.

This is the operation the engines disagree about most and the one an application needs most often. SQLite and MySQL assign the key and hold it until asked – lastInsertId – while PostgreSQL has no such concept at all, and the only way to learn the key there is to ask the INSERT itself for it with a RETURNING clause. Written by hand that is a branch on the engine at every insert; here the dialect knows which it is.

idColumn names the generated column, which is what RETURNING needs. It is quoted for the engine, so a column named “order” or one whose case matters is spelled correctly rather than folded.

ONE ROW. A statement whose VALUES clause names more than one tuple is refused before it runs, because the three engines key a multi-row insert differently and there is no answer that means the same thing on all of them. A statement whose row count its text does NOT show – an INSERT … SELECT – is refused on PostgreSQL, where RETURNING counts the rows for certain, and answers with the engine’s last-insert-id on the other two, where asking would mean trusting MySQL’s affected-row count, which says two for an upsert that touched one row. Use execute() for a statement that inserts an unknown number of rows.

How this connection’s engine spells what the three of them spell differently: parameter placeholders, identifier quoting, column types, the declaration of a generated key.

Statements passed to execute and query are already rendered through it, so ordinary code never needs this. Schema generation does – it has to ask what this engine calls a 64-bit integer.

Begins a transaction like beginTransaction, telling the engine when it will only read.

A read-only one is a real promise on two of the engines: PostgreSQL and MySQL refuse a write inside it, and SQLite takes no write lock up front (BEGIN DEFERRED rather than IMMEDIATE), so it does not queue other writers behind a transaction that will never write.

The id the most recent insert produced, or 0 where the engine has no such concept. PostgreSQL is the case that has none: use INSERT … RETURNING.

INSIDE THE GATE like every other operation on this class, which is the point: it was the one that was not. A close on another thread – a pool shutting down, a reconnect – could therefore run between this reading the engine and the engine reading its own state.

Inside the connection gate, like execute, query and transaction.

Without it a shutdown or a reconnect could close the engine while another handler was inside an operation, so Postgres.close or MySql.close wrote its termination packet into a Wire another thread was mid-exchange on – and on the packaged TLS path freed the native session while that thread was reading through it. The engines’ own close() methods were given this lock already; the facade that fronts them was not, which left the same race one level up.