Bill Niblock c10b847e81 Add Yard, and begin some documentation

Use Yard to generate documentation. Included in the `.yardopts` file is
configuration to also publish the markdown files in the `wiki/`
directory.

wiki/
- addons.md: Information on writing new addons.
- database.md: Information on using the database and migrations

db/migrate/*: Rename in accordance with documentation

Rakefile: Add the Yard Rake tasks

2021-03-07 16:57:27 -05:00

2.8 KiB

Raw Permalink Blame History

@markup markdown

@title Database

Chronicle Database

Chronicle leverages a database for persistent storage. It uses ActiveRecord for interfacing with the supported database types, performing migrations, and interacting with models.

Supported Databases

Currently Supported:

SQLite

Planned Support:

PostgreSQL
MySQL
MariaDB

Creating the Database

There's a Rake task for creating the database according to ActiveRecord: rake db:create. For configuration, check out config/db.yml. The default configuration will create a SQLite3 database at db/chronicle-bot.db.

Working With the Migrations

ActiveRecord migrations are database-agnostic schema alterations, stored as code. This allows Chronicle to support multiple different database architectures, without having to write custom code for each one. Migrations can represent changes tied to new versions, or additional database configuration tied to an add-on or protocol, for example.

To apply the migrations, use the Rake task rake db:migrate.

To roll-back the migrations, use the Rake task rake db:down.

Provided Migrations

By default, Chronicle includes a migration for setting up the "general" table, which provides details around the bot itself.

It also includes a migration for the Custom Commands add-on, which creates a table for storing the commands and responses, along with the room ID the command was created in.

Each of these migrations include a "roll-back" solution, which simply drops the corresponding tables.

Writing Additional Migrations

The most important thing when creating new migrations is to follow the naming convention:

   XXXX_name_of_migration.rb

The Rake tasks for working with migrations will look at every file in the db/migrate/ directory, and sort them. It will require those files, and then compile a list of the classes within those files according to specific logic: it takes the file name, drops the numbers at the beginning, and converts the file name from snake case and to camel case, dropping the file extension. For example, "0000_create_general.rb" will be processed to the class named "CreateGeneral", which will be added to a list. The Rake task will then go through each the list of all classes and run the "migrate" method of each class, passing it "up" if migrations are being applied, or "down" if migrations are being rolled-back.

Generally speaking, the number for the migration is mostly important for sorting order. However, a simple naming convention can help distinguish between types of migrations, by changing the 2nd-position digit:

For migrations tied to Chronicle functionality, use 00XX.
For migrations tied to addon functionality, use 01XX.
For migrations tied to protocol functionality, use 02XX.
For any miscellaneous migrations, use 03XX.

2.8 KiB Raw Permalink Blame History