Clients and Drivers
ScramDB speaks the PostgreSQL wire protocol, so the drivers and tools you already use work without changes. Point them at ScramDB the way you would point them at PostgreSQL, with a host, port, database, user, and password. There is no ScramDB-specific SDK to install and no new query language to learn.
The examples below assume ScramDB is listening on localhost:5432 with a database named scramdb.
The published scramdb/scramdb Docker image starts with authentication disabled by default: any client that reaches port 5432 can connect as any existing role (for example scramdb, the bootstrap superuser) with no password; a user name that names no role is refused, as in PostgreSQL. That's fine for a local instance on your own machine, but do not point a shared or internet-reachable ScramDB instance's driver connections at it without first enabling authentication and setting a password on the roles you use. See Quick Start for how to enable it.
Command line: psql
psql -h localhost -p 5432 -U scramdb scramdb
Everything you expect from psql works: \dt to list tables, \d table to describe one, \timing to measure queries, and running .sql files with -f.
Drivers by language
Use the standard PostgreSQL driver for your language. No adapter, no shim.
| Language | Driver | Connection string |
|---|---|---|
| Python | psycopg (psycopg3) or psycopg2 | postgresql://scramdb@localhost:5432/scramdb |
| Java | PostgreSQL JDBC | jdbc:postgresql://localhost:5432/scramdb |
| Node.js | pg | postgresql://scramdb@localhost:5432/scramdb |
| Go | pgx or lib/pq | postgres://scramdb@localhost:5432/scramdb |
| Rust | tokio-postgres | host=localhost port=5432 user=scramdb dbname=scramdb |
| .NET | Npgsql | Host=localhost;Port=5432;Database=scramdb |
ScramDB's own test suite runs SQLAlchemy 2 (with Alembic migrations), Django, Peewee, asyncpg, psycopg 3, sqlx, SeaORM and Diesel against a server, so these work with no ScramDB-specific adapter.
Python
import psycopg
with psycopg.connect("postgresql://scramdb@localhost:5432/scramdb") as conn:
with conn.cursor() as cur:
cur.execute("SELECT count(*) FROM orders")
print(cur.fetchone())
Java (JDBC)
String url = "jdbc:postgresql://localhost:5432/scramdb";
try (Connection conn = DriverManager.getConnection(url, "scramdb", "")) {
try (Statement st = conn.createStatement();
ResultSet rs = st.executeQuery("SELECT count(*) FROM orders")) {
while (rs.next()) System.out.println(rs.getLong(1));
}
}
Node.js
import { Client } from 'pg';
const client = new Client({ connectionString: 'postgresql://scramdb@localhost:5432/scramdb' });
await client.connect();
const { rows } = await client.query('SELECT count(*) FROM orders');
console.log(rows[0]);
await client.end();
GUI and BI tools
Because the wire protocol is PostgreSQL, tools that speak to PostgreSQL connect to ScramDB the same way. Choose the PostgreSQL connection type and enter the host, port, database, and credentials:
- pgAdmin, DBeaver, DataGrip for querying and browsing schemas
- Grafana and other BI tools, using their PostgreSQL data source
Connection settings
| Setting | Default | Notes |
|---|---|---|
| Host | localhost | The address ScramDB is listening on |
| Port | 5432 | The standard PostgreSQL port |
| Database | scramdb | The database to connect to |
| User | scramdb | Bootstrap superuser role, no password by default. Create additional roles with CREATE ROLE |
| Password | none by default | Set one with ALTER ROLE scramdb WITH PASSWORD '...' once authentication is enabled |
Settings the server reports
Drivers read a few settings from the connection instead of asking for them: libpq and JDBC escape a literal by standard_conforming_strings, psycopg reads server_version and TimeZone, and a pool reads search_path and application_name to restore a session. ScramDB tells a client the same fifteen settings as PostgreSQL 18.6, in the same order, when it connects: in_hot_standby, integer_datetimes, TimeZone, IntervalStyle, search_path, is_superuser, application_name, default_transaction_read_only, scram_iterations, DateStyle, standard_conforming_strings, session_authorization, client_encoding, server_version and server_encoding.
The values are the session's own: server_version is 18.6, is_superuser is off for a role without the SUPERUSER attribute, session_authorization is the role that logged in, and the settings the connection asked for (application_name, TimeZone, options=-c ...) and the ones ALTER ROLE ... SET and ALTER DATABASE ... SET stored are already applied.
After that the server tells a client a setting again whenever its value changes, once, right before the ReadyForQuery of the message that changed it. SET, RESET, set_config, SET ROLE (is_superuser), SET SESSION AUTHORIZATION, DISCARD ALL, the end of a transaction that used SET LOCAL and a ROLLBACK of a SET are all told, with the value the session now has. A SET to the value the client already knows, a setting that is not on the list and a change that was undone inside the same message (a function with a SET clause) tell nothing. SHOW is_superuser follows the current role the same way.
Connecting to a cluster
Everything above is unchanged against a cluster: same driver, same DSN shape, same SQL. Every node serves every table, so one pool against any node is the correct default and there is no coordinator or proxy to run. The one thing worth reading before you ship is the retry contract, which is three SQLSTATEs your ORM most likely already handles: Connecting to a cluster, with the full code list in Error codes.
See PostgreSQL Compatibility for the full list of supported features, and Get Started to connect for the first time.