jsite-database

6.1.0 verified Fri May 01 auth: no javascript

Database module for the JSite package, providing a structured database interface with built-in auditing (SCD Type 4 row-based and column-based change tracking), SQL formatting via sql-formatter, SQL generation via json-sql-builder2, and MySQL support via the mysql module. Version 6.1.0 is the latest stable release. Key differentiators include integrated audit trail capabilities and customizable configuration for format, SQL dialect, and MySQL connection.

Common errors

error Error: Cannot find module 'jsite-database' ↓

cause Package not installed in node_modules

fix

Run 'npm install jsite-database' in your project directory.

error TypeError: JSiteDatabase is not a constructor ↓

cause Using default import or calling function without 'new'

fix

Use 'const JSiteDatabase = require('jsite-database')' and instantiate with 'new JSiteDatabase()'.

error Error: connect ECONNREFUSED 127.0.0.1:3306 ↓

cause MySQL server not running or incorrect host/port

fix

Ensure MySQL is running on localhost:3306, or provide correct host and port in options.

error Error: Unknown audit method: 'all' ↓

cause Passing invalid audit option

fix

Use one of 'row', 'column', or omit for default 'row'.

Warnings

breaking In version 6.x, the audit option 'row' and 'column' changed behavior. Ensure you review the new SCD implementation. ↓

fix Review auditing documentation and migrate your schema accordingly.

gotcha The package uses 'json-sql-builder2' which has a different API than 'json-sql-builder'. Ensure you have the correct version. ↓

fix Use 'json-sql-builder2' as a dependency.

deprecated The 'mysql' package used for MySQL connections is deprecated since version 6.0.0. Consider migrating to 'mysql2'. ↓

fix Replace 'mysql' with 'mysql2' in options or use a compatible wrapper.

gotcha JSiteDatabase must be instantiated with 'new'. Calling it as a regular function will throw an error. ↓

fix Always use 'new JSiteDatabase(options)'.

Install

npm install jsite-database

yarn add jsite-database

pnpm add jsite-database

Imports

JSiteDatabase

wrong

import JSiteDatabase from 'jsite-database'

correct

const JSiteDatabase = require('jsite-database')

This package uses CommonJS and does not provide ESM exports.

JSiteDatabase

wrong

const JSiteDatabase = require('jsite-database').default

correct

const { JSiteDatabase } = require('jsite-database')

Named export, not default export.

JSiteDatabase
wrong
```
const db = JSiteDatabase(options)
```
correct
```
const Database = new JSiteDatabase(options)
```
JSiteDatabase is a constructor, must be instantiated with new.

Quickstart

Initializes a JSiteDatabase instance with MySQL connection and row-based auditing, then waits for readiness via ready().

const path = require('path');
const JSiteDatabase = require('jsite-database');

const db = new JSiteDatabase({
  format: { indent: '  ' },
  mysql: {
    host: process.env.MYSQL_HOST ?? 'localhost',
    user: process.env.MYSQL_USER ?? 'root',
    password: process.env.MYSQL_PASSWORD ?? '',
    database: process.env.MYSQL_DATABASE ?? 'test'
  },
  sql: {
    language: 'mysql',
    options: { quoteIdentifiers: true }
  },
  audit: 'row',
  files: {
    db: path.join(__dirname, 'private', 'mysql')
  }
});

db.ready()
  .then(() => console.log('Database ready'))
  .catch(err => console.error(err));