Bookshelf is a JavaScript ORM for Node.js, built on the Knex SQL query builder. It features both Promise-based and traditional callback interfaces, transaction support, eager/nested-eager relation loading, polymorphic associations, and support for one-to-one, one-to-many, and many-to-many relations.
It is designed to work with PostgreSQL, MySQL, and SQLite3.
Website and documentation. The project is hosted on GitHub, and has a comprehensive test suite.
Introduction
Persia Bookshelf 3 Drawer Bookshelf. Valentino Bookshelf 650 Open. Valentino Bookshelf 650 Solid. The most comprehensive image search on the web.
Bookshelf aims to provide a simple library for common tasks when querying databases in JavaScript, and forming relations between these objects, taking a lot of ideas from the Data Mapper Pattern.
With a concise, literate codebase, Bookshelf is simple to read, understand, and extend. It doesn't force you to use any specific validation scheme, and provides flexible, efficient relation/nested-relation loading and first-class transaction support.
It's a lean object-relational mapper, allowing you to drop down to the raw Knex interface whenever you need a custom query that doesn't quite fit with the stock conventions.
Installation
You'll need to install a copy of Knex, and either
mysql
, pg
, or sqlite3
from npm.The Bookshelf library is initialized by passing an initialized Knex client instance. The Knex documentation provides a number of examples for different databases.
This initialization should likely only ever happen once in your application. As it creates a connection pool for the current database, you should use the
bookshelf
instance returned throughout your library. You'll need to store this instance created by the initialize somewhere in the application so you can reference it. A common pattern to follow is to initialize the client in a module so you can easily reference it later:Examples
Here is an example to get you started:
Official Plugins
- Virtuals: Define virtual properties on your model to compute new values.
- Case Converter: Handles the conversion between the database's snake_cased and a model's camelCased properties automatically.
- Processor: Allows defining custom processor functions that handle transformation of values whenever they are
.set()
on a model.
Community plugins
- bookshelf-cascade-delete - Cascade delete related models on destroy.
- bookshelf-json-columns - Parse and stringify JSON columns on save and fetch instead of manually define hooks for each model (PostgreSQL and SQLite).
- bookshelf-mask - Similar to the functionality of the
Model#visible
attribute but supporting multiple scopes, masking models and collections using the json-mask API. - bookshelf-schema - A plugin for handling fields, relations, scopes and more.
- bookshelf-signals - A plugin that translates Bookshelf events to a central hub.
- bookshelf-paranoia - Protect your database from data loss by soft deleting your rows.
- bookshelf-uuid - Automatically generates UUIDs for your models.
- bookshelf-modelbase - An alternative to extend
Model
, adding timestamps, attribute validation and some native CRUD methods. - bookshelf-advanced-serialization - A more powerful visibility plugin, supporting serializing models and collections according to access permissions, application context, and after ensuring relations have been loaded.
- bookshelf-plugin-mode - Plugin inspired by the functionality of the
Model#visible
attribute, allowing to specify different modes with corresponding visible/hidden fields of model. - bookshelf-secure-password - A plugin for easily securing passwords using bcrypt.
- bookshelf-default-select - Enables default column selection for models. Inspired by the functionality of the
Model#visible
attribute, but operates on the database level. - bookshelf-ez-fetch - Convenient fetching methods which allow for compact filtering, relation selection and error handling.
- bookshelf-manager - Model & Collection manager to make it easy to create & save deep, nested JSON structures from API requests.
Support
Have questions about the library? Come join us in the #bookshelf freenode IRC channel for support on knex.js and bookshelf.js, or post an issue on Stack Overflow.
Contributing
If you want to contribute to Bookshelf you'll usually want to report an issue or submit apull-request. For this purpose the online repository isavailable on GitHub.
For further help setting up your local development environment or learning how you can contribute toBookshelf you should read the Contributing documentavailable on GitHub.
F.A.Q.
Dockshelf 1 3 10
Can I use standard node.js style callbacks?
Yes, you can call
.asCallback(function(err, resp) {
on any database operation method and use the standard (err, result)
style callback interface if you prefer.My relations don't seem to be loading, what's up?
Make sure to check that the type is correct for the initial parameters passed to the initial model being fetched. For example
new Model({id: '1'}).load([relations..])
will not return the same as new Model({id: 1}).load([relations..])
- notice that the id is a string in one case and a number in the other. This can be a common mistake if retrieving the id from a url parameter.This is only an issue if you're eager loading data with load without first fetching the original model.
new Model({id: '1'}).fetch({withRelated: [relations..]})
should work just fine.My process won't exit after my script is finished, why?
![Dockshelf 1 3 1 Dockshelf 1 3 1](https://m.media-amazon.com/images/I/710u8cD7AeL._AC_SX522_.jpg)
The issue here is that Knex, the database abstraction layer used by Bookshelf, uses connection pooling and thus keeps the database connection open. If you want your process to exit after your script has finished, you will have to call
.destroy(cb)
on the knex
property of your Bookshelf
instance or on the Knex
instance passed during initialization. More information about connection pooling can be found over at the Knex docs.How do I debug?
If you pass
debug: true
in the options object to your knex
initialize call, you can see all of the query calls being made. You can also pass that same option to all methods that access the database, like model.fetch()
or model.destroy()
. Examples:Sometimes you need to dive a bit further into the various calls and see what all is going on behind the scenes. You can use node-inspector, which allows you to debug code with
debugger
statements like you would in the browser.Bookshelf uses its own copy of the
bluebird
Promise library. You can read up here for more on debugging Promises.Adding the following block at the start of your application code will catch any errors not otherwise caught in the normal Promise chain handlers, which is very helpful in debugging:
How do I run the test suite?
See the CONTRIBUTINGdocument on GitHub.
Can I use Bookshelf outside of Node.js?
While it primarily targets Node.js, all dependencies are browser compatible, and it could be adapted to work with other javascript environments supporting a sqlite3 database, by providing a custom Knex adapter. No such adapter exists though.
Which open-source projects are using Bookshelf?
We found the following projects using Bookshelf, but there can be more:
- Ghost (A blogging platform) uses bookshelf. [Link]
- Soapee (Soap Making Community and Resources) uses bookshelf. [Link]
- NodeZA (Node.js social platform for developers in South Africa) uses bookshelf. [Link]
- Sunday Cook (A social cooking event platform) uses bookshelf. [Link]
- FlyptoX (Open-source Node.js cryptocurrency exchange) uses bookshelf. [Link]
- And of course, everything on here use bookshelf too.
RSS Feed for this tag 68 applications totalLast updated: Nov 10th 2021, 17:59 GMT
TeamBeam 4.10.0
Easily send and share large files with your business customers with the help of this streamlined a..
Curiota 3.3.1
Organize ideas and files with ease, make use of the Spotlight capabilities to find specific entrie..
DockShelf 1.5.1
Allows you to place an unlimited number of docks on your desktop
OS X 10.9 or later (Intel only)
FontNuke 1.2.11
Excel 2013 xlsx. A free and straightforward utility designed from the get-go to remove all the corrupt font cache f..
aMule 2.3.2
Open source and cross-platform ed2k client that makes it very easy and quick to search for and dow..
Webmin 1.770
A web-based interface for system administration for Unix Hegis grasp: evil resurrected 2 0 3.
XtreemFS 1.5.1
Distributed and replicated file system for the Cloud.
Mac OS X
S.S.E. File Encryptor 10R3A
Enables you to encrypt and decrypt files stored on your Mac's hard-drive with the help of six encr..
QFS 1.1.4
High-performance and fault-tolerant distributed file system
Mac OS X
Twotade 1.0.4
A small application that offers you the possibility to switch between the modification and creatio..
Mac OS X 10.6.6 or later (Intel only)
FileLib 6.0
REALbasic plug-in to access Unix file permissions
Mac OS X
Data Fence 1.0
A Mac OS X application that is able to monitor the access to user specified files and alert you ab..
Mac OS X 10.9 or later (Intel only)
Transfer on LAN 0.6.1
A simple, Java based file transferring tool
Mac OS X
Cloudfogger 1.0 Build 2143
An easy to use, free file encryption service created for your files and online documents
iPadOS
IPSW update files designed to help you effortlessly restore and / or update your iPad to the latest software version using Apple's iTunes
Firefox
The world's most popular open-source browser, designed for users who want a customizable, feature-rich alternative to Safari that still takes privacy seriously
Google Chrome
Fast and user-friendly web browser that helps you navigate the Internet while also allowing you to stay safe and to synchronize your bookmarks between multiple computers
Hidden Bar
Hide menu bar items and avoid clutter without removing the icons altogether, using this impressively straightforward and lightweight app
Aerial
Set the aerial videos recorded for the fourth-generation Apple TV as your Mac's screensaver and enjoy beautiful scenery from around the world
Alfred
An easy to use productivity application for the macOS that helps you save time by speeding up your searches, on the web or on your Mac
VLC Media Player
Multi-platform multimedia player that helps its users play, convert and stream most popular video and formats via a simple and intuitive user interface
macOS Monterey
The latest macOS provides FaceTime improvements, a Safari rework, integration of various iOS features, and enhancements across the board
Pages
An intuitive word processor and layout designer that allows you to create documents using a multitude of templates and a versatile set of tools
Numbers
Fully-featured spreadsheet application that enables you to setup everything from the family budget, to lab reports and comprehensive financial documents
Keynote
Intuitive presentation app that lets you create impressive slideshows with very little effort, using one of the many well-designed templates
Microsoft Remote Desktop
Offers you the possibility to quickly connect to a Windows-based computer in order to work with its programs and files, access data and more
Patched Sur
Run macOS Big Sur on unsupported Macs using an intuitive patcher that downloads the necessary files and creates a USB installer, then helps you update the OS
AppCleaner
Simple to use macOS utility designed to help you to quickly and properly uninstall any application with a just a flick of your mouse
macOS Monterey
- macOS Monterey
- Pages
- Numbers
- Keynote
- Microsoft Remote Desktop
- Patched Sur
- AppCleaner
- iOS
- iPadOS
- Firefox
- Google Chrome
- Hidden Bar
- Aerial
- Alfred
- VLC Media Player
![Dockshelf Dockshelf](https://media.madeindesign.com/nuxeo/products/3/1/shelf-dock-white_madeindesign_189245_large.jpg)
essentials
ShowAllFiles
A lightweight and no-frills Mac OS X utility that provides a simple method to show or hide the spe..
Mac OS X 10.5 or later (PPC & Intel)
Cheetah Sync 1.5.1
A small application that will allow you to sync files between your computer and Android device
Mac OS X 10.5 or later
Dockshelf 1 3 1 2
Zeeb 3.9.25
An Adobe AIR application for renaming movie files on your hard drive
Mac OS X (PPC & Intel)
BYclouder Data Recovery Pro 6.8.1.0
Recover lost files from any storage device
Mac OS X 10.6 or later (Intel only)
Glark 1.10.1
Dockshelf 1 3 1 2 Equals
Powerful grep-like search tool written in Ruby
Mac OS X
FITS 0.6.2
Tool set for extracting file information
Mac OS X
EclipseCommander 1.3.1
Eclipse-based file manager for all major platforms
Mac OS X
caudec 1.6.0
A CLI based Multi-process audio transcoder
Mac OS X
Protocol Buffers 2.5.0
A program that lets you easily convert your files in a format compatible with the data interchange..
Mac OS X
Free Files Downloader 2.0
Java based download manager
AST Folder Hider and Locker 1.0
Hide and protect your personal files and folders
Mac OS X
1/3 - 1 Fraction
DiABlu Mailman 0.6
Send files to or and receive files from Bluetooth devices
Mac OS X
SnatchIt 1.0
Dashboard Widget that downloads files from URLs to your desktop
Mac OS X 10.4 or later (PPC & Intel)
SanDisk SecureAccess 1.1.19755
A tool to secure the files on your SanDisk USB flash drive
WebDAV integration 1.0.1
LibreOffice add-on for accessing documents from a WebDAV server
Mac OS X
showinfinder
A tool for finding a file from the command line
Mac OS X