NukeBase

Connecting to External Databases

If you need to connect to another NukeBase database from your server (for example, a shared service or microservice architecture), you can use the sys/serversdk.js module.

When to use serversdk.js:

  • Connecting to a separate NukeBase instance
  • Building microservices that communicate with each other
  • Aggregating data from multiple database servers
  • Server-to-server real-time synchronization
Using serversdk.js to connect to another database
module.exports = ({ get, set, update, addCallable, startDB, addDomain, ... }) => {

  // Import the server SDK for external connections
  const path = require('path');
  const createServerClient = require('../sys/serversdk.js');

  // Connect to an external NukeBase database
  // Note: External connections ARE async (like client-side)
  // The second argument is REQUIRED: a JSON file holding { uid, token } for the
  // session to connect as. Use a build token (dashboard → Signed-in devices →
  // Create build token) for the account that owns the other project; keep the
  // file out of public/. The SDK sends them as cookies.
  createServerClient('wss://other-project.nukebase.com',
                     path.join(__dirname, 'external-session.json')).then(externalDb => {
    console.log('Connected to external database');

    // Use the external database with async operations
    addCallable("getExternalData", async function(data, admin, sessionId) {
      // Local database (sync)
      const localUser = get(["users", admin.uid]);

      // External database (async - requires await)
      const externalData = await externalDb.get(["sharedData", data.itemId]);

      return {
        local: localUser.data,
        external: externalData.data
      };
    });

    // Subscribe to changes on external database
    externalDb.getSub({
      event: "value@",
      path: ["notifications"]
    }, (event) => {
      // When external data changes, update local database
      set(["cache", "externalNotifications"], event.data);
    });

  }).catch(err => {
    console.error('Failed to connect to external database:', err);
  });

  // Set up local domain
  const nukebase = addDomain({
    authPath: ["users"]
  });

  startDB(nukebase);
};

Important differences:

  • Local operations (via destructured get, set, etc.) are synchronous
  • External operations (via serversdk.js) are asynchronous and require await

This is because external connections go over the network via WebSocket, just like client connections.

serversdk.js covers the data operations, subscriptions, callableFunction and the auth endpoints. It has no file methods (use fetch against /_file/… with the session cookies) and no request timeout — a request the remote never answers stays pending.

↑