Skip to main content

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.

No authentication by default

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​

bash
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.

LanguageDriverConnection string
Pythonpsycopg (psycopg3) or psycopg2postgresql://scramdb@localhost:5432/scramdb
JavaPostgreSQL JDBCjdbc:postgresql://localhost:5432/scramdb
Node.jspgpostgresql://scramdb@localhost:5432/scramdb
Gopgx or lib/pqpostgres://scramdb@localhost:5432/scramdb
Rusttokio-postgreshost=localhost port=5432 user=scramdb dbname=scramdb
.NETNpgsqlHost=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​

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)​

java
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​

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​

SettingDefaultNotes
HostlocalhostThe address ScramDB is listening on
Port5432The standard PostgreSQL port
DatabasescramdbThe database to connect to
UserscramdbBootstrap superuser role, no password by default. Create additional roles with CREATE ROLE
Passwordnone by defaultSet 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.