Migration Guide

This guide helps you migrate from other embedded databases to NebulaDB.

Migrating from LokiJS

Concept Mapping

LokiJS	NebulaDB	Notes
`new Loki()`	`createDb()`	Database creation
`db.addCollection()`	`db.collection()`	Collection creation
`collection.insert()`	`collection.insert()`	Similar API
`collection.find()`	`collection.find()`	Similar query syntax
`collection.update()`	`collection.update()`	MongoDB-style operators
`collection.remove()`	`collection.delete()`	Different method name
`collection.chain()`	N/A	Use native JavaScript
`collection.observeChanges()`	`collection.subscribe()`	Different API

Migration Script

const loki = require('lokijs');
import { createDb } from '@nebula/core';
import { FileSystemAdapter } from '@nebula/adapter-filesystem';

async function migrateFromLokiJS(lokiPath, nebulaPath) {
  const lokiDb = new loki(lokiPath);
  await new Promise(resolve => { lokiDb.loadDatabase({}, resolve); });
  const nebulaDb = createDb({ adapter: new FileSystemAdapter(nebulaPath) });
  lokiDb.collections.forEach(async (lokiCollection) => {
    const collectionName = lokiCollection.name;
    const nebulaCollection = nebulaDb.collection(collectionName);
    const documents = lokiCollection.find();
    for (const doc of documents) {
      const { $loki, meta, ...data } = doc;
      await nebulaCollection.insert({
        ...data, id: $loki.toString(),
        createdAt: meta.created ? new Date(meta.created).toISOString() : undefined,
        updatedAt: meta.updated ? new Date(meta.updated).toISOString() : undefined
      });
    }
  });
  await nebulaDb.save();
  console.log('Migration completed successfully!');
}

Migrating from PouchDB

Concept Mapping

PouchDB	NebulaDB	Notes
`new PouchDB()`	`createDb()`	Database creation
`db.put()`	`collection.insert()`	Different API
`db.get()`	`collection.findOne()`	Different API
`db.allDocs()`	`collection.find()`	Different API
`db.changes()`	`collection.subscribe()`	Different API
`db.replicate()`	N/A	No built-in replication

Migration Script

const PouchDB = require('pouchdb');
import { createDb } from '@nebula/core';
import { IndexedDBAdapter } from '@nebula/adapter-indexeddb';

async function migrateFromPouchDB(pouchDbName, nebulaDbName) {
  const pouchDb = new PouchDB(pouchDbName);
  const nebulaDb = createDb({ adapter: new IndexedDBAdapter(nebulaDbName) });
  const result = await pouchDb.allDocs({ include_docs: true });
  const docsByType = {};
  for (const row of result.rows) {
    const doc = row.doc;
    if (doc._id.startsWith('_design/')) continue;
    let type = doc.type || 'documents';
    if (!docsByType[type]) docsByType[type] = [];
    const { _id, _rev, type: docType, ...data } = doc;
    docsByType[type].push({ id: _id.includes(':') ? _id.split(':')[1] : _id, ...data });
  }
  for (const [type, docs] of Object.entries(docsByType)) {
    const collection = nebulaDb.collection(type);
    for (const doc of docs) { await collection.insert(doc); }
    console.log(`Migrated ${docs.length} documents to ${type} collection`);
  }
  await nebulaDb.save();
}

Migrating from Lowdb

Concept Mapping

Lowdb	NebulaDB	Notes
`new Low()`	`createDb()`	Database creation
`db.data.users`	`db.collection('users')`	Collection access
`db.data.users.push()`	`collection.insert()`	Different API
`db.data.users.filter()`	`collection.find()`	Different API
`db.write()`	`db.save()`	Similar API
N/A	`collection.subscribe()`	No reactivity in Lowdb

const { Low } = require('lowdb');
const { JSONFile } = require('lowdb/node');
import { createDb } from '@nebula/core';
import { FileSystemAdapter } from '@nebula/adapter-filesystem';

async function migrateFromLowdb(lowdbPath, nebulaPath) {
  const adapter = new JSONFile(lowdbPath);
  const lowDb = new Low(adapter);
  await lowDb.read();
  const nebulaDb = createDb({ adapter: new FileSystemAdapter(nebulaPath) });
  for (const [collectionName, documents] of Object.entries(lowDb.data)) {
    if (!Array.isArray(documents)) continue;
    const collection = nebulaDb.collection(collectionName);
    for (const doc of documents) {
      if (!doc.id) doc.id = Math.random().toString(36).substr(2, 9);
      await collection.insert(doc);
    }
    console.log(`Migrated ${documents.length} documents to ${collectionName} collection`);
  }
  await nebulaDb.save();
}

General Migration Tips

Plan Your Data Model: Review your current data model and consider improvements
Migrate in Phases: For large datasets, migrate one collection at a time
Test Thoroughly: Test your migration process with a subset of data first
Validate Data: Verify that all data was migrated correctly
Update Queries: Adapt your queries to NebulaDB's syntax
Consider Indexing: Add appropriate indexes for your common queries
Run in Parallel: Consider running both databases in parallel during the transition