SDK Overview

ParticleDB SDKs in this repo target three live transport families today: REST API, PostgreSQL wire, and gRPC. Some SDKs also contain streaming/WebSocket layers, but the default server path today is HTTP SSE streaming rather than a production WebSocket endpoint.

Quick Start

Python

# REST client (zero dependencies)
pip install particledb

# With gRPC support
pip install particledb[grpc]

TypeScript

# PG wire + streaming + gRPC
npm install particledb

Go

# PG wire + gRPC
go get github.com/particledb/particledb-go

Rust

[dependencies]
particledb-sdk = "0.1"

Java

<!-- Native PDB-wire JDBC driver. See /sdks/java/ -->
<dependencies>
    <dependency>
        <groupId>ai.particledb</groupId>
        <artifactId>particledb-jdbc</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

C#

dotnet add package ParticleDB.Client

Kotlin

implementation("io.particledb:particledb-kotlin:0.1.0")

Swift

.package(url: "https://github.com/particledb/particledb-swift.git", from: "0.1.0")

Dart

dependencies:
  particledb: ^0.1.0

Ruby

gem "particledb"

PHP

composer require particledb/particledb-php

C

cd sdk/c && make && sudo make install

C++

add_subdirectory(path/to/particledb-sdk)
target_link_libraries(your_target particledb)

Browser

npm install @particledb/web

SDK Comparison

Language	Package	Transport	Vector	KV	RAG	AI
Python	particledb	REST + gRPC	Yes	Yes	Yes	—
TypeScript	particledb	PG wire + gRPC + SSE	Yes	Yes	Yes	Yes
Go	particledb-go	PG wire + gRPC	Yes	Yes	Yes	Yes
Java	ai.particledb:particledb-jdbc	JDBC over PDB native wire (Arrow IPC)	Yes	Yes	Yes	Yes
Rust	particledb-sdk	SqlExecutor trait (pluggable)	Yes	Yes	Yes	Yes
C# / .NET	ParticleDB.Client	PG wire (Npgsql)	Yes	Yes	Yes	Yes
Kotlin	particledb-kotlin	REST (OkHttp)	Yes	Yes	Yes	—
Swift	particledb-swift	REST (URLSession)	Yes	Yes	Yes	—
Dart / Flutter	particledb	REST (http)	Yes	Yes	Yes	—
Ruby	particledb	REST (Net::HTTP)	Yes	Yes	Yes	—
PHP	particledb-php	REST (cURL)	Yes	Yes	Yes	—
C	libparticledb	REST (libcurl)	—	—	—	—
C++	particledb (header-only)	PG wire (libpq)	Yes	Yes	Yes	Yes
Browser	@particledb/web	Experimental WebSocket layer	Yes	Yes	Yes	Yes

Transport Details

REST API (HTTP)

Used by: Python, Kotlin, Swift, Dart, Ruby, PHP, C

The REST API runs on port 8080 by default. SDKs send SQL as JSON payloads to POST /v1/sql and receive structured JSON responses. Zero-dependency clients can be built using any HTTP library.

PostgreSQL Wire Protocol

Used by: TypeScript, Go, C#, C++ (also available to Java via stock pgjdbc)

Full compatibility with standard PostgreSQL drivers. Supports prepared statements, transactions, binary format, and pipeline mode. Runs on port 5432 by default.

PDB Native Wire v2

Used by: Java (ai.particledb:particledb-jdbc)

HTTP/2-style multiplexing over a single TCP connection. Arrow IPC result rows for typed, zero-copy decoding. Default port 5440 (TLS on 5443). The Java JDBC driver is the reference implementation; other SDKs use this transport via language-specific clients.

gRPC

Used by: Python, TypeScript, Go

Native gRPC protocol with protobuf-encoded messages. The current server listens on port 26257 by default and exposes the particledb.v1.ParticleDB service.

Streaming transports

Used by: TypeScript/browser-oriented clients

The repo contains SSE and WebSocket client code. Today, the default server exposes SSE over HTTP (/v1/sql/stream). Treat WebSocket support as experimental unless you have explicitly wired a compatible endpoint into your deployment.

What the SDKs Add

Standard PostgreSQL drivers give you full SQL access to ParticleDB. The ParticleDB SDKs add:

• Vector search helpers — Build and query vector indexes with a typed API instead of raw SQL
• KV operations — get, set, delete, mset, incr, keys methods for key-value workloads
• RAG pipelines — Create named pipelines for retrieval-augmented generation workflows
• AI functions — Embeddings, text generation, classification, and summarization
• CDC streaming — Real-time change-data-capture event subscriptions over gRPC, plus experimental streaming helpers in some SDKs

Next Steps

• Python SDK — REST + gRPC client
• TypeScript SDK — PG wire + gRPC + streaming
• Go SDK — PG wire + gRPC client
• Rust SDK — Native Rust client with SqlExecutor trait
• Java SDK — JDBC + gRPC client
• C# / .NET SDK — Npgsql-based client
• Kotlin / Android — REST API via OkHttp
• Swift — REST API via URLSession
• Dart / Flutter — REST API via http package
• Ruby — REST API via Net::HTTP
• PHP — REST API via cURL
• Clojure — Idiomatic next.jdbc wrapper for the PG wire
• C — REST API via libcurl
• C++ — Header-only, libpq
• Browser / Web SDK — Browser client notes and current transport caveats
• PostgreSQL Wire Protocol — Protocol-level details
• gRPC — gRPC protocol details
• HTTP API — REST API reference