ffc-database 1.0.1 → 1.0.22

package/README.md

@@ -1,82 +1,106 @@
 # ffc-database
 
-Database utility npm module for FFC services
-
-## Usage
+Database utility npm module for FFC services.
 
 ### Installation
 
-```
+```bash
 npm install --save ffc-database
 ```
 
-### Configuration
+---
+
+### API and configuration
+
+- **Constructor argument**: a single **config** object with the following important properties:
+  - **database** - Name of the database to connect to.
+  - **username** - Database user name.
+  - **password** - Database user password.
+  - **modelPath** - Filesystem path to the directory containing your Sequelize model files.
+  - **Other Sequelize options** - Any other Sequelize options may be included on the same config object and are passed to Sequelize, for example **dialect**, **host**, **port**, **logging**, **ssl**, etc.
+
+Example config:
+
+```js
+const config = {
+  dialect: 'postgres',
+  host: 'localhost',
+  port: 5432,
+  database: 'ffc_pay',
+  username: 'ffc_user',
+  password: 'ffc_password',
+  modelPath: './models',
+  ssl: true,
+  logging: false
+}
+```
 
-`dialect` - Database dialect, e.g. `postgres`, `mssql`, `sqlite`, etc.
+---
 
-`host` - Database server hostname, e.g. `localhost` or `mydb.postgres.database.azure.com`
+### Usage
 
-`port` - Database server port, e.g. `5432` for PostgreSQL
+- Instantiate the exported class and call **connect**. The returned object contains each model keyed by model name, plus **sequelize** and **Sequelize**.
 
-`database` - Name of the database to connect to
+Example:
 
-`username` - Database user name
+```js
+const Base = require('ffc-database')
 
-`password` - Database user password
+const dbBase = new Base(config)
+const db = dbBase.connect()
 
-`ssl` - Boolean or object for SSL configuration (optional, recommended for production)
+// Access models
+// e.g. db.Payment, db.User
+// Access sequelize instance
+// e.g. db.sequelize.authenticate(), db.sequelize.close()
+```
 
-`logging` - Enable or disable SQL query logging (default: `false`)
+- Model file shape example (models/payment.js):
 
-#### Example
-```
-const config = { dialect: 'postgres', host: 'localhost', port: 5432, database: 'ffc_pay', username: 'ffc_user', password: 'ffc_password', ssl: true, logging: false }
-```
+```js
+module.exports = (sequelize, DataTypes) => {
+  const Payment = sequelize.define('Payment', {
+    amount: { type: DataTypes.DECIMAL },
+    status: { type: DataTypes.STRING }
+  })
 
-### Connecting to the database
+  Payment.associate = (models) => {
+    // e.g. Payment.belongsTo(models.User)
+  }
 
-```
-const { createDatabaseConnection } = require('ffc-database') const db = createDatabaseConnection(config)
+  return Payment
+}
 ```
 
-### Running migrations
+- The module reads all `.js` files in **modelPath**, ignores files starting with a dot and `index.js`, requires each file and invokes it with `(sequelize, DataTypes)`, and then runs `associate` on models that provide it.
 
-```
-const { runMigrations } = require('ffc-database') await runMigrations(db)
+---
 
-```
+### Querying and closing
 
-### Executing queries
+- Run raw queries via the returned **sequelize** instance:
 
-```
-const [results, metadata] = await db.query('SELECT * FROM payments WHERE status = $1', { replacements: ['pending'] })
+```js
+const [results, metadata] = await db.sequelize.query(
+  'SELECT * FROM payments WHERE status = $1',
+  { bind: ['pending'] }
+)
 ```
 
-### Closing the connection
+- Close the connection:
 
-```
-await db.close()
+```js
+await db.sequelize.close()
 ```
 
-## Licence
+### Licence
 
-THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT
-LICENCE found at:
+THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE
 
 <http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3>
 
-The following attribution statement MUST be cited in your products and
-applications when using this information.
-
-> Contains public sector information licensed under the Open Government license
-> v3
-
-### About the licence
+**Attribution statement**
 
-The Open Government Licence (OGL) was developed by the Controller of Her
-Majesty's Stationery Office (HMSO) to enable information providers in the
-public sector to license the use and re-use of their information under a common
-open licence.
+> Contains public sector information licensed under the Open Government licence v3
 
-It is designed to encourage use and re-use of information freely and flexibly,
-with only a few conditions.
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffc-database",
-  "version": "1.0.1",
+  "version": "1.0.22",
   "description": "Databas npm module for FCP services",
   "main": "index.js",
   "repository": {
@@ -24,4 +24,4 @@
   "devDependencies": {
     "standard": "17.1.2"
   }
-}
+}