Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create
✓ const db = require('apemandb').create(envConfig, { modelsDir: './db/models' });
✗ import { create } from 'apemandb'; // apemandb primarily uses CommonJS 'require' pattern in examples.
The primary interaction with ApemanDB is via its `create` factory function, typically consuming configuration from `apemanenv` and a directory of JSON model definitions.
apemanenv
✓ const apemanenv = require('apemanenv');
✗ import apemanenv from 'apemanenv'; // Examples explicitly use CommonJS `require`.
ApemanDB strongly relies on `apemanenv` for loading environment-specific database configuration, as shown in the provided setup guides.
DB Instance (methods)
✓ await db.sync(); await db.models.User.create({ username: 'test' });
✗ await db.User.create(); // Access models via `db.models` property, not directly on the instance.
After initialization, models are typically accessed via the `models` property of the returned database instance. The `sync` method is used for schema synchronization.
Demonstrates setting up `apemanenv` for database configuration, defining a model using `apemandb`'s JSON schema, and initializing the `apemandb` instance to synchronize schema and perform basic CRUD operations.
const path = require('path');
const apemanenv = require('apemanenv');
const apemandb = require('apemandb');
// 1. Define environment configuration (env/database.json)
// In a real project, this would be loaded by apemanenv automatically.
// For quickstart, we'll simulate the structure.
const envDir = path.join(__dirname, 'env');
require('fs').mkdirSync(envDir, { recursive: true });
require('fs').writeFileSync(path.join(envDir, 'database.json'), JSON.stringify({
"default": {
"DIALECT": "sqlite",
"SCHEMA": "apeman-demo-web",
"STORAGE": ":memory:"
},
"development": {
"SCHEMA": "apeman-demo-web_dev",
"STORAGE": "./tmp/dev-database.db"
},
"test": {
"DIALECT": "sqlite",
"SCHEMA": "apeman-demo-web_test",
"STORAGE": ":memory:"
}
}, null, 2));
// 2. Define a model (db/models/user.json)
const modelsDir = path.join(__dirname, 'db', 'models');
require('fs').mkdirSync(modelsDir, { recursive: true });
require('fs').writeFileSync(path.join(modelsDir, 'user.json'), JSON.stringify({
"$name": "User",
"$description": "A user model",
"$attributes": {
"username": {
"$type": "STRING",
"$unique": true
},
"introText": {
"$type": "STRING(1024)",
"$nullable": true
}
}
}, null, 2));
async function main() {
// Load environment variables
const envConfig = apemanenv(__dirname); // Simulates env loading from __dirname
// Initialize ApemanDB with configuration and models
const db = apemandb.create(envConfig, { modelsDir: modelsDir });
try {
// Connect to the database and synchronize models (create tables)
await db.sync({ force: true }); // `force: true` drops tables before recreating
console.log('Database and tables synchronized!');
// Create a new user record
const newUser = await db.models.User.create({ username: 'john_doe', introText: 'Hello world!' });
console.log('Created user:', newUser.toJSON());
// Find a user
const foundUser = await db.models.User.findOne({ where: { username: 'john_doe' } });
console.log('Found user:', foundUser.toJSON());
} catch (error) {
console.error('Database operation failed:', error.message);
} finally {
// Close the database connection if it's not an in-memory SQLite
if (db.sequelize.options.dialect !== 'sqlite' || db.sequelize.options.storage !== ':memory:') {
await db.sequelize.close();
console.log('Database connection closed.');
}
}
}
main();
Errors
Common errors & fixes
Dialect needs to be explicitly defined. If you are using SQLite, install 'sqlite3' package.
Missing database driver package or incorrect 'DIALECT' in database.json.
fixInstall the correct driver (e.g., `npm install sqlite3` or `npm install mysql2`) for your chosen database, and ensure the `DIALECT` property is correctly set in `env/database.json`.
Error: connect ECONNREFUSED 127.0.0.1:3306
The database server is not running, or the host/port/credentials in `database.json` are incorrect, preventing a connection.
fixVerify that your database server (e.g., MySQL, PostgreSQL) is running and accessible. Double-check `HOST`, `PORT`, `USERNAME`, and `PASSWORD` in your `env/database.json`.
TypeError: Cannot read properties of undefined (reading 'User')
The `modelsDir` path provided to `apemandb.create` is incorrect, or the JSON model file (e.g., `user.json`) is malformed or missing.
fixEnsure the `modelsDir` path is absolute and correctly points to your model definition directory. Verify that JSON model files are valid and present in that directory.
Audit
Dependencies
sequelizerequiredCore ORM functionality, ApemanDB is a wrapper around it.
apemanenvrequiredRequired for managing environment-specific database configurations.
mysql2optionalRequired for MySQL database dialect support, inferred from database.json example.
sqlite3optionalRequired for SQLite database dialect support, inferred from database.json example. For Sequelize v6, sqlite3 must be installed manually.