Client Usage

Basic connection#

const { AxioDBCloud } = require('axiodb');
 
const client = new AxioDBCloud("axiodb://localhost:27019");
await client.connect();
 
// Use exactly like embedded AxioDB
const db = await client.createDB("ProductionDB");
const users = await db.createCollection("Users");
 
await users.insert({ name: "Alice", email: "alice@example.com" });
 
const results = await users.query({ name: "Alice" })
  .Limit(10)
  .Skip(0)
  .Sort({ createdAt: -1 })
  .exec();
 
await 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#

const client = new AxioDBCloud("axiodb://localhost:27019", {
  timeout: 30000,           // Request timeout (ms)
  reconnectAttempts: 10,    // Max reconnect attempts
  reconnectDelay: 1000,     // Initial delay (ms)
  heartbeatInterval: 30000, // Heartbeat every 30s
  maxPoolSize: 10,          // Concurrent connections (default: 10)
  username: 'admin',        // Only needed if the server has TCPAuth: true
  password: 'admin',
});

How the connection pool works#

Each pool member is a socket, and the server holds one socket per connected client — both count against the OS's open-file-descriptor limit (ulimit -n, often 1024 by default on Linux). At the default pool size that's enough for roughly 100 clients before the server starts refusing new connections. Deploying toward 1,000+ concurrent connections means raising that limit (ulimit -n 65536, or docker run --ulimit nofile=65536:65536) rather than raising maxPoolSize per client.

The server also caps concurrent connections at 100 per remote IP, independent of the global 1,000-connection budget, checked at connect time before authentication — a single misbehaving client can't claim the entire server pool. A single client at the default maxPoolSize: 10 is nowhere near this limit.

If maxPoolSize asks for more connections than the server allows, connect() doesn't reject outright — it resolves as long as at least one pool member connected, and emits a poolDegraded event:

client.on('poolDegraded', ({ requested, connected, failed, errors }) => {
  console.warn(`Pool came up smaller than requested: ${connected}/${requested} connected, ${failed} failed`);
});
 
await client.connect(); // resolves even if some pool members were rejected

The one exception: if the very first connection in the pool fails, connect() rejects entirely — that's the signal the server is unreachable or the credentials are invalid.

Rate limiting on connection attempts#

The 100-per-IP cap only bounds concurrent connections. A separate per-IP rate limiter tracks connection attempts (successful or rejected) in a trailing 10-second window; once an IP crosses 300 attempts, every new connection from it is rejected with a 429 for the next 30 seconds. A normal client — even one repeatedly reconnecting a full maxPoolSize: 10 pool — is nowhere near this threshold.

E-commerce example#

const { AxioDBCloud } = require('axiodb');
 
async function main() {
  const client = new AxioDBCloud("axiodb://prod.example.com:27019");
  await client.connect();
 
  const db = await client.createDB("EcommerceDB");
  const products = await db.createCollection("Products");
  const orders = await db.createCollection("Orders");
 
  await products.insert({
    sku: "LAPTOP-001",
    name: "Gaming Laptop",
    price: 1299.99,
    stock: 15,
    category: "Electronics"
  });
 
  const lowStock = await products.query({ stock: { $lt: 10 } })
    .Sort({ stock: 1 })
    .exec();
 
  await orders.insert({
    orderId: "ORD-12345",
    customerId: "USER-001",
    items: [{ sku: "LAPTOP-001", quantity: 1 }],
    total: 1299.99,
    status: "pending"
  });
 
  await client.disconnect();
}
 
main().catch(console.error);

Where AxioDBCloud fits#

• Microservices — share one AxioDB instance across multiple services.
• Desktop apps — Electron apps connecting to a local or remote database.
• Cloud deployments — AWS, Azure, Google Cloud, DigitalOcean.

See Auth and TLS for securing the connection.