AxioDB is an embedded NoSQL database for Node.js with MongoDB-style queries. It is a pure JavaScript alternative to SQLite with zero native dependencies, no node-gyp compilation, and no platform-specific binaries. Install with 'npm install axiodb' and you have a database — no mongod process, no server setup. Perfect for Electron apps, CLI tools, and local-first applications.

Is AxioDB a replacement for MongoDB?

No. AxioDB is embedded — it runs inside your app with no server. MongoDB is a client-server database for multi-user production systems. Use AxioDB for desktop apps, CLI tools, and local-first applications with 10K–500K documents. Use MongoDB when you need a shared, networked, multi-user database.

Does AxioDB work with Electron?

Yes — Electron is the primary use case AxioDB was built for. Zero native dependencies means no electron-rebuild, no platform-specific .node files, no node-gyp compilation. Just npm install axiodb and it works on Windows, Mac, and Linux without any rebuild step.

What is the difference between AxioDB and better-sqlite3?

better-sqlite3 uses C native bindings and requires compilation via node-gyp. AxioDB is pure JavaScript — it installs in any Node.js environment without compilation or platform-specific builds. AxioDB also uses NoSQL/JSON document queries instead of SQL strings, includes built-in caching and Worker Threads, and works out of the box in Electron without electron-rebuild.

What is the difference between AxioDB and lowdb?

lowdb stores everything in a single JSON file and becomes slow above 1,000–5,000 records due to full-file reads on every operation. AxioDB uses file-per-document tree storage with InMemoryCache, Worker Threads, and auto-indexing — optimized for 10,000–500,000 documents with O(1) lookups by ID and fast filtered queries.

What is the difference between AxioDB and nedb?

NeDB is abandoned (no active maintenance since 2016) and keeps the entire database in memory. AxioDB is actively maintained, uses file-based storage, supports TypeScript, ACID transactions with savepoints and WAL, Worker Threads, AES-256 encryption, custom field indexing, and AxioDBCloud remote access.

How many documents can AxioDB handle?

AxioDB is optimized for 10,000–500,000 documents per collection. For 1M+ documents, migrate to PostgreSQL or MongoDB. AxioDB's InMemoryCache and Worker Threads keep performance fast within this range — documentId lookups take ~1ms and indexed queries take ~2ms on 10,000 documents.

Does AxioDB support TypeScript?

Yes. Full TypeScript type definitions are included out of the box with the axiodb npm package. No @types/axiodb needed.

Does AxioDB work in the browser?

No. AxioDB requires Node.js (v20+) and uses the filesystem for storage. It is a server-side and desktop embedded database. It does not run in browsers.

AxioDBCloud is a TCP-based remote access layer for AxioDB. Deploy AxioDB in Docker or Cloud, then connect from multiple clients using the exact same API as embedded AxioDB — zero code changes. Supports 1,000+ concurrent connections, auto-reconnect with exponential backoff, and heartbeat monitoring.

TROUBLESHOOTING

Troubleshooting

The errors you're most likely to hit connecting to AxioDBCloud or logging into the GUI, in the exact wording AxioDB returns, with the real fix for each.

"Not connected to server" right after calling connect()

client.connect() is asynchronous and must be awaited before you use the connection — it only resolves once the TCP handshake (and, if TCPAuth is on, the AUTHENTICATE round-trip) has completed.

javascript

1// ❌ Wrong — races ahead before the connection (and login) finish
2client.connect();
3console.log(client.authenticatedUser); // undefined
4await client.createDB("MyDB");         // "Not connected to server"
5
6// ✅ Right
7await client.connect();
8console.log(client.authenticatedUser); // populated
9await client.createDB("MyDB");         // works

401 — "Authentication required..."

You're running with TCPAuth: true and sent a command before a successful AUTHENTICATE. Either pass { username, password } in the AxioDBCloud constructor (it auto-authenticates on connect()), or call await client.login(username, password) yourself before any other command.

403 — "This account must change its password before it can be used over TCP..."

Your credentials are correct, but that account is still flagged for a forced password change — true for the default admin/admin account, and for any newly created user. Log into the GUI at http://localhost:27018, sign in, and complete the password change there — there's no TCP command for this yet. Then reconnect with the new password, or use a different account that has already completed its change.

429 — "Too many failed login attempts..."

Five failed logins from your IP within a trailing 15-minute window trigger a 15-minute lockout, shared between TCP and the GUI. Double-check the credentials you're sending, wait out the cooldown, or fix the underlying typo/config issue causing repeated failures — there's no way to clear the lockout early.

403 — "This is a reserved system database"

You (or a client) tried to read/write a database literally named config — that name is reserved for AxioDB's own RBAC storage (users/roles/permissions) and is blocked on both the GUI and TCP, authenticated or not. Use a different database name.

Connection refused / timeout connecting to axiodb://host:27019

• Confirm the server was started with TCP: true (or, in Docker, AXIODB_TCP=true, the default).
• Confirm the port is published: -p 27019:27019 on docker run, or that nothing else on the host is bound to 27019.
• If you're getting a protocol error mentioning "Message exceeds maximum size" or "Received HTTP data on TCP port," you're likely pointed at the GUI port (27018) instead of the TCP port (27019) — check your connection string.

Docker container won't start, port conflicts, or data not persisting

See the Docker Deployment page, and Docker/README.md in the repository for a fuller Docker-specific troubleshooting guide (docker logs, port-conflict remapping, volume-mounting checklist).