{"id":16525,"library":"s3db.js","title":"s3db.js: S3 Document Database ORM","description":"s3db.js transforms AWS S3 into a powerful, cost-effective document database by leveraging S3's metadata capabilities to store document data up to 2KB per object, providing a serverless ORM-like interface. Currently at version 21.6.2, the library maintains an active release cadence with frequent patch and minor updates, indicating ongoing development and feature expansion. It differentiates itself by offering automatic encryption, schema validation, a streaming API for efficient data handling, and an extensive plugin architecture that supports multi-backend operations, including `RedDBClient` and integration with various other AWS services and external databases. Designed for serverless applications, cost-conscious projects, and rapid prototyping, it aims to reduce database management overhead. While its core leverages S3 for storage, its `DatabaseManager` allows integration with alternative storage backends and services, making it a flexible solution for diverse cloud data needs.","status":"active","version":"21.6.2","language":"javascript","source_language":"en","source_url":"https://github.com/forattini-dev/s3db.js","tags":["javascript","s3","aws","database","orm","nosql","document-store","cloud-database","metadata-encoding","typescript"],"install":[{"cmd":"npm install s3db.js","lang":"bash","label":"npm"},{"cmd":"yarn add s3db.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add s3db.js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for core S3 interactions, despite not being listed directly in the provided peerDependencies, it is an implicit dependency for S3 database functionality.","package":"@aws-sdk/client-s3","optional":false},{"reason":"s3db.js supports a wide array of AWS services and other data backends via its plugin architecture. Users must install specific client packages (e.g., `@aws-sdk/client-lambda`, `@google-cloud/bigquery`, `pg`) only for the features or plugins they intend to use.","package":"Various @aws-sdk/client-* packages","optional":true}],"imports":[{"note":"The library primarily uses ESM imports, especially with its Node.js >=24 engine requirement. DatabaseManager is the entry point for configuring and managing various backends.","wrong":"const { DatabaseManager } = require('s3db.js');","symbol":"DatabaseManager","correct":"import { DatabaseManager } from 's3db.js';"},{"note":"Model is the base class for defining your document schemas and interacting with S3 documents via an ORM-like interface.","wrong":"import Model from 's3db.js'; // Model is a named export","symbol":"Model","correct":"import { Model } from 's3db.js';"},{"note":"Used within Model schemas to define document attributes, including validation rules, types, and constraints.","symbol":"Field","correct":"import { Field } from 's3db.js';"}],"quickstart":{"code":"import { DatabaseManager, Model, Field } from 's3db.js';\nimport { S3Client } from '@aws-sdk/client-s3';\n\n// Initialize AWS S3 Client with credentials from environment variables\nconst s3Client = new S3Client({\n  region: process.env.AWS_REGION ?? 'us-east-1',\n  credentials: {\n    accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '', \n    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',\n  },\n});\n\n// Configure DatabaseManager for the S3 backend\nconst dbManager = new DatabaseManager({\n  backends: {\n    s3: {\n      type: 's3',\n      client: s3Client,\n      bucketName: process.env.S3_BUCKET_NAME ?? 'my-s3db-test-bucket',\n      prefix: 'my-app-data/', // Optional: prefix for keys within the bucket\n    },\n  },\n  defaultBackend: 's3',\n});\n\n// Define a User Model with a schema\nclass User extends Model {\n  static schema = {\n    id: Field.id(), // Primary key\n    name: Field.string({ required: true, maxLength: 100 }),\n    email: Field.string({ required: true, unique: true, validator: (v: string) => v.includes('@') }),\n    age: Field.number({ min: 18, max: 120, optional: true }),\n    isActive: Field.boolean({ default: true }),\n    createdAt: Field.timestamp({ auto: true }),\n  };\n\n  constructor(data?: any, options?: any) {\n    super(data, { ...options, dbManager, backend: 's3' });\n  }\n}\n\nasync function runS3DBExample() {\n  // Ensure S3 bucket exists and credentials are valid.\n  await dbManager.connect();\n  console.log('Connected to S3DB backend.');\n\n  try {\n    // 1. Create a new user\n    const newUser = new User({\n      name: 'Alice Wonderland',\n      email: 'alice@example.com',\n      age: 30,\n    });\n    const createdUser = await newUser.insert();\n    console.log('Created User:', createdUser.toObject());\n\n    // 2. Find a user by ID\n    const foundUser = await User.findById(createdUser.id); // Static method for finding by ID\n    if (foundUser) {\n      console.log('Found User by ID:', foundUser.toObject());\n\n      // 3. Update the user\n      foundUser.age = 31;\n      foundUser.isActive = false;\n      const updatedUser = await foundUser.update();\n      console.log('Updated User:', updatedUser.toObject());\n    }\n\n    // 4. List all users (note: for S3 metadata, complex queries might involve scanning)\n    const allUsers = await User.findMany({}); // Fetches all documents under the model's prefix\n    console.log(`Total users found: ${allUsers.length}`);\n    if (allUsers.length > 0) {\n      console.log('First user from findMany:', allUsers[0].toObject());\n    }\n\n    // 5. Delete the user\n    if (foundUser) {\n      await foundUser.delete();\n      console.log(`Deleted User with ID: ${foundUser.id}`);\n    }\n\n  } catch (error) {\n    console.error('Error during S3DB operations:', error);\n  } finally {\n    // In S3's stateless nature, explicit disconnects are often not needed, \n    // but a manager might offer a cleanup method.\n  }\n}\n\nrunS3DBExample();","lang":"typescript","description":"This quickstart demonstrates how to initialize `s3db.js` with an S3 backend, define a `Model` with a schema, and perform basic CRUD operations (create, find, update, delete) on document data."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 24 or higher: `nvm install 24 && nvm use 24` or `fnm install 24 && fnm use 24`.","message":"s3db.js requires Node.js version 24 or newer. Older Node.js versions will result in runtime errors due to reliance on modern JavaScript features.","severity":"breaking","affected_versions":">=21.0.0"},{"fix":"Install the S3 client: `npm install @aws-sdk/client-s3`.","message":"Core S3 functionality implicitly requires `@aws-sdk/client-s3`. While s3db.js lists many other `@aws-sdk/client-*` packages as peer dependencies for its various plugins, `@aws-sdk/client-s3` is fundamental for interacting with S3 itself and must be installed separately.","severity":"gotcha","affected_versions":">=21.0.0"},{"fix":"For documents exceeding 2KB, utilize s3db.js's custom behaviors or plugins designed to store larger content in the S3 object's body, rather than its metadata, and link it to the metadata entry. Review the official documentation on handling large documents.","message":"s3db.js stores document data directly within S3 object metadata. This imposes a strict 2KB size limit per document. Attempting to store larger documents will lead to data truncation or errors.","severity":"gotcha","affected_versions":">=21.0.0"},{"fix":"Carefully review your project's `package.json` and install only the `peerDependencies` that align with your required `s3db.js` integrations. For instance, if only using S3, you generally only need `@aws-sdk/client-s3`.","message":"The package lists a vast number of peer dependencies for various AWS services and other data stores (e.g., BigQuery, Redis, PostgreSQL). Users should only install the specific peer dependencies corresponding to the `s3db.js` plugins or features they are actively using to avoid unnecessary package bloat.","severity":"gotcha","affected_versions":">=21.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { DatabaseManager } from 's3db.js';` and that your project is configured for ESM. Check `tsconfig.json` for `moduleResolution` and `module` settings, and `package.json` for `\"type\": \"module\"` if running directly with Node.js.","cause":"Using CommonJS require syntax for `s3db.js` which is primarily an ESM module, or an incorrect module resolution in build tools.","error":"TypeError: (0 , import_s3db.DatabaseManager) is not a constructor"},{"fix":"Set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` environment variables, or pass them directly to the `S3Client` constructor. Ensure the credentials have necessary S3 permissions for the specified bucket.","cause":"The S3Client or DatabaseManager was initialized without valid AWS credentials (access key ID, secret access key) or a specified region. This commonly occurs in development environments.","error":"Error: Missing AWS credentials in config"},{"fix":"Refactor your document schema to store large data fields in the S3 object body instead of metadata. s3db.js typically offers mechanisms (like 'text' field type with deflate compression, or custom behaviors) to manage larger content. Consult the library's documentation for strategies on handling oversized documents.","cause":"Attempted to `insert` or `update` a document whose serialized data, when stored in S3 metadata, exceeds the 2KB limit imposed by S3.","error":"Error: Document size exceeds S3 metadata limit. Max 2KB allowed."},{"fix":"Verify that the `bucketName` in your `DatabaseManager` configuration is correct and that the S3 bucket exists. Ensure your AWS IAM user/role has the appropriate S3 permissions for the specified bucket.","cause":"The S3 bucket specified in the `DatabaseManager` configuration does not exist, or the provided AWS credentials lack the necessary permissions (e.g., `s3:PutObject`, `s3:GetObject`, `s3:DeleteObject`, `s3:ListBucket`) for the bucket.","error":"Error: 'my-s3db-test-bucket' not found or access denied."}],"ecosystem":"npm"}