Build a vector database on the customer's object storage
This example builds a vector database that runs in the customer's cloud and keeps every vector in their own bucket. Releases replace the compute freely, because the containers keep nothing on local disk.
Architecture diagram. Left: Your cloud, Your backend. Right: Customer cloud containing Deployment containing router :8080; services containing writer :8081; reader :8082; data (Storage): segments.
You build:
- A public Nginx router that sends writes to a Rust writer and queries to a Rust reader.
- A writer that adds immutable segments to the customer's S3, Cloud Storage, or Blob Storage.
- Coordination through conditional writes on ETags: no lock service, consensus, or coordination database.
Source: examples/byoc-database (Rust and Nginx).
The alternative, a stateful database with attached disks, makes every release deal with volumes, replication, and migrations. It also gives the customer one more stateful system to back up. Here the only stateful thing is a bucket.
| Resource | Lifecycle | Purpose |
|---|---|---|
data Storage | Frozen | Namespace metadata and vector segments |
writer Container | Live | POST /api/v1/namespaces/{namespace}/upsert |
reader Container | Live | POST /api/v1/namespaces/{namespace}/query |
router Container | Live | Public endpoint. Routes requests by path |
Stack
The stack starts with one Storage resource. Alien maps it to S3 on AWS, Cloud Storage on Google Cloud, Blob Storage on Azure, and a folder on disk locally:
// Object storage for vector data
// S3 on AWS, Cloud Storage on Google Cloud, Blob Storage on Azure
const storage = new alien.Storage("data").build()The writer and reader build from the same Rust binary, byocdb. BYOCDB_MODE selects which routes each process serves. Both link the bucket:
// Writer container
const writer = new alien.Container("writer")
.code({
type: "source",
toolchain: { type: "rust", binaryName: "byocdb" },
src: ".",
})
.cpu(0.5)
.memory("512Mi")
.port(8081)
.environment({
BYOCDB_MODE: "writer",
PORT: "8081",
RUST_LOG: "info,byocdb=debug",
})
.permissions("default")
.link(storage)
.build()The reader is the same, with BYOCDB_MODE: "reader" and port 8082.
Only the router has a public endpoint. It's a plain Nginx image built from router/. The reader, writer, and bucket stay private to the deployment:
// Router: nginx routing requests to writer/reader
const router = new alien.Container("router")
.code({
type: "source",
toolchain: {
type: "docker",
},
src: "./router",
})
.cpu(0.25)
.memory("256Mi")
.port(8080)
.publicEndpoint("web", 8080, "http")
.healthCheck({ path: "/health", method: "GET", timeoutSeconds: 1, failureThreshold: 3 })
.permissions("default")
.build()The stack adds the bucket as frozen and the three services as live. One permission profile grants read and write on data:
export default new alien.Stack("byoc-database")
.platforms(["aws", "gcp", "azure", "kubernetes"])
.operations({
cloudwatch: { approval: { "*": "auto" } },
"aws-vpc": { approval: { "*": "auto" } },
})
.add(storage, "frozen")
.add(writer, "live")
.add(reader, "live")
.add(router, "live")
.permissions({
profiles: {
default: {
data: ["storage/data-read", "storage/data-write"],
},
},
})
.build()The bucket is frozen: the customer's admin creates it once, during initial setup (the one-time step with their own credentials), and a release can't replace or delete it. The three services are live, so each release replaces them without any authority over the bucket.
.operations() declares two read-only Remote Operator plugins, cloudwatch and aws-vpc, that run without approval. They let you inspect metrics and networking in an AWS deployment when debugging.
Reader and writer modes
Both containers start in src/main.rs. The process loads the data binding and registers routes for its mode:
let bindings = Bindings::from_env()
.map_err(|e| Error::Configuration(format!("Failed to load bindings: {}", e)))?;
// Load storage binding
let storage = bindings.storage("data").await.map_err(|e| {
Error::Configuration(format!("Failed to load storage binding 'data': {}", e))
})?;let (app, command_receiver) = match mode {
Mode::Writer => {
let writer = Arc::new(Writer::new(storage));
let state = WriterState { writer };
(
Router::new()
.route("/health", get(health))
.route("/api/v1/namespaces/{namespace}/upsert", post(upsert))
.with_state(state),
None,
)
}
Mode::Reader => {
let reader = Arc::new(Reader::new(storage));
let env = std::env::vars().collect();
let mut command_receiver = command_receiver_from_env(&env)?;
if let Some(receiver) = &mut command_receiver {
register_stats_handler(receiver, reader.clone());
}
let state = ReaderState { reader };
(
Router::new()
.route("/health", get(health))
.route("/api/v1/namespaces/{namespace}/query", post(query))
.with_state(state),
command_receiver,
)
}
};The Nginx router reaches the other containers by their internal names, writer.svc and reader.svc. These short names work on AWS, Google Cloud, Azure, and machines. On Kubernetes the name includes the namespace (writer.<namespace>.svc), so writer.svc doesn't resolve there. To run the router on Kubernetes, link it to the writer and reader and read each address from its link binding (ALIEN_WRITER_BINDING, ALIEN_READER_BINDING). The resolver comes from the container's /etc/resolv.conf at startup, so Nginx starts even before the upstreams exist:
# Route upsert to writer
location ~ ^/api/v1/namespaces/.*/upsert$ {
set $writer_backend writer.svc:8081;
proxy_pass http://$writer_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# Route query to reader
location ~ ^/api/v1/namespaces/.*/query$ {
set $reader_backend reader.svc:8082;
proxy_pass http://$reader_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}The router answers /health itself with ok, so its health check doesn't depend on the backends.
Immutable segments
Each upsert becomes a new JSON segment. A namespace looks like this in the bucket:
demo/
├── metadata.json
└── segments/
├── 2fb1….json
└── 81ac….jsonmetadata.json records the vector dimension and the list of segment IDs. Each segment holds the vectors from one upsert.
The writer checks that every vector in the request has the same dimension, then writes the segment:
// Create a new segment
let segment_id = Uuid::new_v4().to_string();
let segment = Segment::new(segment_id.clone(), request.vectors.clone());
// Serialize and write segment to storage
let segment_path = Path::from(format!("{}/segments/{}.json", namespace, segment_id));
let segment_bytes =
serde_json::to_vec(&segment).map_err(|e| Error::Serialization(e.to_string()))?;
self.storage
.put(&segment_path, Bytes::from(segment_bytes).into())
.await
.map_err(|e| Error::Storage(format!("Failed to write segment: {}", e)))?;A segment never changes after it's written. The writer then appends its ID to metadata.json.
ETag coordination
Two writers can read the same metadata.json and append different segment IDs. Without coordination, the second write would drop the first segment. The writer uses the object's ETag as an optimistic lock:
// Try to write with conditional put
let put_options = if let Some(etag_value) = etag {
// Update existing metadata with ETag check
PutOptions {
mode: PutMode::Update(etag_value),
..Default::default()
}
} else {
// Create new metadata
PutOptions {
mode: PutMode::Create,
..Default::default()
}
};
match self
.storage
.put_opts(
&metadata_path,
Bytes::from(metadata_bytes).into(),
put_options,
)
.await
{
Ok(_) => {
info!(
"Successfully updated metadata for namespace '{}' with segment {}",
namespace, segment_id
);
break;
}
Err(object_store::Error::Precondition { .. }) => {
// ETag mismatch or already exists - retry
warn!(
"Metadata update conflict for namespace '{}', retrying ({}/{})",
namespace, retries, max_retries
);
continue;
}
Err(e) => {
return Err(Error::Storage(format!("Failed to update metadata: {}", e)));
}
}PutMode::Updatesucceeds only if the object still has the ETag the writer read.PutMode::Createsucceeds only if the object doesn't exist yet.- If another writer got there first, the put fails with
Precondition. This writer reads the new metadata and tries again, up to 10 times.
The same loop enforces the namespace dimension. The first upsert sets it; a later upsert with a different dimension fails with 400.
Queries
A query loads metadata.json, checks the query dimension, then loads every segment the metadata lists:
// Load all segments
let mut all_vectors: Vec<Vector> = Vec::new();
for segment_id in &metadata.segments {
let segment = self.read_segment(namespace, segment_id).await?;
all_vectors.extend(segment.vectors);
}It scores every vector by cosine similarity and returns the top topK:
let mut scored_vectors: Vec<(usize, f32)> = all_vectors
.iter()
.enumerate()
.map(|(idx, vector)| {
let score = cosine_similarity(&request.vector, &vector.values);
(idx, score)
})
.collect();
// Sort by score descending (highest similarity first)
scored_vectors.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));The reader rebuilds this from the bucket on every query and keeps no cache. That's slow for large namespaces, but any reader replica, new or old, gives the same answer.
| Status | When |
|---|---|
200 | Upsert or query succeeded |
400 | Vectors in a request have different dimensions, or don't match the namespace dimension |
404 | The namespace has no metadata.json yet |
500 | A storage or serialization error. The body is {"error": "<message>"} |
Commands from your backend
The reader can also serve a stats command, which counts segments and vectors in a namespace. It runs the pull receiver from the alien-commands crate next to the HTTP server:
fn register_stats_handler(receiver: &mut alien_commands::Receiver, reader: Arc<Reader>) {
receiver.command("stats", move |request: StatsRequest, _ctx| {
let reader = reader.clone();
async move {
let stats = reader.stats(&request.namespace).await?;
Ok(stats)
}
});
}The receiver starts only when Alien injects ALIEN_COMMANDS_* variables, which happens when the resource has commands enabled. The example's alien.ts doesn't enable them, so out of the box the reader serves HTTP only. Add .commandsEnabled(true) to the reader to turn it on.
If the receiver stops, the whole process exits instead of leaving a healthy HTTP server that can no longer take commands. See Commands.
Run it locally
This example isn't an alien init template. Run it from a clone of the repository, with Docker running:
Start the stack:
git clone https://github.com/alienplatform/alien.git
cd alien/examples/byoc-database
pnpm install
alien devalien dev builds the binary and the router image, starts the three containers, and prints the router's endpoint URL. In a second terminal:
export DB=http://localhost:<port> # the router URL alien dev printedWrite three vectors to the demo namespace:
curl -X POST $DB/api/v1/namespaces/demo/upsert \
-H 'content-type: application/json' \
-d '{
"vectors": [
{"id": "doc1", "values": [0.1, 0.2, 0.3, 0.4], "metadata": {"title": "Hello"}},
{"id": "doc2", "values": [0.2, 0.3, 0.4, 0.5], "metadata": {"title": "World"}},
{"id": "doc3", "values": [0.9, 0.8, 0.7, 0.6], "metadata": {"title": "Other"}}
]
}'{"upserted":3}Ask for the two nearest vectors:
curl -X POST $DB/api/v1/namespaces/demo/query \
-H 'content-type: application/json' \
-d '{"vector": [0.1, 0.2, 0.3, 0.4], "topK": 2}'{
"results": [
{"id": "doc1", "score": 1.0, "metadata": {"title": "Hello"}},
{"id": "doc2", "score": 0.9938, "metadata": {"title": "World"}}
]
}Scores are rounded here. doc1 is the exact match. doc3 scores about 0.84 and is cut off by topK.
Run the integration tests. They deploy the stack locally and check:
- The router health endpoint.
- Upsert and query, and namespace isolation.
- A dimension mismatch (
400) and a query on a missing namespace (404).
pnpm testIn a cloud deployment, restart or replace the reader and send the same query again. The answer doesn't change, because everything it needs is in the bucket.
Deploy it to a customer
alien login
alien link
alien release
alien onboard customer-1 --allow admin@customer-1.com- Initial setup. The customer's admin opens the setup link, a URL to the setup page Alien hosts for them, and runs it once, with their own credentials. It creates the bucket.
- Ongoing management. Later releases replace the router, reader, and writer without the admin.
See Follow a deployment.
How it runs on each platform
| Platform | data Storage | Containers |
|---|---|---|
| AWS | S3 bucket | EC2 machines in a ComputeCluster |
| Google Cloud | Cloud Storage bucket | Compute Engine machines |
| Azure | Blob Storage container | Azure VMs |
| Kubernetes | External binding the customer provides | Deployments in the cluster |
| Local | Folder on disk | Docker containers |
The Rust code is identical on all of them. Conditional puts work the same way through object_store on S3, Cloud Storage, and Blob Storage.
On Kubernetes, Alien doesn't create a bucket; the customer points the data binding at storage they already run. See Kubernetes. The stack leaves out Linux servers, where a Container can't have a public endpoint.
Before production
A production version would also:
- Cache indexes. Keep vectors in memory and reload only when
metadata.jsonchanges, instead of reading every segment on each query. - Buffer writes. Collect vectors and flush larger segments, rather than one segment per request.
- Compact segments. Merge small segments in the background and replace older vectors that share an ID. Today an upsert always appends, so writing the same ID twice returns it twice.
- Use an index. Replace the linear cosine scan with an approximate nearest-neighbor index.
- Add authentication. The router's endpoint is public and has no auth.
The foundation stays the same: stateless containers, and ETag-coordinated writes on object storage.
Adapt it
Next
- Trace history: a single-writer store on SlateDB and object storage
- Storage reference
- Container reference
- Frozen and live resources
AI trace history on object storage
Build a durable, queryable AI trace store on SlateDB and the customer's bucket, with no database server to run in their cloud.
Kubernetes agent
A TypeScript agent in each customer's Kubernetes cluster that reports pods, deployments, and nodes to your API and answers commands, with read-only access, a generated enrollment token, and updates on every release.