FAQ & Troubleshooting

Does file-json-db require MongoDB?

No. It is completely independent. It only uses Node.js built-in modules and stores data as ordinary JSON files on disk.

Does it have external dependencies?

Zero runtime dependencies. The package ships only db.js and db.d.ts.

Can multiple processes write to the same collection?

Not safely. The lock is in-process only. If two Node processes open the same collection and write concurrently you can get corrupted part files or a torn index. Use a single process, or external locking, or a real multi-client database.

My query is slow. What should I check?

• Is the field you filter on listed in indexes?
• Is the query a simple equality on a single indexed field? Only then is the secondary index used.
• Are you calling toArray() on a huge result set without limit?
• Consider adding project so you do not carry large unused fields.

I see a crash/ folder. What happened?

A part file failed to parse. In errorLevel: 'debug' mode the library copies the bad file once into crash/ and marks it so it is never parsed again. The rest of the collection continues to work. See Error Handling & Recovery.

How do I reset a collection?

db.dropCollection('users');
// or, to keep the name but clear data:
users.import('./empty.json', { clear: true }); // empty.json = []

Can I change the ID field after data exists?

Not automatically. The idField option is used when generating and looking up IDs. If you already have documents under _id and you switch to idField: 'id', existing documents will not be found by the new field until you migrate them yourself.

Where should I put the database directory?

• CLI tools: under the user’s home or a project-local ./data
• Electron: app.getPath('userData')
• Servers: a dedicated data volume with proper backup and permissions

Is the data human-readable?

Yes. Part files and index.json are ordinary JSON. With pretty: true (the default) they are indented and easy to inspect.

How do I migrate from low-json-db or a single JSON file?

Export your old data as a JSON array, then:

users.import('./old-data.json', { clear: true });

Something else went wrong

Attach an error listener and check the message:

db.on('error', (err) => console.error(err));

Open an issue on the GitHub repository with the error message, your Node version, and a minimal reproduction if possible.