Registry / database / bookshelf

bookshelf

JSON →
library1.2.0jsnpmunverified

Bookshelf is a Node.js ORM built on Knex query builder, supporting PostgreSQL, MySQL, and SQLite3. Version 1.2.0 (latest stable) is actively maintained with a test suite on Travis CI. It provides promise-based and callback interfaces, eager/nested-eager loading, transactions, and polymorphic associations. Unlike full-featured ORMs like Sequelize, Bookshelf is lean, data-mapper oriented, and encourages dropping to raw Knex for custom queries. Release cadence is irregular, with security fixes prioritized. Requires peer dependency knex >=0.15.0 <0.22.0 and a database driver (pg, mysql, sqlite3).

database
npm install bookshelf
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · BOOKSHELF
B
bookshelf
databasejavascriptv1.2.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

default
✓ const bookshelf = require('bookshelf')(knex)
✗ const bookshelf = require('bookshelf')
Bookshelf must be initialized with a Knex instance. Common mistake: calling require('bookshelf') without passing knex.
model
✓ const User = bookshelf.model('User', { tableName: 'users' })
✗ const User = bookshelf.Model.extend({ tableName: 'users' })
bookshelf.model() is the recommended way to define models (since v0.12). bookshelf.Model.extend() still works but is deprecated.
forge
✓ const user = await new User({ id: 1 }).fetch()
✗ const user = bookshelf.forge('User', { id: 1 }).fetch()
forge() is not part of Bookshelf API. Use new Model() or static methods like User.forge() if defined.

Sets up Bookshelf with Knex, defines three models with relations, and fetches a user with nested eager loading.

const knex = require('knex')({ client: 'mysql', connection: { host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'root', password: process.env.DB_PASS ?? '', database: process.env.DB_NAME ?? 'test' } }); const bookshelf = require('bookshelf')(knex); const User = bookshelf.model('User', { tableName: 'users', posts() { return this.hasMany('Post'); } }); const Post = bookshelf.model('Post', { tableName: 'posts', tags() { return this.belongsToMany('Tag'); } }); const Tag = bookshelf.model('Tag', { tableName: 'tags' }); async function example() { const user = await new User({ id: 1 }).fetch({ withRelated: ['posts.tags'] }); console.log(user.toJSON()); } example().catch(console.error);
Debug
Known issues
breakingBookshelf v1.x requires knex >=0.15.0 but <0.22.0. Upgrading knex to 0.22+ will break.
fix
Pin knex to 0.21.x or 0.19.x (check compat). Use lockfile.
affects: >=1.0.0
deprecatedbookshelf.Model.extend() is deprecated in favor of bookshelf.model().
fix
Use bookshelf.model('Name', { ... }) instead.
affects: >=0.12.0
gotchaBookshelf does not create tables automatically. You must use Knex migrations or raw SQL to create tables before querying.
fix
Run knex migrate:latest or create tables manually.
affects: all
gotchaWhen using ESM imports (TypeScript or ES modules), require('bookshelf') returns a function that must be called with knex.
fix
Use dynamic import or CJS require. ESM: import bookshelf from 'bookshelf'; const b = bookshelf(knex);
affects: all
Errors
Common errors & fixes
TypeError: bookshelf is not a function
Calling require('bookshelf') without passing knex instance.
fix
Use `const bookshelf = require('bookshelf')(knex);`
Error: ER_BAD_DB_ERROR: Unknown database 'myapp_test'
The database specified in knex connection does not exist.
fix
Create the database using `CREATE DATABASE myapp_test;` or change connection settings.
TypeError: Cannot read property 'model' of undefined
Calling bookshelf.model() before initializing bookshelf with knex.
fix
Ensure `const bookshelf = require('bookshelf')(knex);` is executed before using bookshelf methods.
Upgrade
Version history
1.2.0latest on npm
Audit
Dependencies
knexrequiredSQL query builder and connection management
Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources
githubhttps://github.com/bookshelf/bookshelf ↗
packagebookshelf ↗
homepagehttps://bookshelfjs.org ↗