Middleware.md

Helppo Express.js middleware

Mount a Helppo-instance in your own NodeJS application

• Instant CRUD for your database (create, read, update, and delete)
• Works with Postgres, MySQL
• Can read database schema automatically, via schema: 'auto'
• Just 2 dependencies (!!), you probably already have both (express and body-parser)
• Use your own authentication implementation

Quickstart

Install Helppo as a dependency:

$ npm install --save helppo
# or
$ yarn add helppo

Mount it in your Express.js application:

import helppo from "helppo";
// or
const helppo = require("helppo").default;

const config = {
  driver: ...,
  schema: ...,
};
app.use("/admin", helppo(config));

For more information, continue reading.

Table of Contents

• Quickstart
• Table of Contents
• Usage
  • Database driver
  • Schema
    • schema: "auto"
    • schema: { ... }
  • Customize column definitions
• Authentication
  • Example: Basic Auth
  • Example: Passport.js
• Documentation
• License

Usage

Database driver

Helppo works with your existing database connection. You don't pass database credentials to Helppo; instead you pass a database driver which is initialized with your existing connection.

Example for Postgres:

import { PgDriver } from "helppo";
import { Pool } from "pg";
const pool = new Pool({
  max: 5 // control how many connections Helppo may create
});
app.use("/admin", helppo({
  driver: new PgDriver(pool),
}));

Example for MySQL:

import { MysqlDriver } from "helppo";
import { createPool } from "mysql";
const pool = createPool({
  connectionLimit: 5 // control how many connections Helppo may create
});
app.use("/admin", helppo({
  driver: new MysqlDriver(pool),
}));

See Drivers.md for a list of available drivers.

Schema

schema: "auto"

Helppo can read your full database schema automatically.

Example:

app.use("/admin", helppo({
  schema: "auto",
}));

schema: { ... }

For when you want to customize the table and column information (e.g. including only a subset of tables/columns), you can define a full schema-object.

Example:

app.use("/admin", helppo({
  schema: {
    tables: [
      ...
    ]
  },
}));

How to get a starting point? Simply leave the schema property undefined in your config. When you open Helppo in your browser, you'll be able to copy an automatically generated schema:

See Configuration.md for available schema configuration options.

Customize column definitions

Take advantage of the various schema options Helppo supports:

• Set a maximum length for text-based columns (via maxLength)
• Hide the value of sensitive columns like passwords (via secret)
• Link related rows together between tables (via referencesTable and referencesColumn)
• Add a comment/explanation to a column (via comment)

For many of these, if you have them defined at the database level, Helppo will also find them automatically.

See Configuration.md for documentation.

Authentication

NOTE: Helppo does not include any built-in authentication.

Helppo is a regular Express middleware, so you can restrict access to it similarly to any other middleware or route in your application.

The following examples are illustrative. Make sure to test your authentication implementation before going live.

Example: Basic Auth

Example using the popular express-basic-auth package:

const basicAuth = require('express-basic-auth');
const authMiddeware = basicAuth({ ... });
app.use('/admin', authMiddeware, helppo(config));

Example: Passport.js

If you use Passport.js in your application, just use it as usual:

app.use("/admin", passport.authenticate("local"), helppo(config));

Documentation

Full documentation can be found at docs/README.md.

License

See LICENSE in the repository root, and for added information see License-section in the repository README.md.