Registry / database / ffc-database

ffc-database

JSON →
library1.0.24jsnpmunverified

ffc-database is an npm module developed by DEFRA, providing a structured utility layer for database interactions within FFC services. It is built upon the Sequelize ORM, abstracting common setup and model loading patterns. The module simplifies connecting to SQL databases (e.g., PostgreSQL, as shown in examples) by taking a configuration object, dynamically loading Sequelize models from a specified filesystem path, and exposing the connected Sequelize instance and loaded models. The current stable version is 1.0.24. While specific release cadence is not provided, its versioning and association with government services suggest a focus on stability and compatibility within its ecosystem. Its key differentiator lies in its opinionated, service-centric wrapper around Sequelize, streamlining database access for specific internal FFC applications.

database
npm install ffc-database
github ↗package ↗
INSTALL
IMPORT
SIG · FFC-DATABASE
F
ffc-database
databasejavascriptv1.0.24
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Base
✓ const Base = require('ffc-database')
✗ import Base from 'ffc-database'
The package primarily uses CommonJS `require()`. Direct ES module `import` syntax may not work without additional configuration or transpilation due to its CommonJS export structure.
db.sequelize
✓ const dbBase = new Base(config); const db = dbBase.connect(); // Access sequelize instance: db.sequelize.authenticate();
The `sequelize` instance is exposed directly on the object returned by `connect()`, allowing access to all native Sequelize methods like `authenticate()`, `close()`, and `query()`.
db.ModelName
✓ const dbBase = new Base(config); const db = dbBase.connect(); // Access models by their defined name (e.g., 'Payment'): await db.Payment.findAll();
Models are automatically loaded from `modelPath` and attached to the `db` object with their defined names (e.g., `Payment`). This pattern is part of the `ffc-database` abstraction.

This quickstart demonstrates how to instantiate the `ffc-database` module, connect to a PostgreSQL database using environment variables for sensitive data, dynamically load Sequelize models, execute a simple raw SQL query, and gracefully close the database connection.

const Base = require('ffc-database'); const config = { dialect: 'postgres', host: process.env.DB_HOST ?? 'localhost', port: parseInt(process.env.DB_PORT ?? '5432', 10), database: process.env.DB_NAME ?? 'ffc_pay', username: process.env.DB_USER ?? 'ffc_user', password: process.env.DB_PASSWORD ?? 'ffc_password', modelPath: './models', // Assuming models directory exists in CWD ssl: process.env.DB_SSL === 'true' ?? false, logging: process.env.NODE_ENV !== 'production' }; // Minimal model file example (./models/payment.js): // module.exports = (sequelize, DataTypes) => { // const Payment = sequelize.define('Payment', { // amount: { type: DataTypes.DECIMAL }, // status: { type: DataTypes.STRING } // }); // Payment.associate = (models) => {}; // Define associations here // return Payment; // }; async function runDbOperations() { let dbBase; let db; try { dbBase = new Base(config); db = await dbBase.connect(); console.log('Database connected successfully.'); // Example: Run a raw query const [results, metadata] = await db.sequelize.query( 'SELECT 1 + 1 as solution;', { type: db.sequelize.QueryTypes.SELECT } ); console.log('Query result:', results); // Assuming a 'Payment' model exists and is defined in './models/payment.js' // const payments = await db.Payment.findAll(); // console.log('Found payments:', payments); } catch (error) { console.error('Database operation failed:', error); } finally { if (db && db.sequelize) { await db.sequelize.close(); console.log('Database connection closed.'); } } } runDbOperations();
Debug
Known issues
gotchaThe module's examples and internal structure primarily use CommonJS (`require`). Integrating into a pure ES module (ESM) Node.js project may require specific `package.json` configurations (`'type': 'commonjs'`) or transpilation to avoid `SyntaxError: Named export 'X' not found` or `require() of ES modules is not supported` errors.
fix
For ESM projects, consider using dynamic `import()` or ensuring your project's `package.json` correctly handles module types. For Sequelize specifically, ensure compatibility by checking how it's imported in ESM contexts.
affects: >=1.0.0
gotchaThe `modelPath` configuration expects a filesystem path to a directory containing JavaScript files that define Sequelize models. These files must adhere to the `module.exports = (sequelize, DataTypes) => { ... }` pattern. Incorrect paths or malformed model files will prevent models from being loaded.
fix
Verify that `config.modelPath` is an absolute or correct relative path to your model directory. Ensure each model file exports a function that accepts `sequelize` and `DataTypes` as arguments and returns the defined model.
affects: >=1.0.0
gotchaThe `sequelize.close()` method should be called when your application is shutting down to release database connections. Once called, the `sequelize` instance cannot re-establish connections, requiring a new instance if further database operations are needed.
fix
Implement connection closing in application shutdown hooks (e.g., `process.on('SIGTERM', ...)`) or after a block of operations where the connection is no longer needed. Ensure a new `Base` instance is created if `connect()` is to be called again.
affects: >=1.0.0
Errors
Common errors & fixes
SequelizeConnectionError: connect ECONNREFUSED
The database server is not running, is inaccessible from the host, or the connection parameters (host, port, username, password) are incorrect.
fix
Verify the database server is running and accessible. Double-check `host`, `port`, `username`, `password`, and `database` in your `config` object. Ensure no firewall rules are blocking the connection.
Error: Cannot find module 'pg'
The necessary database driver (e.g., `pg` for PostgreSQL) is not installed as a dependency in your project.
fix
Install the required database dialect package: `npm install --save pg` for PostgreSQL, `npm install --save mysql2` for MySQL, etc.
TypeError: db.YourModelName.findAll is not a function
The model `YourModelName` was not correctly loaded or defined, possibly due to an incorrect `modelPath` or an error in the model's file structure.
fix
Confirm that `config.modelPath` points to the correct directory. Check the model file (`yourmodelname.js`) for syntax errors, ensure it exports a function, and that `sequelize.define` is correctly used within it.
Upgrade
Version history
1.0.24latest on npm
Audit
Dependencies
sequelizerequiredProvides the underlying ORM functionality for database interactions, model definition, and querying.
pgoptionalRequired for connecting to a PostgreSQL database, as indicated by the example `dialect: 'postgres'` configuration. Other database drivers (e.g., `mysql2`) would be needed for different dialects.
Agent activity
7 hits · last 30 days
node
6
Resources
githubhttps://github.com/DEFRA/ffc-database ↗
packagehttps://www.npmjs.com/package/ffc-database ↗
ffc-database — npm install ffc-database · libregistry