stolon

Guide

Connect from psql, Python and Node.js

Your Postgres driver connects unchanged. The database name selects the branch.

The connection string

Copy it from your database's Connect page. The database name is <database>.<branch>:

postgresql://app:<password>@db.stolondb.com/acme.main

psql

psql "postgresql://app:<password>@db.stolondb.com/acme.main"
CREATE TABLE accounts (id int PRIMARY KEY, owner text NOT NULL, balance numeric(10,2) NOT NULL); INSERT INTO accounts VALUES (1, 'ada', 100.00), (2, 'lin', 250.00), (3, 'sam', 75.50); CREATE DATABASE scratch; -- a branch of main: the whole database, copied by reference \c acme.scratch UPDATE accounts SET balance = 0; -- main does not see this \l

Python with psycopg 3

import psycopg # CREATE DATABASE cannot run inside a transaction block, as in Postgres, # so open the connection that makes a branch with autocommit. with psycopg.connect("postgresql://app:<password>@db.stolondb.com/acme.main", autocommit=True) as conn: print(conn.execute("SELECT id, owner, balance FROM accounts ORDER BY id").fetchall()) conn.execute("CREATE DATABASE py_branch") with psycopg.connect("postgresql://app:<password>@db.stolondb.com/acme.py_branch") as conn: conn.execute("UPDATE accounts SET balance = balance * 2") print(conn.execute("SELECT sum(balance) FROM accounts").fetchone())

Python with psycopg2 and SQLAlchemy

import psycopg2 conn = psycopg2.connect(host="db.stolondb.com", user="app", password="<password>", dbname="acme.main") cur = conn.cursor() cur.execute("SELECT count(*), sum(balance) FROM accounts") print(cur.fetchone()) conn.close()
from sqlalchemy import create_engine, text engine = create_engine("postgresql+psycopg2://app:<password>@db.stolondb.com/acme.py_branch") with engine.connect() as conn: print(conn.execute(text("SELECT sum(balance) FROM accounts")).scalar())

Node.js with node-postgres

import pg from "pg"; const main = new pg.Client("postgresql://app:<password>@db.stolondb.com/acme.main"); await main.connect(); console.log((await main.query("SELECT id, owner, balance FROM accounts ORDER BY id")).rows); await main.query("CREATE DATABASE node_branch"); await main.end(); const branch = new pg.Client("postgresql://app:<password>@db.stolondb.com/acme.node_branch"); await branch.connect(); await branch.query("UPDATE accounts SET balance = $1 WHERE id = $2", [0, 1]); console.log((await branch.query("SELECT balance FROM accounts WHERE id = 1")).rows); await branch.end();

Node.js with postgres.js

import postgres from "postgres"; const sql = postgres("postgresql://app:<password>@db.stolondb.com/acme.node_branch"); console.log(await sql`SELECT id, balance FROM accounts WHERE id = ${1}`); await sql.end();

Tips