Usage

There are several methods of using the database, depending on your purpose:

General Browsing/Querying

If you're interested in the contents of the database, start by downloading the latest SQLite database release, and an SQLite browser such as DBeaver.

Once installed, open the Database > New Connection dialog. Select the SQLite type from the list, and press Next. On the following screen, press the Browse button and select the Shabad OS database file that you previously downloaded, and proceed through the next screens until wizard is complete.

A new database entry will appear under the Database Navigator tab, and double-clicking this will open the database. Expand the tables option to view all the tables in the database, and double-click on any of the tables to view the data. You may also run some of the SQL queries and explore the dataset further.

Some common query examples can be seen at SQLite Querying.

Offline Applications - SQLite

If you're building a mobile app or desktop application, you'll likely want an offline copy of the database, unless you're certain your users will always be connected to the internet.

You can download the latest SQLite database release and query against it using your language's SQLite library.

Note: This option will mean that you will have to check the Shabad OS Database release page for updates yourself. If you are building an application in JavaScript, please see the Offline Applications - JavaScript section below.

Some common query examples can be seen at SQLite Querying.

Offline Applications - JavaScript

The offline JavaScript API is perfect for Node applications. Once installed using npm install @shabados/database, the module can be used to query the database using the fluid interface that Objection.js and Knex provide.

The module exposes an Objection.js Model for each table in the database, and can automatically fetch any relations.

A quick example of querying an Objection.js Model can be seen below. Each query must begin with a .query() method call, which will return a Knex Query Builder object that can be used to build up the query by chaining method calls.

This kicks off a jQuery-like chain, with which you can call additional query builder methods as needed to construct the query, eventually calling any of the interface methods, to either convert toString, or execute the query, returning the results as a promise, callback, or stream.

Let's start by fetching all the Gurbani sources that the database has:

// Import the Sources Model from the module
const { Sources } = require('@shabados/database');

Sources.query() // Returns a Knex Query Builder
  .then((results) => console.log(results)); // Results are returned as a promise

ES7 async/await can also be used with the results: await Sources.query().