# Database

Nodewood uses PostgreSQL as its database of choice. PostgreSQL has a lot of advanced features for when your application grows in complexity, but has excellent defaults to start you off with and can help ensure that you design and grow a solid schema.

# Configuration

Your database connection is configured using a .env file at the root of your project. This file is ignored by Git, which means it must be set up uniquely for every environment/machine, and it is safe to store secrets in.

The following configuration variables control your connection to the database:

  • DB_HOST: The IP address or URL of the database server. (e.g. '127.0.0.1')
  • DB_PORT: The port of the database server. (e.g. '5432')
  • DB_DB: The name of your database. (e.g. 'nodewood')
  • DB_USER: The username that is authenticated to connect to your database. (e.g. 'nodewood_user')
  • DB_PASS: The password for the provided username. (e.g. 'god')

# Data mapping

Nodewood does not use an ORM for data access, but rather a data mapper called MassiveJS. This is because Nodewood models are shared between the front-end and back-end, and thus can't contain any methods for accessing the database. Instead, Services are used to load data from the database and build models to work with. Check the relevant sections of the Node documentation for more information, and the MassiveJS documentation for information about how to send queries and statements to your database.

# Migrations

While Nodewood uses MassiveJS for database access, it doesn't come with a built-in migrations library. So for this purpose, we use the excellent migrations capabilities of Knex.JS.

# Creating

To add a new migration with some sample code to get you rolling, run:

nodewood add migration NAME

Replace NAME with a descriptive name of the migration you wish to create. The migration will be created in app/migrations, prefixed with a timestamp of the time when you created the migration. This prevents migration collisions should you name two migrations the same thing (ill-advice and confusing, but not catastrophic).

# Running Migrations

To run existing migrations, run:

nodewood migrate

This will run all migrations from the app/migrations and wood/migrations folders. You can optionally add test to the end of the command (nodewood migrate test) to run migrations against the test database.

# Rolling back

To rollback the most-recent set of changes, run:

nodewood rollback

Again, you can add test to the end of the command (nodewood rollback test) to rollback the most recent set of changes from the test database.