AxioDB Logo
AxioDB Docs
NEW FEATURE

AxioDBCloud

Remote Database Access Made Simple

Deploy AxioDB in Docker or Cloud. Connect from anywhere with the same API you already know. Zero code changes, production-ready TCP protocol, automatic reconnection.

Why AxioDBCloud?

Zero Code Changes

Use the exact same API as embedded AxioDB. Just change from new AxioDB() to new AxioDBCloud()

Deploy Anywhere

Docker, AWS, Azure, Google Cloud, DigitalOcean, or your own servers. One instance, unlimited clients.

Auto-Reconnect

Built-in exponential backoff reconnection. Up to 10 retry attempts. Your app stays resilient.

Production Ready

1000+ concurrent connections, heartbeat monitoring, request correlation, connection pooling.

Server Setup

Option 1: Docker (Recommended)

The easiest way to deploy AxioDB with TCP access. Full instructions — simpledocker runquick start, then advanced env vars, volumes, and Compose — live on the dedicated Docker page:

Docker Deployment Guide

Option 2: Node.js Application

Using this config, you can expose an AxioDB instance running inside one service (Service A) so it can be reached over TCP from another service (Service B) using the AxioDBCloud client — no shared filesystem, no HTTP layer, just a direct TCP connection between processes:

javascript
1const { AxioDB } = require('axiodb');
2

3// Service A: the process that owns the data, exposed for other services to reach
4const db = new AxioDB({
5  GUI: false,              // GUI (optional)
6  RootName: 'MyDatabase',  // Root database name
7  CustomPath: './data',    // Data directory
8  TCP: true                // Enable TCP server
9});
10

11// Server automatically starts on port 27019
12console.log('AxioDB TCP Server running on port 27019');

Default Port: TCP server listens on port 27019 (HTTP GUI uses 27018). Service B then connects with new AxioDBCloud("axiodb://service-a-host:27019") — see Client Usage below.

Client Usage

Basic Connection

javascript
1const { AxioDBCloud } = require('axiodb');
2

3// Connect to remote AxioDB server
4const client = new AxioDBCloud("axiodb://localhost:27019");
5

6// Establish connection
7await client.connect();
8

9// Use exactly like embedded AxioDB!
10const db = await client.createDB("ProductionDB");
11const users = await db.createCollection("Users");
12

13// All operations work identically
14await users.insert({ name: "Alice", email: "[email protected]" });
15

16const results = await users.query({ name: "Alice" })
17  .Limit(10)
18  .Skip(0)
19  .Sort({ createdAt: -1 })
20  .exec();
21

22console.log(results);
23

24// Disconnect when done
25await client.disconnect();

Connection String Format

axiodb://[host]:[port]
  • • Local: axiodb://localhost:27019
  • • Remote: axiodb://192.168.1.100:27019
  • • Cloud: axiodb://mydb.example.com:27019

Advanced Options

javascript
1const client = new AxioDBCloud("axiodb://localhost:27019", {
2  timeout: 30000,           // Request timeout (ms)
3  reconnectAttempts: 10,    // Max reconnect attempts
4  reconnectDelay: 1000,     // Initial delay (ms)
5  heartbeatInterval: 30000, // Heartbeat every 30s
6  username: 'admin',        // Only needed if the server has TCPAuth: true
7  password: 'admin',
8});

TCP Authentication (NEW!)

TCP connections are unauthenticated by default (unchanged from before). Opt in with TCPAuth: true to require a username/password on every connection - it reuses the exact same accounts and roles as the GUI Control Server's RBAC system, so there's only one set of credentials to manage.

Server

javascript
1const db = new AxioDB({
2  TCP: true,
3  TCPAuth: true,           // Require authentication on every TCP connection
4  RootName: 'MyDatabase',
5  CustomPath: './data',
6});

Client

javascript
1// Pass credentials in the constructor options - connect() authenticates automatically
2const client = new AxioDBCloud("axiodb://localhost:27019", {
3  username: 'admin',
4  password: 'admin',
5});
6await client.connect();
7

8console.log(client.authenticatedUser);
9// { username: 'admin', role: 'Super Admin', mustChangePassword: false }
10

11// Or authenticate after connecting (e.g. credentials supplied at runtime)
12const client2 = new AxioDBCloud("axiodb://localhost:27019");
13await client2.connect();
14await client2.login('admin', 'admin');

What's enforced

  • • Every command except PING/DISCONNECT/AUTHENTICATE requires a prior successful login on that connection
  • • Same role permissions as the GUI, checked per command (e.g. a View-role user gets 403 on CREATE_DB)
  • • Shared per-IP login rate limiter with the GUI: 5 failed attempts in 15 minutes locks that IP out for 15 minutes (429)
  • • Accounts still needing their forced password change are rejected outright (403) - complete it via the GUI first
  • • A password reset, role change, or deletion via the GUI immediately forces an already-open TCP connection to re-authenticate

Known limitations

  • • The TCP protocol itself is unencrypted (no TLS) - use a private network, VPN, or your own TLS termination for untrusted networks
  • • No TCP command exists yet to change a password - that must go through the GUI

Complete API Examples

CRUD Operations

javascript
1// Insert single document
2await users.insert({ name: "Bob", age: 30 });
3

4// Insert multiple documents
5await users.insertMany([
6  { name: "Charlie", age: 25 },
7  { name: "Diana", age: 28 }
8]);
9

10// Query documents
11const adults = await users.query({ age: { $gte: 18 } })
12  .Limit(10)
13  .Sort({ age: -1 })
14  .exec();
15

16// Update document
17await users.update({ name: "Bob" }).UpdateOne({ age: 31 });
18

19// Delete document
20await users.delete({ name: "Charlie" }).deleteOne();
21

22// Aggregation
23const stats = await users.aggregate([
24  { $match: { age: { $gte: 25 } } },
25  { $group: { _id: null, avgAge: { $avg: "$age" } } }
26]).exec();

Real-World Example: E-commerce App

javascript
1const { AxioDBCloud } = require('axiodb');
2

3async function main() {
4  // Connect to production database
5  const client = new AxioDBCloud("axiodb://prod.example.com:27019");
6  await client.connect();
7

8  const db = await client.createDB("EcommerceDB");
9  const products = await db.createCollection("Products");
10  const orders = await db.createCollection("Orders");
11

12  // Add new product
13  await products.insert({
14    sku: "LAPTOP-001",
15    name: "Gaming Laptop",
16    price: 1299.99,
17    stock: 15,
18    category: "Electronics"
19  });
20

21  // Get low stock products
22  const lowStock = await products.query({ stock: { $lt: 10 } })
23    .Sort({ stock: 1 })
24    .exec();
25

26  console.log("Low stock products:", lowStock.data.documents);
27

28  // Create order
29  await orders.insert({
30    orderId: "ORD-12345",
31    customerId: "USER-001",
32    items: [{ sku: "LAPTOP-001", quantity: 1 }],
33    total: 1299.99,
34    status: "pending"
35  });
36

37  // Get today's orders
38  const today = new Date().toISOString().split('T')[0];
39  const todayOrders = await orders.query({
40    createdAt: { $regex: today }
41  }).exec();
42

43  console.log("Today's orders:", todayOrders.data.documents.length);
44

45  await client.disconnect();
46}
47

48main().catch(console.error);

Features & Capabilities

35+ Commands

Full CRUD, aggregation, indexing support

Optional Auth (NEW!)

Shared RBAC with the GUI, per-IP rate limiting

Auto-Reconnect

Exponential backoff with 10 retry attempts

Heartbeat

PING/PONG every 30 seconds

Connection Pool

1000+ concurrent connections

Fast Protocol

Binary JSON with 4-byte length prefix

TypeScript

Full type definitions included

Perfect For

Microservices

Share one AxioDB instance across multiple services

Desktop Apps

Electron apps connecting to local or remote database

Cloud Deployments

Deploy to AWS, Azure, Google Cloud, DigitalOcean

Ready to Get Started?

Deploy AxioDB in minutes and start connecting from anywhere.

Installation GuideAPI Reference