Basin — documentation

01 · start here

Quickstart

Basin is one binary. Point it at a data directory and run — local development needs no external object store, and the same binary that runs on your laptop is the one that runs against S3.

# Docker — pgwire on :5432, no Rust toolchain
docker run --rm -p 5432:5432 -v basin-data:/var/basin --name basin basin-server
 
# From source — pgwire on :5433
BASIN_DATA_DIR=/tmp/basin cargo run -p basin-server
 
# Connect with any Postgres client
psql 'postgres://alice@127.0.0.1:5433/alice'
      

5-Minute Docker Quickstart

One docker run, connect via psql, no toolchain required.

docs/quickstart-docker.md

Getting started tutorial

CRUD, auth, RLS policies, the REST API and a frontend snippet — ~15 minutes.

docs/tutorial.md

Reference applications

A multi-tenant SaaS starter and an AI/RAG app, both runnable.

examples/

Deployment

Production-shaped boot: WAL, shard owner, pool, JWT auth and REST in one process.

docs/deployment.md

02 · how it works

Architecture

pgwire on the front, Vortex-compressed columnar files on an S3-compatible bucket on the back, with a file-backed WAL between them. A project is a bucket prefix the engine refuses to read across, resolved once at connection accept.

Architecture overview

The full path from a wire message to bytes on object storage.

docs/architecture.md

HTAP hot tier

The UPDATE/DELETE fast paths, on by default, and what they cost.

docs/htap-guide.md

Object-storage scaling

How throughput behaves as buckets, prefixes and files multiply.

docs/scaling/object-storage.md

Capability matrix

Feature-by-feature status, honestly marked shipped or not.

CAPABILITIES.md

03 · the wire

SQL compatibility

Basin parses with libpg_query — the actual PostgreSQL parser, vendored — so at parse time your ORM cannot tell the difference. 863 of 975 SQL fragments pass on the default configuration (88.5%). Basin is Postgres-compatible, not Postgres; the gaps are documented rather than papered over.

Area	Status
pgwire v3	Simple + extended query, TLS, COPY, prepared statements, binary params
Row-Level Security	`ENABLE ROW LEVEL SECURITY` + `CREATE POLICY`, enforced at the plan layer
Vector search	`vector(N)` + HNSW, pgvector-compatible operators
Extensions	Equivalents for pgcrypto, uuid-ossp, pg_trgm, plus basin-cron / net / geo / cv
Stored procedures	`LANGUAGE sql` + `CALL` only — no PL/pgSQL, PL/Python or PL/Perl
Replication	Not supported — wrong shape for object-store storage; CDC out of scope
Federation	No `postgres_fdw` / `dblink`; use basin-net for HTTP-shaped reads

SQL support matrix

Generated from the test suite — the ground truth, never hand-edited.

docs/sql-support.md

Compatibility notes

Where behaviour diverges from Postgres and why.

docs/sql-compatibility.md

ORM compatibility

Drizzle, Prisma, SQLAlchemy, Diesel, SeaORM and friends.

docs/orm-compat.md

Migration tools

sqlx, flyway, golang-migrate.

docs/migration-tools.md

04 · isolation

Multi-project

The connection URL names the project. After accept, ordinary SQL — no per-query auth, no row-scoping boilerplate. Adding a tenant writes no new heap pages and books no connection slot, which is where the cost shape comes from.

Multi-project isolation

How prefixes bound a project and what crosses the boundary (nothing).

docs/multi-project.md

Importing data

Getting an existing Postgres database into Basin.

docs/import.md

05 · included

Batteries included

Auth, REST, cron, webhooks, Wasm functions, vector search and an Iceberg catalog are all in the same binary — not sidecars to deploy and version separately.

What ships in the box

The full list, with the ADR that scoped each one.

docs/batteries.md

Wasm functions

Server-side functions with the sandbox boundary spelled out.

docs/functions.md

06 · clients

Client SDKs

Ten engine-direct SDKs, all MIT-licensed and all speaking pgwire + REST straight to a Basin engine. They live in the monorepo under sdks/ and are versioned alongside the engine they target.

JavaScript / TypeScript

Browser, Node, Deno, Bun and Workers. Realtime subscriptions + Arrow IPC.

sdks/js

Python

Async and sync clients, realtime, Arrow via pyarrow.

sdks/py

Go

Arrow IPC streaming against the engine.

sdks/go

Rust, Java, Ruby, .NET, PHP, Dart, Swift

Six more first-party clients with the same surface.

sdks/

07 · running it

Operations

Basin is meant to be self-hosted on your own box and your own bucket. Runbooks and operator guides are versioned in the repository next to the code they cover.

Operator guides

Quotas, compatibility checks and day-two concerns.

docs/operators/

Runbooks

Procedures for the situations you'd rather not improvise.

docs/runbooks/

Benchmark methodology

How the numbers are produced, and why losses are published too.

benchmark/BENCHMARKS.md

Security policy

Reporting process and supported versions.

SECURITY.md

08 · why

Design decisions

Basin is opinionated about scope, and the reasoning is written down. Every "no" in the compatibility table has a one-page rationale that includes the trigger which would change our mind.

Open an issue before a PR that adds new surface area. The ADRs exist so scope arguments happen once, in writing, rather than in review.

Architecture decision records

The numbered ADRs, including the ones that closed doors deliberately.

docs/decisions/

Contributing

How to build, test and land a change.

CONTRIBUTING.md

Basin documentation