S3 Driver (Experimental)

@hedystia/db includes an experimental s3 driver which stores records as JSON lines inside an AWS S3-compatible bucket (like AWS S3, Cloudflare R2, Minio, DigitalOcean Spaces, etc.).

This driver caches the state of the database locally in memory, and writes synchronization updates across the network, making it essentially a remote file database.

Warning

WARNING

The S3 driver is highly experimental. It is not designed to replace robust, relational databases like MySQL or PostgreSQL. It is best suited for ephemeral storage or light, slow-moving configuration data.

Installation

To use the S3 driver, you must install the official AWS S3 client:

bun add @aws-sdk/client-s3

To use the S3 driver, set the database type to "s3" and provide AWS credentials, an endpoint, a bucket name, and a prefix path.

import { database } from "@hedystia/db";
import { users } from "./schema";

const db = database({
  schemas: { users },
  database: "s3",
  connection: {
    bucket: "hedystia-test",
    endpoint: "s3.us-east-1.amazonaws.com",
    region: "us-east-1",
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    prefix: "production-data",
  },
  syncSchemas: true,
});

await db.initialize();

Behavior

During await db.initialize(), the driver attempts to pull the existing JSON lines from S3 over the network. When performing db.insert, db.update, or db.delete, operations persist the changed file state back into your cloud-hosted S3 bucket, overwriting the object entirely.