{"id":40664,"library":"bookshelf","title":"Bookshelf.js","description":"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).","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/bookshelf/bookshelf","tags":["javascript","orm","mysql","postgresql","sqlite","datamapper","active record"],"install":[{"cmd":"npm install bookshelf","lang":"bash","label":"npm"},{"cmd":"yarn add bookshelf","lang":"bash","label":"yarn"},{"cmd":"pnpm add bookshelf","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"SQL query builder and connection management","package":"knex","optional":false}],"imports":[{"note":"Bookshelf must be initialized with a Knex instance. Common mistake: calling require('bookshelf') without passing knex.","wrong":"const bookshelf = require('bookshelf')","symbol":"default","correct":"const bookshelf = require('bookshelf')(knex)"},{"note":"bookshelf.model() is the recommended way to define models (since v0.12). bookshelf.Model.extend() still works but is deprecated.","wrong":"const User = bookshelf.Model.extend({ tableName: 'users' })","symbol":"model","correct":"const User = bookshelf.model('User', { tableName: 'users' })"},{"note":"forge() is not part of Bookshelf API. Use new Model() or static methods like User.forge() if defined.","wrong":"const user = bookshelf.forge('User', { id: 1 }).fetch()","symbol":"forge","correct":"const user = await new User({ id: 1 }).fetch()"}],"quickstart":{"code":"const knex = require('knex')({\n  client: 'mysql',\n  connection: {\n    host: process.env.DB_HOST ?? 'localhost',\n    user: process.env.DB_USER ?? 'root',\n    password: process.env.DB_PASS ?? '',\n    database: process.env.DB_NAME ?? 'test'\n  }\n});\nconst bookshelf = require('bookshelf')(knex);\n\nconst User = bookshelf.model('User', {\n  tableName: 'users',\n  posts() {\n    return this.hasMany('Post');\n  }\n});\n\nconst Post = bookshelf.model('Post', {\n  tableName: 'posts',\n  tags() {\n    return this.belongsToMany('Tag');\n  }\n});\n\nconst Tag = bookshelf.model('Tag', {\n  tableName: 'tags'\n});\n\nasync function example() {\n  const user = await new User({ id: 1 }).fetch({ withRelated: ['posts.tags'] });\n  console.log(user.toJSON());\n}\n\nexample().catch(console.error);","lang":"javascript","description":"Sets up Bookshelf with Knex, defines three models with relations, and fetches a user with nested eager loading."},"warnings":[{"fix":"Pin knex to 0.21.x or 0.19.x (check compat). Use lockfile.","message":"Bookshelf v1.x requires knex >=0.15.0 but <0.22.0. Upgrading knex to 0.22+ will break.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use bookshelf.model('Name', { ... }) instead.","message":"bookshelf.Model.extend() is deprecated in favor of bookshelf.model().","severity":"deprecated","affected_versions":">=0.12.0"},{"fix":"Run knex migrate:latest or create tables manually.","message":"Bookshelf does not create tables automatically. You must use Knex migrations or raw SQL to create tables before querying.","severity":"gotcha","affected_versions":"all"},{"fix":"Use dynamic import or CJS require. ESM: import bookshelf from 'bookshelf'; const b = bookshelf(knex);","message":"When using ESM imports (TypeScript or ES modules), require('bookshelf') returns a function that must be called with knex.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'0.15.0':80 '0.22.0':81 '1.2.0':18 'activ':22,95 'associ':44 'base':35 'bookshelf':2,52 'bookshelf.js':1 'builder':11 'built':7 'cadenc':69 'callback':37 'ci':30 'custom':66 'data':56 'data-mapp':55 'databas':84 'datamapp':94 'depend':78 'driver':85 'drop':61 'eager/nested-eager':39 'encourag':60 'featur':48 'fix':74 'full':47 'full-featur':46 'interfac':38 'irregular':71 'javascript':89 'knex':9,64,79 'latest':19 'lean':54 'like':50 'load':40 'maintain':23 'mapper':57 'mysql':14,87,91 'node.js':5 'orient':58 'orm':6,49,90 'peer':77 'pg':86 'polymorph':43 'postgresql':13,92 'priorit':75 'promis':34 'promise-bas':33 'provid':32 'queri':10,67 'raw':63 'record':96 'releas':68 'requir':76 'secur':73 'sequel':51 'sqlite':93 'sqlite3':16,88 'stabl':20 'suit':27 'support':12 'test':26 'transact':41 'travi':29 'unlik':45 'version':17","created_at":"2026-06-04T18:48:39.651613+00:00","updated_at":"2026-06-04T18:48:39.651613+00:00","problems":[{"fix":"Use `const bookshelf = require('bookshelf')(knex);`","cause":"Calling require('bookshelf') without passing knex instance.","error":"TypeError: bookshelf is not a function"},{"fix":"Create the database using `CREATE DATABASE myapp_test;` or change connection settings.","cause":"The database specified in knex connection does not exist.","error":"Error: ER_BAD_DB_ERROR: Unknown database 'myapp_test'"},{"fix":"Ensure `const bookshelf = require('bookshelf')(knex);` is executed before using bookshelf methods.","cause":"Calling bookshelf.model() before initializing bookshelf with knex.","error":"TypeError: Cannot read property 'model' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://bookshelfjs.org","github":"https://github.com/bookshelf/bookshelf","docs":null,"changelog":null,"pypi":null,"npm":"bookshelf","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-04","next_check":"2026-09-02","install_tag":null}}