Skip to main content
Stackhouse
Stackhouse

Documentation

Introduction to Stackhouse

What is Stackhouse and why should you use it?

Introduction to Stackhouse

🎯 What is Stackhouse?

Stackhouse is a next-generation database that evolves with your application, not against it. Schema-later, AI-native, and realtime.

Stackhouse is an open-source, AI-native database that combines the flexibility of NoSQL with the power of SQL, vector search, and serverless compute—all in one unified system.

📊 The Problem Stackhouse Solves

Pain pointWhy it hurts
MigrationsSchema locks, downtime required
Vector SearchSeparate service, high latency/cost
Serverless ComputeCloud functions only, vendor lock-in
Realtime UpdatesMultiple tools, complex setup

Stackhouse eliminates all of this.

✨ The Stackhouse Solution

Rendering diagram…

🌟 Core Philosophy

1️⃣ Schema-Later™

Don't plan your schema upfront. Let it evolve naturally.

Traditional Database

  • Day 1: Define schema → wait for migration → deploy
  • Day 7: Add field → write migration → deploy
  • Day 30: Restructure → complex migration → deploy
  • Day 100: Performance → re-index everything → deploy

Result: development slows down as schema grows.

Stackhouse

  • Day 1: Push JSON → ✅ works immediately
  • Day 7: Push JSON → ✅ schema auto-evolves
  • Day 30: Push JSON → ✅ handles any structure
  • Day 100: Query → ✅ optimized automatically

Result: development stays fast forever.

Visual Example:

Request 1: POST /users {name: "Alice", age: 25}

Stackhouse infers and creates:

CREATE TABLE users (
  name TEXT,
  age INTEGER
);

Request 2: POST /users {name: "Bob", age: 30, email: "bob@..."}

Stackhouse evolves the schema:

ALTER TABLE users ADD COLUMN email TEXT;

Request 3: POST /users {name: "Carol", preferences: {theme: "dark"}}

Stackhouse adapts again:

ALTER TABLE users ADD COLUMN preferences JSON;

2️⃣ AI-Native

Vector search is a first-class, unified API — not a bolt-on you have to wire up yourself — even though under the hood it proxies to a dedicated Qdrant instance rather than an in-process index (see Vector Search).

Rendering diagram…

Semantic Search Example:

Rendering diagram…

3️⃣ Realtime 2.0

Bi-directional WebSocket communication, not just server-sent events.

Rendering diagram…

Benefits:

  • ✅ Bidirectional subscribe/unsubscribe control messages
  • ✅ Multiple table subscriptions per connection
  • ✅ Server-initiated push on INSERT/UPDATE/DELETE

Note: this channel is for table-change subscriptions only — there is no arbitrary SQL query-over-WebSocket capability; use the REST query/SQL endpoints for that.

🏗️ Architecture Overview

Rendering diagram…

All data lives in PostgreSQL — Stackhouse does not implement its own storage engine. See Architecture and Storage Engine for the verified breakdown. The JavaScript function runtime (compute/functions.rs, powered by boa_engine) is implemented and its HTTP router is mounted under /v1/functions in main.rs.

🎯 Key Features Deep Dive

1. Automatic Schema Evolution

Initial state: empty database — no tables, no schema.

Insert User Document

POST /users
{ "name": "Alice", "age": 25 }

Stackhouse infers:

CREATE TABLE users (
  id BIGSERIAL PRIMARY KEY,
  name TEXT,
  age BIGINT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Insert Document with New Field

POST /users
{ "name": "Bob", "email": "bob@example.com" }  // NEW FIELD

Stackhouse evolves:

ALTER TABLE users ADD COLUMN IF NOT EXISTS email TEXT;

Insert Complex Nested Object

POST /users
{ "name": "Carol", "settings": { "theme": "dark", "notifications": true } }

Stackhouse adapts:

ALTER TABLE users ADD COLUMN IF NOT EXISTS settings JSONB;

Result: zero downtime, zero manual migrations!

2. PostgreSQL-Backed Storage

Stackhouse does not implement its own storage engine (no custom WAL/MemTable/SSTable stack exists in this codebase). All data is stored in PostgreSQL via sqlx — durability, WAL, compaction, MVCC, and caching are all delegated to Postgres itself.

Rendering diagram…

See Storage Engine for the full breakdown.

3. Vector Similarity Search

Embed the document — "The quick brown fox jumps over the lazy dog"

Passed through an embedding model (e.g. sentence-transformers) to produce a vector: [0.23, -0.45, 0.67, 0.12, ..., 0.89] (384 dimensions for example).

Insert into Stackhouse

POST /v1/vectors/documents/upsert
{
  "id": "doc1",
  "embedding": [0.23, -0.45, ...],
  "data": {"title": "..."}
}

HNSW index build (via Qdrant)

  • Approximate Nearest Neighbor
  • Hierarchical graph structure
  • O(log n) search complexity
  • Built and served by an external Qdrant instance, not Stackhouse's own storage engine

Query time — "What did the fox do?"

The same embedding model produces a query vector [0.25, -0.43, 0.65, ...]:

POST /v1/vectors/documents/search
{
  "vector": [0.25, -0.43, ...],
  "top_k": 10
}

Results, sorted by similarity

  1. doc1 (similarity: 0.88) — most similar
  2. doc15 (similarity: 0.77)
  3. doc7 (similarity: 0.69)
  4. …
  5. doc42 (similarity: 0.33)

Distance metrics:

  • Cosine Similarity (default) — semantic similarity
  • Euclidean Distance — geometric distance

Use cases:

  • ✅ Semantic search
  • ✅ Recommendation systems
  • ✅ Document similarity
  • ✅ Image search (via vision embeddings)
  • ✅ Duplicate detection

💪 Performance Characteristics

No throughput/latency numbers are published — actual performance is governed by the underlying PostgreSQL deployment (instance size, connection pool limits, indexes, network) and, for vector search, by the external Qdrant deployment, rather than by any fixed constant in Stackhouse's own code. There is no bundled benchmark suite in this repo today (see Benchmarks); measure against your own deployment before relying on any comparative number.

🎓 When to Use Stackhouse?

✅ Perfect For:

  1. Rapid Prototyping

    • Changing requirements? No problem.
    • Unknown data model? Start anyway.
    • Quick iterations? Native workflow.

  2. AI/ML Applications

    • Semantic search
    • RAG (Retrieval Augmented Generation)
    • Recommendation engines
    • Similarity matching

  3. Realtime Features

    • Live dashboards
    • Collaborative apps
    • Notifications
    • Gaming leaderboards

  4. Serverless Compute

    • Custom business logic
    • Data transformations
    • Edge computing
    • Cost reduction

⚠️ Consider Alternatives For:

  1. Legacy SQL Migrations

    • If you have strict migration requirements
    • Consider: Postgres, MySQL

  2. Massive Analytics

    • Petabyte-scale data warehousing
    • Consider: Snowflake, BigQuery

  3. Distributed Transactions

    • Multi-region ACID transactions
    • Consider: CockroachDB, Spanner

🚀 What's Next?

Continue your journey:

Ready to start? Continue to Quick Start 🚀