• Stars
    star
    867
  • Rank 50,741 (Top 2 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 8 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

SQLite client wrapper around sqlite3 for Node.js applications with SQL-based migrations API written in Typescript

SQLite Client for Node.js Apps

NPM version CircleCI built with typescript JavaScript Style Guide

A wrapper library written in Typescript with ZERO dependencies that adds ES6 promises and SQL-based migrations API to sqlite3 (docs).

note v4 of sqlite has breaking changes compared to v3! Please see CHANGELOG.md for more details.

Installation

Install sqlite3

Most people who use this library will use sqlite3 as the database driver.

Any library that conforms to the sqlite3 (API) should also work.

$ npm install sqlite3 --save

Install sqlite

# v4 of sqlite is targeted for nodejs 10 and on.
$ npm install sqlite --save

# If you need a legacy version for an older version of nodejs
# install v3 instead, and look at the v3 branch readme for usage details
$ npm install sqlite@3 --save

Usage

This module has the same API as the original sqlite3 library (docs), except that all its API methods return ES6 Promises and do not accept callback arguments (with the exception of each()).

Opening the database

Without caching

import sqlite3 from 'sqlite3'
import { open } from 'sqlite'

// this is a top-level await 
(async () => {
    // open the database
    const db = await open({
      filename: '/tmp/database.db',
      driver: sqlite3.Database
    })
})()

or

import sqlite3 from 'sqlite3'
import { open } from 'sqlite'

open({
  filename: '/tmp/database.db',
  driver: sqlite3.Database
}).then((db) => {
  // do your thing
})

or

import sqlite3 from 'sqlite3'
import { open } from 'sqlite'

// you would have to import / invoke this in another file
export async function openDb () {
  return open({
    filename: '/tmp/database.db',
    driver: sqlite3.Database
  })
}

With caching

If you want to enable the database object cache

import sqlite3 from 'sqlite3'
import { open } from 'sqlite'

(async () => {
    const db = await open({
      filename: '/tmp/database.db',
      driver: sqlite3.cached.Database
    })
})()

Enable verbose / debug mode

import sqlite3 from 'sqlite3'

sqlite3.verbose()

Tracing SQL errors

For more info, see this doc.

db.on('trace', (data) => {
  
})

With a custom driver

You can use an alternative library to sqlite3 as long as it conforms to the sqlite3 API.

For example, using sqlite3-offline-next:

import sqlite3Offline from 'sqlite3-offline-next'
import { open } from 'sqlite'

(async () => {
    const db = await open({
      filename: '/tmp/database.db',
      driver: sqlite3Offline.Database
    })
})()

Opening multiple databases

import sqlite3 from 'sqlite3'
import { open } from 'sqlite'

(async () => {
  const [db1, db2] = await Promise.all([
    open({
      filename: '/tmp/database.db',
      driver: sqlite3.Database
    }),
    open({
      filename: '/tmp/database2.db',
      driver: sqlite3.Database
    }),
  ])

  await db1.migrate({
    migrationsPath: '...'
  })

  await db2.migrate({
    migrationsPath: '...'
  })
})()

open config params

// db is an instance of `sqlite#Database`
// which is a wrapper around `sqlite3#Database`
const db = await open({
  /**
   * Valid values are filenames, ":memory:" for an anonymous in-memory
   * database and an empty string for an anonymous disk-based database.
   * Anonymous databases are not persisted and when closing the database
   * handle, their contents are lost.
   */
  filename: string

  /**
   * One or more of sqlite3.OPEN_READONLY, sqlite3.OPEN_READWRITE and
   * sqlite3.OPEN_CREATE. The default value is OPEN_READWRITE | OPEN_CREATE.
   */
  mode?: number

  /**
   * The database driver. Most will install `sqlite3` and use the `Database` class from it.
   * As long as the library you are using conforms to the `sqlite3` API, you can use it as
   * the driver.
   *
   * @example
   *
   * ```
   * import sqlite from 'sqlite3'
   *
   * const driver = sqlite.Database
   * ```
   */
  driver: any
})

Examples

  • See the src/**/__tests__ directory for more example usages
  • See the docs/ directory for full documentation.
  • Also visit the sqlite3 library API docs

Creating a table and inserting data

await db.exec('CREATE TABLE tbl (col TEXT)')
await db.exec('INSERT INTO tbl VALUES ("test")')

Getting a single row

const result = await db.get('SELECT col FROM tbl WHERE col = ?', 'test')

// { col: 'test' }
const result = await db.get('SELECT col FROM tbl WHERE col = ?', ['test'])

// { col: 'test' }
const result = await db.get('SELECT col FROM tbl WHERE col = :test', {
  ':test': 'test'
})

// { col: 'test' }

Getting many rows

const result = await db.all('SELECT col FROM tbl')

// [{ col: 'test' }]

Inserting rows

const result = await db.run(
  'INSERT INTO tbl (col) VALUES (?)',
  'foo'
)

/*
{
  // row ID of the inserted row
  lastID: 1,
  // instance of `sqlite#Statement`
  // which is a wrapper around `sqlite3#Statement`
  stmt: <Statement>
}
*/
const result = await db.run('INSERT INTO tbl(col) VALUES (:col)', {
  ':col': 'something'
})

Updating rows

const result = await db.run(
  'UPDATE tbl SET col = ? WHERE col = ?',
  'foo',
  'test'
)

/*
{
  // number of rows changed
  changes: 1,
  // instance of `sqlite#Statement`
  // which is a wrapper around `sqlite3#Statement`
  stmt: <Statement>
}
*/

Prepared statement

// stmt is an instance of `sqlite#Statement`
// which is a wrapper around `sqlite3#Statement`
const stmt = await db.prepare('SELECT col FROM tbl WHERE 1 = ? AND 5 = ?5')
await stmt.bind({ 1: 1, 5: 5 })
let result = await stmt.get()
// { col: 'some text' }
const stmt = await db.prepare(
  'SELECT col FROM tbl WHERE 13 = @thirteen ORDER BY col DESC'
)

const result = await stmt.all({ '@thirteen': 13 })

each()

each() is a bit different compared to the other operations due to its underlying implementation.

The function signature looks like this:

async each (sql, [...params], callback)

  • callback(err, row) is triggered when the database has a row to return
  • The promise resolves when all rows have returned with the number of rows returned.
try {
  // You need to wrap this in a try / catch for SQL parse / connection errors
  const rowsCount = await db.each(
    'SELECT col FROM tbl WHERE ROWID = ?',
    [2],
    (err, row) => {
      if (err) {
        // This would be if there is an error specific to the row result
        throw err
      }

      // row = { col: 'other thing' }
    }
  )
} catch (e) {
  throw e
}

// rowsCount = 1

Get the driver instance

Useful if you need to call methods that are not supported yet.

const rawDb = db.getDatabaseInstance()
const rawStatement = stmt.getStatementInstance()

Closing the database

await db.close()

ES6 tagged template strings

This module is compatible with sql-template-strings.

import SQL from 'sql-template-strings'

const book = 'harry potter';
const author = 'J. K. Rowling';

const data = await db.all(SQL`SELECT author FROM books WHERE name = ${book} AND author = ${author}`);

Migrations

This module comes with a lightweight migrations API that works with SQL-based migration files

With default configuration, you can create a migrations/ directory in your project with SQL files, and call the migrate() method to run the SQL in the directory against the database.

See this project's migrations/ folder for examples.

await db.migrate({    
    /**
    * If true, will force the migration API to rollback and re-apply the latest migration over
    * again each time when Node.js app launches.
    */
    force?: boolean
    /**
    * Migrations table name. Default is 'migrations'
    */
    table?: string
    /**
    * Path to the migrations folder. Default is `path.join(process.cwd(), 'migrations')`
    */
    migrationsPath?: string
})

Typescript tricks

Import interfaces from sqlite

import { ISqlite, IMigrate } from 'sqlite'

See the definitions for more details.

Specify typings for a specific database driver

// Assuming you have @types/sqlite3 installed
import sqlite3 from 'sqlite3'

// sqlite3.Database, sqlite3.Statement is the default if no explicit generic is specified
await open<sqlite3.Database, sqlite3.Statement>({
  filename: ':memory'
})

Use generics to get better typings on your rows

Most methods allow for the use of generics to specify the data type of your returned data. This allows your IDE to perform better autocomplete and the typescript compiler to perform better static type analysis.

Get example

interface Row {
  col: string
}

// result will be of type Row, allowing Typescript supported IDEs to autocomplete on the properties!
const result = await db.get<Row>('SELECT col FROM tbl WHERE col = ?', 'test')

All example

interface Row {
  col: string
}

// Result is an array of rows, you can now have array-autocompletion data
const result = await db.all<Row[]>('SELECT col FROM tbl')

result.each((row) => {
  // row should have type information now!
})

API Documentation

See the docs directory for full documentation.

Management Tools

  • Beekeeper Studio: Open Source SQL Editor and Database Manager
  • DB Browser for SQLite: Desktop-based browser.
  • datasette: Datasette is a tool for exploring and publishing data. Starts up a server that provides a web interface to your SQLite data.
  • SQLite Studio: A free, open source, multi-platform SQLite database manager written in C++, with use of Qt framework.
  • HeidiSQL: Full-featured database editor.
  • DBeaver: Full-featured multi-platform database tool and designer.

Alternative SQLite libraries

This library and the library it primarily supports, sqlite3, may not be the best library that fits your use-case. You might want to try these other SQLite libraries:

  • better-sqlite3: Totes itself as the fastest and simplest library for SQLite3 in Node.js.
  • Bun sqlite3: bun:sqlite is a high-performance builtin SQLite3 module for bun.js.
  • sql.js: SQLite compiled to Webassembly.
  • sqlite3-offline-next: Offers pre-compiled sqlite3 binaries if your machine cannot compile it. Should be mostly compatible with this library.

If you know of any others, feel free to open a PR to add them to the list.

References

License

The MIT License © 2020-present Kriasoft / Theo Gravity. All rights reserved.


Made with ♥ by Konstantin Tarkus (@koistya), Theo Gravity and contributors

More Repositories

1

react-starter-kit

The web's most popular Jamstack front-end template (boilerplate) for building web applications with React
TypeScript
22,474
star
2

react-firebase-starter

Boilerplate (seed) project for creating web apps with React.js, GraphQL.js and Relay
JavaScript
4,493
star
3

graphql-starter-kit

💥 Monorepo template (seed project) pre-configured with GraphQL API, PostgreSQL, React, and Joy UI.
TypeScript
3,822
star
4

Folder-Structure-Conventions

Folder / directory structure options and naming conventions for software projects
1,834
star
5

universal-router

A simple middleware-style router for isomorphic JavaScript web apps
TypeScript
1,694
star
6

isomorphic-style-loader

CSS style loader for Webpack that is optimized for isomorphic (universal) web apps.
JavaScript
1,272
star
7

aspnet-starter-kit

Cross-platform web development with Visual Studio Code, C#, F#, JavaScript, ASP.NET Core, EF Core, React (ReactJS), Redux, Babel. Single-page application boilerplate.
JavaScript
1,156
star
8

react-app

Create React App with server-side code support
JavaScript
614
star
9

babel-starter-kit

🐠 Babel Starter Kit is a project template for authoring and publishing JavaScript libraries
JavaScript
555
star
10

react-decorators

A collection of higher-order ReactJS components
JavaScript
231
star
11

node-starter-kit

Node.js / GraphQL project template pre-configured with TypeScript, PostgreSQL, login flow, transactional emails, unit tests, CI/CD workflow.
TypeScript
157
star
12

static-site-starter

Static Website Starter Kit (static site generator) powered by Gulp, Jade, Bootstrap, LESS and BrowserSync. It can automatically deploy your website to GitHub Pages via Travis CI.
JavaScript
136
star
13

angular-vs

AngularJS + ASP.NET Web Api + TypeScript - Single Page Application (SPA) Starter Kit for Visual Studio
JavaScript
127
star
14

AspNet.Identity

Entity Framework (EF) Database-First Providers, Database Schema and Samples for ASP.NET Identity 2.0
C#
122
star
15

AngularJS-SPA-Template

AngularJS SPA Template for Visual Studio is a project skeleton for a simple single-page web application (SPA) built with AngularJS, Bootstrap, and ASP.NET (MVC, Web Api, SignalR).
CSS
104
star
16

hyperapp-render

Render Hyperapp to an HTML string with SSR and Node.js streaming support.
JavaScript
103
star
17

cloudflare-starter-kit

Template (boilerplate) repository for scaffolding Cloudflare Workers projects
TypeScript
103
star
18

fsharp-starter-kit

Cross-platform web development with Visual Studio Code, C#, F#, JS, ASP.NET Core, EF Core, React (ReactJS), Babel and Webpack. Demo =>
JavaScript
88
star
19

web-auth-library

Authentication library for the browser environment using Web Crypto API
TypeScript
83
star
20

TDAmeritrade

TD Ameritrade Client Library for .NET. Helps developers integrate custom solutions with the TD Ameritrade Trading Platform.
C#
76
star
21

amibroker

AmiBroker .NET SDK - An open source plug-in project template and community plug-ins for AmiBroker
C#
67
star
22

knex-types

Generate TypeScript definitions (types) from a PostgreSQL database schema.
TypeScript
63
star
23

hyperapp-starter

Boilerplate and tooling for authoring modern web applications with Hyperapp and Node.js.
JavaScript
61
star
24

react-component-starter

Skeleton project template for a stand-alone React component. NOTE: This project is currently NOT maintained. You may want to check https://github.com/kriasoft/babel-starter-kit instead
JavaScript
50
star
25

app-starter-kit

A front-end web application template based on HTML5 Boilerplate and enhanced with LESS style sheets and Gulp.js build system (a newer promising alternative to Grunt.js)
JavaScript
45
star
26

SPA-Seed.Front-end

A single-page application (SPA) project template (aka SPA seed project), which has a pre-configured build system, JavaScript bundling and dependency resolution, unit and integration test runners, minimization and optimization for production deployments.
CSS
40
star
27

react-page-context

React Page Context allows to manage document's title, description and other meta tags, as well as <link> and <script> elements from inside regular React components via context.page context variable
JavaScript
40
star
28

market-data

KriaSoft Market Data Server - A local database server with quotes and trade-related data associated with equity, fixed-income, financial derivatives, currency, and other investment instruments.
32
star
29

ASP.NET-Solution

ASP.NET solution / project template for a typical web application, pre-configured with Git, Gulp.js (or Grunt), NuGet and StyleCop development tools. It is well suited for building a single-page web application (SPA).
CSS
32
star
30

site-sdk

Web Application Starter Kit (aka Site SDK) is a solution / project template for building ambitious web applications on top of the AngularJS, ASP.NET Web Api, Entity Framework, Enterprise Library, and Windows Azure. Need help? Email me at [email protected]
JavaScript
27
star
31

pre-render

Convert a single-page app (SPA) into a fully pre-rendered functional website before deploying it to a CDN
JavaScript
25
star
32

image-resizing

Node.js backend (middleware) for dynamic image manipulation needs (transform, resize, optimize)
TypeScript
23
star
33

cloudflare-client

Lightweight universal Cloudflare API client library for Node.js, Browser, and CF Workers
TypeScript
20
star
34

terraform-starter-kit

Getting started with Terraform
HCL
18
star
35

docker-node-ci

The Docker image based on the official "node" image optimized for a CI environment
18
star
36

node-pg-client

Promise-based wrapper for `node-postgres` library designed for easy use with ES7 async/await.
JavaScript
16
star
37

webpack-middleware

Run Webpack compiler as Express.js/Browsersync middleware
JavaScript
16
star
38

graphql-api-examples

Code examples for GraphQL Start (tutorial) ⁠— How to build a GraphQL API on Node.js stack
JavaScript
10
star
39

SPA-Seed.Front-end.AngularJS

A single-page application (SPA) project template based on AngularJS
CSS
9
star
40

envars

Securely load environment variables (configuration settings) from .env files with support of Google Secret Manager.
JavaScript
9
star
41

MembershipDatabase

Membership database seed project created with SQL Server Data Tools (SSDT) for building a custom ASP.NET Identity / Membership solution for a typical web application using Database First development approach
9
star
42

cloudflare-ips

The list of CloudFlare IPs (IP ranges) to be used in the "trust proxy" (behind proxy) configurations
JavaScript
8
star
43

hyperapp-tools

Build automation tools for Hyperapp projects
JavaScript
7
star
44

jwt-passport

Passport.js framework that uses JWT for sessions
JavaScript
7
star
45

create-dns-record

Create DNS Record Action for GitHub
JavaScript
7
star
46

create-data-api

Project template for authoring data API backends with PostgreSQL, Redis, Passport.js and GraphQL.
JavaScript
6
star
47

component-routing

Component-based routing archiecture for single-page applications (SPA)
6
star
48

monorepo-example

Tips and tricks for setting up monorepo project structure for a typical web application.
JavaScript
5
star
49

rsb.kriasoft.com

Create React App + Relay Modern (DEMO)
JavaScript
5
star
50

delete-dns-record

Delete DNS Record Action for GitHub
JavaScript
5
star
51

reactstarter.com

React Starter Kit Homepage
CSS
4
star
52

check-version

Check Version Action for GitHub
JavaScript
4
star
53

restart

Restart Node.js app in development mode
JavaScript
4
star
54

data

Extensions library for Microsoft Entity Framework 4.2
C#
4
star
55

graphqlstart.com

GraphQL Start (tutorial) ⁠— How to build a GraphQL API on Node.js stack
4
star
56

react-components

Reusable React components
CSS
4
star
57

docker-gcloud

Google Cloud SDK bundled with Kubernetes CLI (kubectl)
3
star
58

AspNet

ASP.NET Identity Database is a SQL database project template (SSDT) which can be used to create a custom ASP.NET Identity / Membership provider using Database-First development approach.
C#
3
star
59

validator-fluent

Validation library for JavaScript/TypeScript with a strongly typed fluent API
TypeScript
2
star
60

core

KriaSoft Core Library - A collection of helper classes and utilities.
C#
2
star
61

kriasoft.github.io

CSS
2
star
62

bundle-webpack-plugin

Webpack plugin for emitting additional application bundles for Node.js, SSR, Cloudflare Workers, etc.
JavaScript
1
star
63

Diffbot

Diffbot Client Library for .NET - helps to extract article information (title, date, author, preview image etc.) for articles and blog posts with the Diffbot.com service.
C#
1
star
64

yeoman-generator

Yeoman Generator Starter Kit is a project template (boilerplate) for authoring Yeoman generators with modern JavaScript syntax (ES2015+) via Babel
JavaScript
1
star
65

simple-oauth2-clients

OAuth 2.0 clients for Google, Apple, Facebook, GitHub and other identity providers.
JavaScript
1
star
66

create-hyperapp-starter

The easiest way to start a new web application using Hyperapp.
JavaScript
1
star