Client and backend. This class is shared: the same code is compiled into your app and into your server, so everything on this page works in both.

public final class Postgres

  1. Object
  2. ServerSession
  3. Postgres

A PostgreSQL client speaking the v3 frontend/backend protocol directly.

Written rather than wrapped because there is nothing to wrap: JDBC needs a driver manager, a class loader and reflection, none of which a translated server binary has. The protocol is small, stable (v3 has been the wire format since 7.4) and documented, so the honest option is to speak it. The same source runs on both targets because it is built on SqlSocket, which each target implements.

Three decisions worth stating:

  • The extended query protocol, always. Simple Query would be fewer round trips, but it has no parameters, and a client with no way to bind a value is a client whose users concatenate SQL. Parse/Bind/Execute is what makes query(sql, params) safe by construction.
  • Text format for parameters and results. The binary format saves parsing at the cost of a per-type encoder on both sides, and gets subtly wrong for the types nobody tested. Text is what psql sends.
  • SCRAM-SHA-256 is verified in both directions. The server’s final message proves it knew the stored key; skipping that check (which a client can do and still connect successfully) leaves the handshake open to a server that only pretends to be PostgreSQL.

Fields

public static final ServerSession.Connector CONNECTOROpens Postgres sessions; naming this constant is what puts the engine in an application.

Methods

public Dialect dialect()The SQL this session’s server speaks.
public boolean ownsTransactionControl()True when beginning, committing and rolling back are protocol requests or session state of this client’s own, rather than statements a caller could equally run.
public static Postgres connect(String host, int port, String database, String user, String password, String sslMode, String caFile, int timeoutMillis, int socketTimeoutMillis) throws IOExceptionConnects, negotiates TLS when asked, authenticates, and returns a session ready for queries.
public int execute(String sql, Object[] params) throws IOExceptionRuns a statement that returns no rows, and returns the number affected.
public List query(String sql, Object[] params) throws IOExceptionRuns a query and returns each row as a column-name to value map, with the SAME value types the SQLite path produces: Long, Double, String, byte[] or null.
public void close()Closes the session; closing twice does nothing.
public void begin() throws IOExceptionOpens a transaction.
public void beginReadOnly() throws IOExceptionBegins a read-only transaction at the server’s default isolation.
public void begin(boolean readOnly, TransactionIsolation isolation) throws IOExceptionOpens a transaction at an isolation level.
public void commit() throws IOExceptionCommits the transaction.
public void rollback() throws IOExceptionRolls the transaction back.
public void savepoint(String verb, String name) throws IOExceptionSavepoint control; the name must be a plain identifier.
public boolean isClosed()True once the session is closed or its connection was lost.
public long lastInsertId()PostgreSQL reports generated keys through RETURNING rows, so there is no last insert id.

Inherited nested types

Inherited methods

Field details

CONNECTOR

public static final ServerSession.Connector CONNECTOR
Opens Postgres sessions; naming this constant is what puts the engine in an application. See ServerSession.Connector.

Method details

dialect

public Dialect dialect()
The SQL this session’s server speaks.

ownsTransactionControl

public boolean ownsTransactionControl()
True when beginning, committing and rolling back are protocol requests or session state of this client’s own, rather than statements a caller could equally run.

connect

public static Postgres connect(String host, int port, String database, String user, String password, String sslMode, String caFile, int timeoutMillis, int socketTimeoutMillis) throws IOException

Connects, negotiates TLS when asked, authenticates, and returns a session ready for queries.

sslMode is “require”, “prefer” or “disable”. “prefer” exists because it is what a local development database usually needs and a managed one usually forbids; “require” fails rather than falling back, which is the only setting that means anything against an attacker.

execute

public int execute(String sql, Object[] params) throws IOException
Runs a statement that returns no rows, and returns the number affected.

Returns

the number of rows it changed

query

public List query(String sql, Object[] params) throws IOException
Runs a query and returns each row as a column-name to value map, with the SAME value types the SQLite path produces: Long, Double, String, byte[] or null. A handler must not be able to tell which engine answered it.

close

public void close()
Closes the session; closing twice does nothing.

begin

public void begin() throws IOException
Opens a transaction. PostgreSQL prepares transaction control like any other statement, so the facade normally sends it through execute where it is traced; these exist so every engine answers the same calls.

beginReadOnly

public void beginReadOnly() throws IOException
Begins a read-only transaction at the server’s default isolation.

begin

public void begin(boolean readOnly, TransactionIsolation isolation) throws IOException
Opens a transaction at an isolation level. READ_UNCOMMITTED is refused: PostgreSQL accepts the words and runs READ COMMITTED.

commit

public void commit() throws IOException
Commits the transaction.

rollback

public void rollback() throws IOException
Rolls the transaction back.

savepoint

public void savepoint(String verb, String name) throws IOException
Savepoint control; the name must be a plain identifier.

isClosed

public boolean isClosed()
True once the session is closed or its connection was lost.

lastInsertId

public long lastInsertId()
PostgreSQL reports generated keys through RETURNING rows, so there is no last insert id.