Add DB Schema

.gitignore

@@ -1,3 +1,6 @@
+# mac
+.DS_Store
+
 # Logs
 logs
 *.log

.sequelizerc

@@ -0,0 +1,8 @@
+const path = require('path');
+
+module.exports = {
+  'config': path.resolve('config', 'database.js'),
+  'models-path': path.resolve('db', 'models'),
+  'seeders-path': path.resolve('db', 'seeders'),
+  'migrations-path': path.resolve('db', 'migrations')
+}

README.rst

@@ -55,6 +55,120 @@ which uses `mocha <https://mochajs.org/>`_, `chai <http://chaijs.com/>`_, and `s
 - run the ``mocha`` test suite,
 - and deploy to `heroku <https://dashboard.heroku.com/>`_
 
+Documentation
+=============
+
+Code Structure
+--------------
+
+- `.sequelizerc <.sequelizerc>`_ contains configuration for the `sequelize cli <https://github.com/sequelize/cli>`_
+- `config/ <config/>`_ contains configuration files for database and other services
+- `db/ <db/>`_ contains database model, seeder, and migration files
+- `index.js <index.js>`_ is our server entrypoint
+- `package.json <package.json>`_ is self-explanatory
+- `scripts/ <scripts/>`_ contains various scripts, such as those referenced by `package.json <package.json>`_
+- `services/ <services/>`_ contains code that runs various services as singletons, the exception being sequelize which is in `db/ <db/>`_
+- `test/ <test/>`_ contains our tests
+- `utils.js <utils.js>`_ contains some utility functions we like
+
 Database Schema Diagram
-=======================
+-----------------------
 `see details <documentation/SCHEMA-DIAGRAM.rst>`_
+
+Database Management
+-------------------
+
+See `sequelize tutorial <http://docs.sequelizejs.com/manual/tutorial/migrations.html>`_ for in-depth details. Setting up the structure for the first time with the `sequelize cli <https://github.com/sequelize/cli>`_ is as easy as running::
+
+  node_modules/.bin/sequelize init
+
+To view all possible commands, run::
+
+  node_modules/.bin/sequelize
+
+Models and Migrations
+~~~~~~~~~~~~~~~~~~~~~
+
+To create a model, you can use the ``model:generate`` command::
+
+  node_modules/.bin/sequelize model:generate --name User --attributes firstName:string,lastName:string,email:string
+
+which creates a ``User`` model in `db/models/ <db/models/>`_ folder and a migration file with name like ``XYZ-create-user.js`` in `db/migrations/ <db/migrations/>`_ folder. You can then run this migration::
+
+  node_modules/.bin/sequelize db:migrate
+
+to create this new user table. Similarly, you can undo this migration with::
+
+  node_modules/.bin/sequelize db:migrate:undo
+
+or to undo all::
+
+  node_modules/.bin/sequelize db:migrate:undo:all
+
+or to a specific migration::
+
+   node_modules/.bin/sequelize db:migrate:undo:all --to XYZ-create-user.js
+
+Migration Procedure Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Based on the way we've organized it, we are enforcing migrations for changes to our database in an atomic, consistent, testable way. To make sure this happens correctly, realize that migrations are for changing the database structure only. Client code such as validation and helper functions for existing database relationships (adding ``belongsToMany`` for example) is not part of a migration. That said, migrations will be done on a best-effort. As an example, let's say we would like to create a migration that adds a many-to-many relationship between ``gloss`` and ``sign`` models. That is, we would like ``belongsToMany`` in both directions of the relationship.
+
+#. Run::
+
+    node_modules/.bin/sequelize model:generate --name gloss_sign --attributes glossId:integer,signId:integer
+
+#. Remove the generated model file under ``db/models/gloss_sign.js``. We are not adding a new "model" per-se, but we are creating a new table. Technically, we should just create a migration, but it's easier to let this set up a lot of the default entries for us to make this connection work.
+#. Edit the migration file that was just created, make sure the table name is ``gloss_sign`` and not ``gloss_signs`` -- as sequelize tends to pluralize automatically.
+#. Continue editing by adding the following information on the foreign keys we plan to make::
+
+      glossId: {
+        primaryKey: true,
+        allowNull: false,
+        type: Sequelize.INTEGER,
+        references: {model: 'glosses', key: 'id'},
+        onUpdate: 'CASCADE',
+        onDelete: 'CASCADE'
+      },
+      signId: {
+        primaryKey: true,
+        allowNull: false,
+        type: Sequelize.INTEGER,
+        references: {model: 'signs', key: 'id'},
+        onUpdate: 'CASCADE',
+        onDelete: 'CASCADE'
+      },
+
+#. Next, edit by removing the ``id`` column from the table. Since we are using a compound primary key of ``(glossId, signId)`` and will automatically cascade updates, we don't need to do any extra work to ensure that this is unique.
+
+#. Next, edit ``db/models/sign.js`` and ``db/models/gloss.js`` to add ``belongsToMany`` relationships. For example, in ``sign.js``::
+
+    sign.associate = models => {
+      ...
+      sign.belongsToMany(models.gloss, {as: "Glosses", through: "gloss_sign", foreignKey: "signId", otherKey: "glossId"});
+      ...
+    };
+
+#. Finally, run a series of migrations to ensure that we can rewind and playback with no issues::
+
+    node_modules/.bin/sequelize db:migrate
+    node_modules/.bin/sequelize db:migrate:undo
+    node_modules/.bin/sequelize db:migrate
+
+and that's it. You've created a many-to-many relationship with migrations! Note that the migration's job here was just to create the tables according to the kind of relationship we were adding (``belongsToMany``) and we configured the ``belongsToMany`` call based exactly on the table we created (``gloss_sign``) and the foreign keys in that table (``signId``, ``glossId``).
+
+For more information, see the following blog posts:
+
+- https://tech.luc.id/sequelize-it-part-1-4bb752097861
+- https://codeburst.io/sequelize-migrations-setting-up-associations-985d29b61ee7
+
+Database Setup
+==============
+
+To set up the dev environment locally for MySQL, I just ran ``brew install mysql`` to install it, then::
+
+  $ mysql.server start
+  $ mysql -u root
+  mysql> GRANT ALL PRIVILEGES ON signsfive_dev.* TO 'signsfive_dev'@'localhost' IDENTIFIED BY 'signsfive_dev';
+
+to create a ``signsfive_dev`` user with the same password and full access to the database of the same name.

config/database.js

@@ -0,0 +1,24 @@
+module.exports = {
+  development: {
+    username: 'signsfive_dev',
+    password: 'signsfive_dev',
+    database: 'signsfive_dev',
+    host: '127.0.0.1',
+    dialect: 'mysql',
+    operatorsAliases: false
+  },
+  test: {
+    username: 'database_test',
+    password: null,
+    database: 'database_test',
+    host: '127.0.0.1',
+    dialect: 'mysql',
+    operatorsAliases: false
+  },
+  production: {
+    use_env_variable: 'CLEARDB_DATABASE_URL',
+    dialect: 'mysql',
+    pool: {min: 0, max: 10, idle: 100},
+    operatorsAliases: false
+  }
+}

db/migrations/20171122013426-create-author.js

@@ -0,0 +1,33 @@
+'use strict';
+module.exports = {
+  up: (queryInterface, Sequelize) => {
+    return queryInterface.createTable('authors', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: Sequelize.INTEGER
+      },
+      email: {
+        type: Sequelize.STRING
+      },
+      username: {
+        type: Sequelize.STRING
+      },
+      auth0_id: {
+        type: Sequelize.STRING
+      },
+      createdAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      },
+      updatedAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      }
+    });
+  },
+  down: (queryInterface, Sequelize) => {
+    return queryInterface.dropTable('authors');
+  }
+};

db/migrations/20171122014309-create-category.js

@@ -0,0 +1,30 @@
+'use strict';
+module.exports = {
+  up: (queryInterface, Sequelize) => {
+    return queryInterface.createTable('categories', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: Sequelize.INTEGER
+      },
+      name: {
+        type: Sequelize.STRING
+      },
+      description: {
+        type: Sequelize.TEXT
+      },
+      createdAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      },
+      updatedAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      }
+    });
+  },
+  down: (queryInterface, Sequelize) => {
+    return queryInterface.dropTable('categories');
+  }
+};

db/migrations/20171122032604-create-gloss.js

@@ -0,0 +1,30 @@
+'use strict';
+module.exports = {
+  up: (queryInterface, Sequelize) => {
+    return queryInterface.createTable('glosses', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: Sequelize.INTEGER
+      },
+      name: {
+        type: Sequelize.STRING
+      },
+      description: {
+        type: Sequelize.TEXT
+      },
+      createdAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      },
+      updatedAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      }
+    });
+  },
+  down: (queryInterface, Sequelize) => {
+    return queryInterface.dropTable('glosses');
+  }
+};

db/migrations/20171122032710-create-region.js

@@ -0,0 +1,30 @@
+'use strict';
+module.exports = {
+  up: (queryInterface, Sequelize) => {
+    return queryInterface.createTable('regions', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: Sequelize.INTEGER
+      },
+      name: {
+        type: Sequelize.STRING
+      },
+      loc: {
+        type: Sequelize.GEOMETRY('POINT')
+      },
+      createdAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      },
+      updatedAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      }
+    });
+  },
+  down: (queryInterface, Sequelize) => {
+    return queryInterface.dropTable('regions');
+  }
+};

db/migrations/20171122032851-create-sign.js

@@ -0,0 +1,28 @@
+'use strict';
+module.exports = {
+  up: (queryInterface, Sequelize) => {
+    return queryInterface.createTable('signs', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: Sequelize.INTEGER
+      },
+      giphy_id: {
+        allowNull: false,
+        type: Sequelize.STRING
+      },
+      createdAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      },
+      updatedAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      }
+    });
+  },
+  down: (queryInterface, Sequelize) => {
+    return queryInterface.dropTable('signs');
+  }
+};

db/migrations/20171122033056-create-source.js

@@ -0,0 +1,27 @@
+'use strict';
+module.exports = {
+  up: (queryInterface, Sequelize) => {
+    return queryInterface.createTable('sources', {
+      id: {
+        allowNull: false,
+        autoIncrement: true,
+        primaryKey: true,
+        type: Sequelize.INTEGER
+      },
+      url: {
+        type: Sequelize.STRING
+      },
+      createdAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      },
+      updatedAt: {
+        allowNull: false,
+        type: Sequelize.DATE
+      }
+    });
+  },
+  down: (queryInterface, Sequelize) => {
+    return queryInterface.dropTable('sources');
+  }
+};

db/migrations/20171122050235-add-author-foreign-key-to-signs.js

@@ -0,0 +1,16 @@
+'use strict';
+
+module.exports = {
+  up: (queryInterface, Sequelize) => {
+    return queryInterface.addColumn('signs', 'authorId', {
+      type: Sequelize.INTEGER,
+      references: {model: 'authors', key: 'id'},
+      onUpdate: 'CASCADE',
+      onDelete: 'SET NULL'
+    });
+  },
+
+  down: (queryInterface, Sequelize) => {
+    return queryInterface.removeColumn('signs', 'authorId');
+  }
+};

db/migrations/20171122053502-add-region-foreign-key-to-authors.js

@@ -0,0 +1,16 @@
+'use strict';
+
+module.exports = {
+  up: (queryInterface, Sequelize) => {
+    return queryInterface.addColumn('authors', 'regionId', {
+      type: Sequelize.INTEGER,
+      references: {model: 'regions', key: 'id'},
+      onUpdate: 'CASCADE',
+      onDelete: 'SET NULL'
+    });
+  },
+
+  down: (queryInterface, Sequelize) => {
+    return queryInterface.removeColumn('authors', 'regionId');
+  }
+};