Connect a SQL client

What you can connect.

Any client or driver that speaks the PostgreSQL protocol can connect. The three we verify against are psql, DBeaver, and pgAdmin - walkthroughs for each are below. Language drivers that use the same protocol (libpq, JDBC's PostgreSQL driver, node-postgres, psycopg, pgx, and friends) connect the same way, and so does the standard PostgreSQL ODBC driver - DSN details below.

Connection details.

Host, port, username and password are per-database and live in the console: open your instance and look for the SQL access panel. The port is PostgreSQL's stock 5432; authentication is SCRAM-SHA-256 (the flow every current Postgres client speaks), and the connection must use TLS - keep sslmode=require.

host      <your-database-host>    # console -> your instance -> SQL access
port      5432                    # PostgreSQL's stock port - the panel shows it too
database  postgres                # cosmetic - see the note below this block
user      <user>                  # shown in the SQL access panel
password  <password>              # shown in the SQL access panel
sslmode   require

# Or as one connection URI:
postgresql://<user>:<password>@<your-database-host>:5432/postgres?sslmode=require

One more gate before the first connect: the SQL port is reachable only from addresses on your instance's IP Access List - it is never open to the world. An empty list means the port stays closed and every client times out. Add the address you connect from (console → your instance → Network access) and retry.

Client walkthroughs.

Each tab is the short version: the fields that matter and the one gotcha worth knowing in advance. pgAdmin gets a fuller step-by-step just below, and ODBC consumers have a section of their own.

# One line - paste the values from the console's SQL access panel:
psql "host=<your-database-host> port=5432 dbname=postgres \
      user=<user> password=<password> sslmode=require"

# Gotcha: \copy (and the COPY protocol generally) is not supported yet.
# Bulk-load with a multi-row INSERT ... VALUES (...), (...) instead,
# or use the HTTP ingest API. Everything else psql does day-to-day -
# queries, \d, \dt, \df, PREPARE/EXECUTE, transactions - works.

1. New Database Connection -> PostgreSQL (the stock PostgreSQL driver -
   no custom driver needed).
2. Host, Port, Username, Password: paste from the console's SQL access
   panel. Database: leave "postgres".
3. SSL tab -> enable SSL. Test Connection -> Finish.

Gotcha: the database navigator shows exactly ONE database, named
"postgres", regardless of what your database is called in the
console. Your table namespaces appear as schemas under it (the
default namespace shows as "public"). Don't enable "Show all
databases" and go hunting for a database with your name on it;
there isn't one.

1. Add New Server -> General: any name you like.
2. Connection tab: Host name/address, Port, Username, Password from
   the console's SQL access panel. Maintenance database: leave
   "postgres".
3. Parameters tab: SSL mode = Require. Save.

Gotcha: pgAdmin's Dashboard panels read PostgreSQL's statistics
tables (pg_stat_activity and friends), which this adapter does not
serve - expect empty panels or a polite error there. The object
browser and the Query Tool are the supported surfaces, and both work.

SQL compatibility.

The honest matrix. Works over wire means your SQL client runs it directly (and the HTTP SQL endpoint runs it too). API only means the capability exists, but through the HTTP API rather than your SQL client. Not yet means exactly that - we'd rather tell you here than have you find out in production. One caveat spans every row: write statements over the wire apply to a single-node instance without row or column controls. A session running under a database-user identity, and any replicated configuration, gets a read-only wire - see the limits below.

DDL over the wire, for completeness: CREATE TABLE and DROP TABLE are real (the drop cascades through rows and indexes, same as the API path). CREATE INDEX, CREATE SEQUENCE and ALTER TABLE are API-only for now. WITH (CTEs) is refused over the wire. COPY (both directions) is not supported yet on any client.

Limits, stated plainly.

SERIALIZABLE is refused, not faked.

Wire connections run at READ COMMITTED. If you ask for more - SET TRANSACTION ISOLATION LEVEL SERIALIZABLE, BEGIN ISOLATION LEVEL REPEATABLE READ, or the equivalent session default - the server returns an error (SQLSTATE 0A000) naming the level it can't deliver. It never acknowledges the request and quietly gives you READ COMMITTED anyway. That's deliberate: a database that says yes and delivers less is lying to your correctness logic - write-skew protection you believe you have but don't is worse than an error at connection time. Levels at or below READ COMMITTED are accepted as-is, so drivers that set read-committed on connect work unchanged. Serializable transactions are available - through the HTTP transactions API, on single-node configurations.

Materialized-view DDL lives on the HTTP endpoint, not the wire.

Plain CREATE MATERIALIZED VIEW name AS select works over the HTTP SQL endpoint - it is populated at creation, and lands in the same refresh and inspection flow as views defined through the materialized views reference. Two forms are refused rather than half-honoured: OR REPLACE (drop, then create) and WITH NO DATA. Over the wire, CREATE MATERIALIZED VIEW is refused.

Row and column controls come with an identity - and a read-only wire.

Where column masks or row-security policies exist, the wire never serves data without knowing who is asking: enabling SQL access on an instance that carries them requires database-user credentials, and a listener that cannot resolve one refuses to serve those objects rather than read them in the clear. When a session does run under a database-user identity, every SELECT is filtered and masked for that user, per session, exactly as the HTTP API - and the session is read-only: every write verb (INSERT / UPDATE / DELETE, CREATE / DROP / ALTER / TRUNCATE, CALL, GRANT / REVOKE) is refused with SQLSTATE 0A000 and points you at the HTTP SQL endpoint for the write. Replicated configurations get the same read-only wire regardless of identity - an inline wire write would bypass the replication path.

Multi-node configurations refuse what they can't guarantee.

The same honesty rule applies across configurations: on a sharded or replicated setup, surfaces that can't uphold their guarantee are refused with a clear error rather than served with silently weaker semantics. Concretely: serializable API transactions are single-node only - a sharded configuration refuses to open one - and on replicated setups they are further restricted to point reads. If a request succeeds, its stated guarantee holds; if we can't hold it, you get an error you can code against.