Fonctionnalités
Tarifs Technologie Feuille de route Docs
Se connecter
Commencer
English Deutsch Français Italiano العربية

Platform Services

Maravilla provides three built-in platform services that give your application persistent storage without managing infrastructure. Every service is accessed through a single entry point and works identically in development and production.

Accessing Platform Services

All services are available through the getPlatform() helper from @maravilla-labs/platform:

import { getPlatform } from '@maravilla-labs/platform';

const platform = getPlatform();

// KV Store — fast key-value storage
await platform.env.KV.myapp.put('key', 'value');

// Database — document queries
await platform.env.DB.find('users', { active: true });

// Storage — object/file storage with presigned URLs
await platform.env.STORAGE.put('uploads/photo.jpg', fileData);

The Three Services

KV Store

A namespaced key-value store for fast reads and writes. Ideal for session data, feature flags, caching, and any data that maps naturally to key-value pairs. Supports optional TTL-based expiration and prefix-based listing with cursor pagination.

// Store and retrieve a value
await platform.env.KV.sessions.put('user:abc', JSON.stringify({ role: 'admin' }));
const session = JSON.parse(await platform.env.KV.sessions.get('user:abc'));

Database

A document database with a powerful query API. Supports comparison, logical, and element operators for filtering, plus sort, limit, and skip for pagination. Write queries once — the platform handles everything.

// Insert and query documents
await platform.env.DB.insertOne('products', {
  name: 'Widget',
  price: 29.99,
  inStock: true
});

const affordable = await platform.env.DB.find('products', {
  price: { $lte: 50 },
  inStock: true
}, { sort: { price: 1 }, limit: 20 });

Storage

Object storage for files of any size. Supports direct server uploads, presigned URLs for browser-to-storage uploads, download URL generation, and file metadata.

// Upload a file
await platform.env.STORAGE.put('reports/q1.pdf', pdfBuffer, {
  contentType: 'application/pdf',
  metadata: { generatedBy: 'reporting-service' }
});

// Generate a temporary download link
const { url } = await platform.env.STORAGE.generateDownloadUrl('reports/q1.pdf', 3600);

Development vs Production

In development, the CLI runs the full platform locally. In production, Maravilla Cloud handles everything. Your code works identically in both environments.

// This query works the same in development and production
await platform.env.DB.find('users', { age: { $gte: 18 }, active: true });

You never need to worry about the underlying infrastructure — just write your code once and it runs everywhere.

Tenant Isolation

All platform services enforce automatic tenant isolation. Every operation is scoped to the current tenant without any extra code on your part.

// Your code:
await platform.env.DB.find('users', { active: true });

// What the platform actually executes:
// { active: true, _tenant_id: "current-tenant-id" }

This applies to all three services:

  • KV Store — keys are prefixed and isolated per tenant
  • Database — queries automatically include tenant ID filters
  • Storage — object keys are scoped to the tenant’s namespace

Cross-tenant data access is not possible through the API. Cursors are also validated to ensure they belong to the requesting tenant.

Multi-Layer Caching

In production, both the KV Store and Database benefit from an integrated multi-layer cache:

  1. L1 (in-process) — fast hot lookups within a single runtime instance
  2. L2 (distributed) — shared across all processes and nodes for cluster-wide coherence

Caching uses a versioned invalidation strategy: writes bump a version counter, making all previously cached entries instantly unreachable. This guarantees no stale data is ever served after a write. If the distributed cache is unavailable, the system operates without it transparently.

Next Steps