Complete Vaultbrix Documentation

Supabase-Compatible Behavior

Vaultbrix implements the complete Supabase stack:

Vaultbrix-Specific Features

Example: Same Code, Different Host

// This code works identically on Supabase and Vaultbrix
import { createClient } from '@supabase/supabase-js'

// Supabase
const supabase = createClient(
  'https://abc123.supabase.co',
  'your-anon-key'
)

// Vaultbrix - just change the URL
const vaultbrix = createClient(
  'https://abc123.vaultbrix.com',
  'your-anon-key'
)

// All operations work the same
const { data, error } = await vaultbrix
  .from('users')
  .select('*')
  .eq('active', true)

Step-by-Step Process

Your Connection Details

# Project URL
https://YOUR_PROJECT_REF.vaultbrix.com

# API Keys (Settings > API)
ANON_KEY=eyJhbGciOiJIUzI1NiIs...
SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIs...

# Direct Database Connection
postgresql://postgres:YOUR_PASSWORD@db.YOUR_PROJECT_REF.vaultbrix.com:5432/postgres

# Pooled Connection (recommended for serverless)
postgresql://postgres:YOUR_PASSWORD@db.YOUR_PROJECT_REF.vaultbrix.com:6543/postgres

Key Comparison

Correct Usage

// CLIENT-SIDE (React, Next.js pages, mobile)
// Use ANON key - safe to expose
const supabase = createClient(
  process.env.NEXT_PUBLIC_VAULTBRIX_URL,
  process.env.NEXT_PUBLIC_VAULTBRIX_ANON_KEY // Public env var
)

// SERVER-SIDE (API routes, cron jobs, admin scripts)
// Use SERVICE ROLE key - never expose
const adminClient = createClient(
  process.env.VAULTBRIX_URL,
  process.env.VAULTBRIX_SERVICE_ROLE_KEY // Private env var
)

Installation

# npm
npm install @supabase/supabase-js

# pnpm
pnpm add @supabase/supabase-js

# yarn
yarn add @supabase/supabase-js

Basic Setup

// lib/vaultbrix.ts
import { createClient } from '@supabase/supabase-js'

const vaultbrixUrl = 'https://YOUR_PROJECT_REF.vaultbrix.com'
const vaultbrixAnonKey = 'YOUR_ANON_KEY'

export const supabase = createClient(vaultbrixUrl, vaultbrixAnonKey)

// Usage
const { data, error } = await supabase
  .from('posts')
  .select('id, title, author:users(name)')
  .order('created_at', { ascending: false })
  .limit(10)

TypeScript Support

// Generate types from your schema
npx supabase gen types typescript \
  --project-id YOUR_PROJECT_REF \
  --schema public > types/database.ts

// Use typed client
import { createClient } from '@supabase/supabase-js'
import type { Database } from './types/database'

export const supabase = createClient<Database>(
  process.env.NEXT_PUBLIC_VAULTBRIX_URL!,
  process.env.NEXT_PUBLIC_VAULTBRIX_ANON_KEY!
)

// Now you get full autocomplete
const { data } = await supabase
  .from('posts')  // ← Autocompletes table names
  .select('*')    // ← Knows column types

Installation

npm install @supabase/supabase-js @supabase/ssr

Environment Variables

# .env.local
NEXT_PUBLIC_VAULTBRIX_URL=https://YOUR_PROJECT_REF.vaultbrix.com
NEXT_PUBLIC_VAULTBRIX_ANON_KEY=eyJhbGciOiJIUzI1NiIs...
VAULTBRIX_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIs...

Browser Client (Client Components)

// lib/vaultbrix/client.ts
import { createBrowserClient } from '@supabase/ssr'

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_VAULTBRIX_URL!,
    process.env.NEXT_PUBLIC_VAULTBRIX_ANON_KEY!
  )
}

Server Client (Server Components, Actions)

// lib/vaultbrix/server.ts
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'

export async function createClient() {
  const cookieStore = await cookies()

  return createServerClient(
    process.env.NEXT_PUBLIC_VAULTBRIX_URL!,
    process.env.NEXT_PUBLIC_VAULTBRIX_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll()
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            )
          } catch {
            // Called from Server Component - ignore
          }
        },
      },
    }
  )
}

Usage in Server Component

// app/posts/page.tsx
import { createClient } from '@/lib/vaultbrix/server'

export default async function PostsPage() {
  const supabase = await createClient()

  const { data: posts } = await supabase
    .from('posts')
    .select('*')
    .order('created_at', { ascending: false })

  return (
    <ul>
      {posts?.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

Valid Use Cases

Secure Usage Pattern

// lib/vaultbrix-admin.ts (server-only!)
import { createClient } from '@supabase/supabase-js'

export function createAdminClient() {
  return createClient(
    process.env.VAULTBRIX_URL!,
    process.env.VAULTBRIX_SERVICE_ROLE_KEY!
  )
}

// app/api/admin/users/[id]/route.ts
import { createAdminClient } from '@/lib/vaultbrix-admin'
import { checkAdminAuth } from '@/lib/auth'

export async function DELETE(req: Request, { params }: { params: { id: string } }) {
  // Verify caller is admin FIRST
  const isAdmin = await checkAdminAuth(req)
  if (!isAdmin) {
    return new Response('Unauthorized', { status: 401 })
  }

  // NOW safe to use service role
  const admin = createAdminClient()
  await admin.from('profiles').delete().eq('id', params.id)
  await admin.auth.admin.deleteUser(params.id)

  return new Response('User deleted', { status: 200 })
}

Key Rotation

Rotate your service role key immediately if compromised, and on a regular schedule (90 days recommended).

# Via Dashboard
Dashboard → Settings → API Keys → Rotate Service Role Key

# Via API
curl -X POST "https://api.vaultbrix.com/v1/projects/{id}/keys/rotate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"keyType": "service_role"}'

# Old key invalidated within 60 seconds
# Update all backend services immediately

Migration Approach

Vaultbrix uses local SQL files for migrations. Create migration files locally, then apply them via the Dashboard SQL Editor or API.

# Create a migrations folder in your project
mkdir -p migrations

# Create timestamped migration files
touch migrations/20260209_add_posts_table.sql

# Apply via Dashboard
Dashboard → Database → SQL Editor → paste and run

# Or use your Vaultbrix connection string directly
psql $VAULTBRIX_DATABASE_URL -f migrations/20260209_add_posts_table.sql

Creating Migrations

# Create a new migration
supabase migration new add_posts_table

# This creates: supabase/migrations/20260209123456_add_posts_table.sql
# Edit the file with your SQL:

-- supabase/migrations/20260209123456_add_posts_table.sql
CREATE TABLE posts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES auth.users(id) NOT NULL,
  title TEXT NOT NULL,
  content TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can CRUD own posts"
  ON posts FOR ALL
  USING (auth.uid() = user_id);

Applying Migrations

# Option 1: Dashboard SQL Editor (recommended)
Dashboard → Database → SQL Editor
Paste your migration SQL and click Run

# Option 2: Direct psql connection
psql $VAULTBRIX_DATABASE_URL -f migrations/20260209_add_posts_table.sql

# Option 3: Via API
curl -X POST "https://api.vaultbrix.com/v1/projects/{id}/sql" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"query": "CREATE TABLE posts (...)"}'

Architecture Comparison

Database: myapp_db
└── public (your tables)

✅ You own everything
✅ Full superuser access
✅ CREATE DATABASE allowed
✅ prisma db push works

Database: postgres (shared)
├── public (system)
├── auth (GoTrue)
├── storage (S3)
├── tenant_abc (Customer A)
└── tenant_xyz (Your schema)

✅ Full data isolation
✅ RLS enforced
⚠️ Limited DDL access

Common Prisma Errors

How to Run Schema Changes

-- Dashboard → Database → SQL Editor
-- Runs as service_role with full permissions

ALTER TABLE users ADD COLUMN avatar TEXT;
CREATE INDEX idx_users_email ON users(email);

# Generate migration SQL without applying
npx prisma migrate diff \
  --from-schema-datamodel ./prisma/schema.prisma \
  --to-migrations ./prisma/migrations \
  --script > migration.sql

# Then copy migration.sql content to Dashboard SQL Editor

Feature Comparison

Branching Workflow

# Create a branch via Dashboard
Dashboard → Database → Branches → Create Branch

# Or via API
curl -X POST "https://api.vaultbrix.com/v1/projects/{id}/branches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name": "feature-auth"}'

# Branch gets its own:
# - Full database copy (schema + data)
# - Unique connection string
# - Separate API keys

# Make changes safely on the branch
# Use the branch connection string in your dev environment

# When ready, merge via Dashboard
Dashboard → Branches → feature-auth → Merge to Production

# Clean up via Dashboard or API
Dashboard → Branches → feature-auth → Delete

Common Use Cases

Backup Types

PITR Retention by Plan

Restoring from Backup

# Via Dashboard (recommended)
Dashboard → Database → Backups → Point-in-Time Recovery

# Select a restore point from the timeline
# Choose to restore in-place or to a new branch

# Via API
curl -X POST "https://api.vaultbrix.com/v1/projects/{id}/restore" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "targetTime": "2026-02-09T14:30:00Z",
    "toBranch": "recovery-test"  // optional: restore to branch
  }'

Migration Steps

# Get your Supabase connection string from Settings > Database
pg_dump "postgresql://postgres:PASSWORD@db.xxxxx.supabase.co:5432/postgres" \
  --clean --if-exists \
  --exclude-schema=_supabase \
  --exclude-schema=supabase_migrations \
  > supabase_export.sql

psql "postgresql://postgres:PASSWORD@db.YOUR_PROJECT.vaultbrix.com:5432/postgres" \
  < supabase_export.sql

# Before (Supabase)
NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbG...

# After (Vaultbrix) - same variable names work!
NEXT_PUBLIC_SUPABASE_URL=https://YOUR_PROJECT.vaultbrix.com
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbG...

What Migrates Automatically