sharded

library0.0.50jsnpmunverified

SQLite-based write buffer and caching system for Prisma that accelerates data operations by buffering writes and caching reads in local SQLite databases with automatic background sync to the main database via Redis/BullMQ. Current stable version 0.0.50, released weekly. Key differentiators: Prisma-first integration, multi-node master/worker architecture, automatic WAL optimizations, and CLI schema generation. Targets sub-10ms response times for high-frequency operations, but adds complexity and is not suited for low-throughput or simple CRUD apps.

database devops

npm install sharded

package ↗

INSTALL

IMPORT

SIG · SHARDED

sharded

databasejavascriptv0.0.50

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Sharded

✓ import { Sharded } from 'sharded'

✗ import Sharded from 'sharded'

Sharded is a named export, not default. ESM only.

generateSchema

✓ import { generateSchema } from 'sharded/cli'

✗ import { generateSchema } from 'sharded'

CLI functions are exported from 'sharded/cli', not main package.

ShardedConfig

✓ import type { ShardedConfig } from 'sharded'

✗ import { ShardedConfig } from 'sharded'

Type imports should use `import type` to avoid runtime inclusion.

Initializes Sharded with Prisma client, starts buffer/cache, performs a write and read, then stops. Demonstrates basic usage with Redis connection.

import { Sharded } from 'sharded'; import { PrismaClient } from '@prisma/client'; const prisma = new PrismaClient(); async function main() { const sharded = new Sharded({ prisma, redisUrl: process.env.REDIS_URL ?? 'redis://localhost:6379', blocks: ['User', 'Order'], schemaPath: './prisma/schema.prisma', dataDir: './prisma/blocks/data', }); await sharded.start(); // Write through buffer const user = await sharded.user.create({ data: { name: 'Alice', email: 'alice@example.com' }, }); // Read from cache const cachedUser = await sharded.user.findUnique({ where: { id: user.id }, }); console.log('User:', cachedUser); await sharded.stop(); } main().catch(console.error);

Debug

Known issues

breakingRequires Prisma 6.7.0 or higher. Older versions are incompatible.

fix

Update Prisma to >=6.7.0

affects: <0.0.50

gotchaWithout persisting the blocks data directory (e.g., in Docker), all cached data is lost on redeployment, causing full reloads.

fix

Mount a persistent volume at /app/prisma/blocks/data in Docker or use an external directory configured via dataDir.

affects: >=0.0.0

gotchaSharded uses SQLite WAL mode automatically. If the application crashes, residual WAL files may cause 'phantom data' on restart if not properly cleaned. Follow WAL optimization guide.

fix

Refer to WAL-OPTIMIZATIONS.md in the repository for handling crash recovery.

affects: <0.0.50

deprecatedThe 'blocks' configuration option is deprecated in favor of 'models' in v0.1.0 (not yet released).

fix

Use 'models' instead of 'blocks' when upgrading to v0.1.0+.

affects: >=0.0.50 <0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'sharded/cli'

Incorrect import path for CLI functions; using 'sharded' instead of 'sharded/cli'.

fix

Use import { generateSchema } from 'sharded/cli';

PrismaClientValidationError: Invalid `prisma.user.create()` invocation

Calling Prisma methods on Sharded instance without proper block/model definition.

fix

Ensure the model is included in the 'blocks' array when constructing Sharded.

Error: Redis connection refused - connect ECONNREFUSED 127.0.0.1:6379

Redis server is not running or REDIS_URL env var is not set correctly.

fix

Start Redis server or set REDIS_URL to a valid Redis connection string.

Error: SQLITE_BUSY: database is locked

Multiple processes/workers attempting to write to the same SQLite block database simultaneously.

fix

Use a single worker per block or implement external locking via Redis. Sharded is designed for single-node worker per block.

Upgrade

Version history

0.0.50latest on npm

Audit

Dependencies

prismarequiredSharded integrates directly with Prisma and requires Prisma schema for block generation

bullmqrequiredUsed for background synchronization queue management

redisrequiredRedis is required for BullMQ queue operations

Agent activity

13 hits · last 30 days

node