@iota-big3/sdk-database

> Enterprise-grade database abstraction layer for the IOTA Big3 SDK ecosystem


🎯 Core Competency

sdk-database serves as the central database abstraction layer for the entire IOTA Big3 SDK ecosystem, preventing database logic duplication across 29+ dependent packages. It provides a unified interface for multiple database paradigms while maintaining enterprise-grade reliability and performance.

🏆 DELEGATION COMPLIANCE: 100% COMPLETE

Historic Achievement: @iota-big3/sdk-database is the FIRST package in the 85-package IOTA Big3 SDK ecosystem to achieve 100% Delegation Compliance.

$3

- Events: 100% delegated to @iota-big3/sdk-events
- Caching: 100% delegated to @iota-big3/sdk-performance
- Logging: 100% delegated to @iota-big3/sdk-observability
- Focus: Pure database abstraction without duplication

$3

- ✅ No custom EventEmitter implementations
- ✅ No custom caching logic
- ✅ No custom logging implementations
- ✅ Clean separation of concerns

View Complete Delegation Documentation →

✨ Features

$3

- SQL Databases: PostgreSQL, MySQL, SQLite, MSSQL (via Knex.js)
- NoSQL: MongoDB with full document support
- Key-Value: Redis with caching patterns
- Graph: Neo4j for relationship data
- Time-Series: InfluxDB for metrics and IoT data

$3

- Connection Pooling: Automatic connection management with configurable pools
- Transaction Support: ACID compliance across supported databases
- Migration System: Version-controlled schema migrations
- Backup & Restore: Full, incremental, and differential backup strategies
- Encryption at Rest: Built-in data encryption support
- Multi-Region Replication: Geographic distribution and failover
- Read Replica Management: Load balancing for read operations
- Database Sharding: Horizontal scaling support
- Large Dataset Optimization: Streaming and batch processing

$3

- Chaos Engineering: Built-in failure injection for resilience testing
- Distributed Tracing: Request tracking across services
- Performance Monitoring: Real-time metrics and alerts
- Health Checks: Automated database health monitoring
- Circuit Breakers: Fault tolerance patterns

📦 Installation

``bash
npm install @iota-big3/sdk-database

Install specific driver dependencies as needed:


npm install pg # PostgreSQL
npm install mysql2 # MySQL
`

$3

This package follows "Delegation, Not Duplication" architecture:

`bash


Automatic delegation to specialized SDKs:

Events: @iota-big3/sdk-events (automatically included)

Caching: @iota-big3/sdk-performance (when needed)

Logging: @iota-big3/sdk-observability (when needed)

`

No additional dependencies required - delegation is handled through dependency injection patterns.

🚀 Quick Start

$3

`typescript
import { SDKDatabaseManager } from "@iota-big3/sdk-database";
import { createLogger } from "@iota-big3/sdk-observability";

// Initialize database manager
const db = new SDKDatabaseManager(
{
type: "postgres",
host: "localhost",
port: 5432,
database: "myapp",
user: "postgres",
password: "password",
pool: {
min: 2,
max: 10,
},
},
createLogger("database")
);

// Connect to database
await db.initialize();

// Execute queries
const users = await db.query("SELECT * FROM users WHERE active = ?", [true]);

// Use transactions
await db.transaction(async (trx) => {
await trx("users").insert({ name: "John Doe" });
await trx("audit_log").insert({ action: "user_created" });
});

// Monitor pool statistics
const stats = db.getPoolStats();
console.log(Connections: ${stats.used}/${stats.total});
`

$3

`typescript
import { driverFactory } from "@iota-big3/sdk-database";

// Create MongoDB driver
const mongoDriver = driverFactory.create({
type: "mongodb",
uri: "mongodb://localhost:27017/myapp",
});

await mongoDriver.connect();

// Perform operations
const result = await mongoDriver.execute({
collection: "users",
operation: "find",
filter: { active: true },
});
`

$3

`typescript
import { MigrationManager } from "@iota-big3/sdk-database";

const migrationManager = new MigrationManager(db, {
directory: "./migrations",
tableName: "migrations",
});

// Run pending migrations
await migrationManager.up();

// Rollback last migration
await migrationManager.down();

// Check migration status
const pending = await migrationManager.pending();
`

🔧 Advanced Features

$3

`typescript
import { MultiRegionReplicationManager } from "@iota-big3/sdk-database";

const replication = new MultiRegionReplicationManager({
regions: {
"us-east": { primary: true, endpoint: "db-us-east.example.com" },
"eu-west": { primary: false, endpoint: "db-eu-west.example.com" },
"ap-south": { primary: false, endpoint: "db-ap-south.example.com" },
},
replicationLag: 1000, // ms
failoverTimeout: 30000, // ms
});

// Monitor replication status
replication.on("lag_exceeded", (region, lag) => {
console.warn(Region ${region} lag: ${lag}ms);
});
`

$3

`typescript
import { ShardingManager } from "@iota-big3/sdk-database";

const sharding = new ShardingManager({
shards: [
{ id: "shard1", range: [0, 1000000] },
{ id: "shard2", range: [1000001, 2000000] },
],
shardKey: "user_id",
strategy: "range",
});

// Route queries to appropriate shard
const shard = sharding.getShard({ user_id: 123456 });
`

$3

`typescript
import { createBackupManager } from "@iota-big3/sdk-database";

const backupManager = createBackupManager();

// Create backup
const backup = await backupManager.createBackup(db, {
type: "full",
compression: true,
encryption: {
algorithm: "aes-256-cbc",
key: process.env.BACKUP_KEY,
},
storage: {
type: "s3",
path: "s3://backups/database",
},
});

// Schedule regular backups
backupManager.scheduleBackup(db, config, "0 2 *"); // 2 AM daily
`

$3

`typescript
import { ChaosEngineer, createChaosDriver } from "@iota-big3/sdk-database";

// Enable chaos testing in non-production
const chaos = new ChaosEngineer({
enabled: process.env.NODE_ENV === "staging",
failureRate: 0.1, // 10% failure rate
delayMs: { min: 100, max: 2000 },
});

// Wrap driver with chaos engineering
const chaosDriver = createChaosDriver(originalDriver, chaos);

// Monitor chaos events
chaos.on("failure", (event) => {
console.log("Chaos failure injected:", event);
});
`

📊 Performance Optimization

$3

`typescript
import { LargeDatasetOptimizer } from "@iota-big3/sdk-database";

const optimizer = new LargeDatasetOptimizer(db);

// Stream large results
await optimizer.streamQuery(
"SELECT * FROM large_table",
async (row) => {
// Process each row
await processRow(row);
},
{ batchSize: 1000 }
);

// Parallel processing
await optimizer.parallelScan("users", {
concurrency: 4,
processor: async (batch) => {
// Process batch of users
},
});
`

🔌 Integration with SDK Ecosystem

$3

- @iota-big3/sdk-types: Shared type definitions
- @iota-big3/sdk-events: Event-driven patterns
- @iota-big3/sdk-observability: Logging and monitoring
- @iota-big3/sdk-auth: User authentication storage
- @iota-big3/sdk-cache: Query result caching

$3

- sdk-auth - User credentials and sessions
- sdk-analytics - Metrics and analytics data
- sdk-billing - Financial records
- sdk-compliance - Audit trails
- sdk-education - Student records
- And many more...

API

📚 API Reference

$3

`typescript
class SDKDatabaseManager {
constructor(config: DatabaseConfig, logger?: Logger);

// Lifecycle
initialize(): Promise;
close(): Promise;

// Queries
query(sql: string, params?: unknown[]): Promise;
transaction(callback: (trx: Transaction) => Promise): Promise;

// Monitoring
getPoolStats(): PoolStats;
healthCheck(): Promise;
}
`

$3

All drivers implement the DatabaseDriver interface:

`typescript
interface DatabaseDriver {
connect(): Promise;
disconnect(): Promise;
execute(query: unknown): Promise;
healthCheck(): Promise;
getMetrics(): Promise;
}
`

🧪 Testing

`bash


Run tests

npm test

Run tests with coverage

npm run test:coverage

Run integration tests (requires databases)

npm run test:integration
`

🔐 Security

- Encryption at Rest: Built-in support for data encryption
- Connection Security: SSL/TLS support for all connections
- Query Parameterization: Automatic SQL injection prevention
- Audit Logging: Full query audit trail support

🤝 Contributing

This package follows the IOTA Big3 SDK contribution guidelines. Key principles:

1. Don't duplicate - Check if feature exists in other packages
2. Maintain compatibility - Don't break existing APIs
3. Add tests - All features must have test coverage
4. Document changes - Update this README and inline docs

📈 Performance Benchmarks

| Operation | PostgreSQL | MongoDB | Redis | Neo4j |
| ------------------ | ---------- | ------- | ----- | ----- |
| Single Insert | 2ms | 3ms | 1ms | 5ms |
| Bulk Insert (1000) | 45ms | 38ms | 12ms | 89ms |
| Simple Query | 1ms | 2ms | <1ms | 3ms |
| Complex Join | 15ms | N/A | N/A | 25ms |
| Transaction | 5ms | 8ms | 2ms | 12ms |

🔧 Configuration

$3

`bash


Connection pooling

DB_POOL_MIN=2
DB_POOL_MAX=10
DB_POOL_IDLE_TIMEOUT=30000

Performance

DB_QUERY_TIMEOUT=30000
DB_STATEMENT_TIMEOUT=60000

Monitoring

DB_SLOW_QUERY_THRESHOLD=1000
DB_METRICS_INTERVAL=60000
``

📝 License

MIT - See LICENSE for details

🔗 Links

- Full Documentation
- API Reference
- Examples
- Migration Guide
- Performance Tuning

---

Part of the IOTA Big3 SDK Ecosystem - Enterprise-ready, production-tested, delegation-first.