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 requireawait
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.