Database Configuration
This page focuses on what is required, what is optional, and how database choice relates to licensing.
Apistry supports multiple database backends, but not all are available in every mode.
Default Database: NeDB (Free Mode)
Apistry ships with NeDB built in to make first-time startup fast and frictionless.
NeDB is a lightweight, document-oriented database with MongoDB-like semantics. It is well suited for: - local development - evaluation - demos - contract experimentation
Why NeDB Is the Default
NeDB allows Apistry to: - start with zero external dependencies - avoid mandatory database installation - support a true free evaluation mode - keep startup time measured in seconds
In free mode, Apistry uses NeDB automatically unless another adapter is explicitly configured.
NeDB Storage Modes
NeDB can run in two modes:
In-Memory (Ephemeral)
If no database path is provided, NeDB runs entirely in memory.
- Data is lost when the server stops
- Ideal for quick experimentation
- No filesystem writes
This is the default behavior when running:
apistry serve -c contracts
Filesystem-Backed (Persistent)
To persist data across restarts, provide a directory path.
apistry serve -c contracts -d contracts/nedb
Notes:
- Three slashes (nedb:///) indicate an absolute path
- Two slashes (nedb://) indicate a relative path
- The directory will be created if it does not exist
If you downloaded the sample contracts ZIP, the NeDB files are already present and populated.
MongoDB (Licensed Mode)
MongoDB support is only available through a license.
This capability is intended for: - production deployments - multi-instance services - externally managed persistence - operational monitoring and scaling - event streaming and triggers
When a valid license is present, MongoDB can be selected by providing a MongoDB connection string in the config.yml.
MongoDB is not required to evaluate or develop with Apistry. Other JSON supported Databases can be supported as well via licensed adapters.
MongoDB Connection Configuration
When using MongoDB, the connection string must be provided in the config.yml.
Hosted MongoDB Example
database:
connection: mongodb+srv://apistry:${MONGO_PASSWORD}@apistry-db.ojsguxa.mongodb.net/apistry?appName=apistry-db
Local MongoDB Example
database:
connection: mongodb://localhost:27017/mydb
Notes: - The database name must be included in the connection string - The database will be created if it does not already exist
Licensing Summary
| Capability | Free Mode | Licensed Mode |
|---|---|---|
| NeDB (in-memory) | ✅ | ✅ |
| NeDB (filesystem) | ✅ | ✅ |
| MongoDB adapter | ❌ | ✅ |
| Additional database adapters | ❌ | ✅ |
What This Page Does Not Cover
This page intentionally avoids: - database schema design - indexing strategies - operational tuning - backup and replication
Those topics are database-specific and outside Apistry’s responsibility.
Once you are comfortable with Apistry, migrating from NeDB to MongoDB is a configuration change, not a rewrite.