Skip to content
Varity Docs

Data Storage Quick Start

Varity Team Core Contributors Updated March 2026

Store and retrieve structured data with zero configuration. The Varity SDK provides a simple, MongoDB-like database API that works out of the box.

What You Get

Section titled “What You Get”
  • Zero config — works immediately with shared dev credentials
  • Simple API — add, get, update, delete on collections
  • Type-safe — full TypeScript generics support
  • Auto-provisioned — deploy with varitykit deploy and get your own private database

Installation

Section titled “Installation”
Terminal window
npm install @varity-labs/sdk

Store Your First Record

Section titled “Store Your First Record”

  1. Import the database

    import { db } from '@varity-labs/sdk';

    The db singleton is pre-configured and ready to use. No initialization needed.

  2. Add a record to a collection

    const product = await db.collection('products').add({
      name: 'T-Shirt',
      price: 29.99,
      inStock: true,
    });
    

    console.log('Saved with ID:', product.id);
    // "550e8400-e29b-41d4-a716-446655440000"

  3. Retrieve your records

    const products = await db.collection('products').get();
    

    products.forEach(p => {
      console.log(`${p.name}: $${p.price}`);
    });

CRUD Operations

Section titled “CRUD Operations”

Create

Section titled “Create”
const record = await db.collection('todos').add({
  title: 'Buy groceries',
  completed: false,
});
// Returns: { id, title, completed, created_at, updated_at }

Read

Section titled “Read”
// Get all records
const all = await db.collection('todos').get();


// With pagination
const page = await db.collection('todos').get({
  limit: 10,
  offset: 0,
});


// With ordering (prefix "-" for descending)
const sorted = await db.collection('todos').get({
  orderBy: '-created_at',
});

Update

Section titled “Update”
await db.collection('todos').update(record.id, {
  completed: true,
});

Delete

Section titled “Delete”
await db.collection('todos').delete(record.id);

Type-Safe Collections

Section titled “Type-Safe Collections”

Use TypeScript generics for full type safety:

import { db } from '@varity-labs/sdk';


interface Product {
  name: string;
  price: number;
  category: string;
  inStock: boolean;
}


const products = db.collection<Product>('products');


// TypeScript knows the shape of your data
const item = await products.add({
  name: 'Widget',
  price: 29.99,
  category: 'tools',
  inStock: true,
});


// item.name is string, item.price is number, item.id is string

Complete Example

Section titled “Complete Example”
components/TodoApp.tsx
import { db } from '@varity-labs/sdk';
import { useState, useEffect } from 'react';


interface Todo {
  title: string;
  completed: boolean;
}


export function TodoApp() {
  const [todos, setTodos] = useState<(Todo & { id: string })[]>([]);
  const [newTitle, setNewTitle] = useState('');


  // Load todos on mount
  useEffect(() => {
    db.collection<Todo>('todos').get().then(setTodos);
  }, []);


  // Add a todo
  const addTodo = async () => {
    if (!newTitle.trim()) return;
    const todo = await db.collection<Todo>('todos').add({
      title: newTitle,
      completed: false,
    });
    setTodos(prev => [...prev, todo]);
    setNewTitle('');
  };


  // Toggle completion
  const toggleTodo = async (id: string, completed: boolean) => {
    await db.collection<Todo>('todos').update(id, { completed: !completed });
    setTodos(prev =>
      prev.map(t => (t.id === id ? { ...t, completed: !completed } : t))
    );
  };


  // Delete a todo
  const deleteTodo = async (id: string) => {
    await db.collection<Todo>('todos').delete(id);
    setTodos(prev => prev.filter(t => t.id !== id));
  };


  return (
    <div>
      <div>
        <input
          value={newTitle}
          onChange={e => setNewTitle(e.target.value)}
          placeholder="New todo..."
        />
        <button onClick={addTodo}>Add</button>
      </div>
      <ul>
        {todos.map(todo => (
          <li key={todo.id}>
            <input
              type="checkbox"
              checked={todo.completed}
              onChange={() => toggleTodo(todo.id, todo.completed)}
            />
            <span style={{ textDecoration: todo.completed ? 'line-through' : 'none' }}>
              {todo.title}
            </span>
            <button onClick={() => deleteTodo(todo.id)}>Delete</button>
          </li>
        ))}
      </ul>
    </div>
  );
}

Filtering Data

Section titled “Filtering Data”
// Fetch all, then filter client-side
const allProducts = await db.collection<Product>('products').get();


const inStock = allProducts.filter(p => p.inStock);
const affordable = allProducts.filter(p => p.price < 50);
const tools = allProducts.filter(p => p.category === 'tools');

Storage Costs

Section titled “Storage Costs”
  • Beta: Free with shared development credentials
  • Production: Included with your Varity deployment (provisioned automatically)
Advanced: Custom Database Configuration

The db singleton auto-configures from environment variables. For custom setups, create your own Database instance:

import { Database } from '@varity-labs/sdk';


const customDb = new Database({
  proxyUrl: 'https://your-proxy.example.com',
  appToken: 'your-jwt-token',
});


const records = await customDb.collection('items').get();

Environment variables (auto-detected by the SDK):

VariableFrameworkPurpose
NEXT_PUBLIC_VARITY_DB_PROXY_URLNext.jsDatabase proxy URL
NEXT_PUBLIC_VARITY_APP_TOKENNext.jsApp authentication token
VITE_VARITY_DB_PROXY_URLViteDatabase proxy URL
VITE_VARITY_APP_TOKENViteApp authentication token
REACT_APP_VARITY_DB_PROXY_URLCRADatabase proxy URL
REACT_APP_VARITY_APP_TOKENCRAApp authentication token

When you deploy with varitykit deploy, these are set automatically.

Next Steps

Section titled “Next Steps”