Skip to end of metadata
Go to start of metadata

RoundhousE is a database deployment and management system. The following article covers all the key aspects of how the Ed-Fi ETL Application solution updates database schema and data using RoundhousE.

This article assumes you have read and completed the setup instructions the ETL Developers' Guide - Installation section.

General Background

If you're not familiar with RoundhousE, you may want to view the technical documentation on the RoundhousE project page and the excellent information on the RoundhousE Wiki.

RoundhousE Execution

Navigate in File Explorer to where you have cloned the code from GitHub. Navigate to the "Database\Scripts" folder.

The scripts folder contains SQL update scripts for the Application, Dashboard, Dashboard DW, ETL Log, and ODS databases. The Application and ODS databases have custom scripts for ODS version 3.1. The folders with appended Glendale names are specially for running against that sample database. The Common folder holds scripts that are executed on every database, which can be useful for applying things like permissions or data compression.

Legacy code removal

 The folders for version 1.2 and 2.0 as well as those for GrandBend will be removed from the folder prior to final release.


RoundhousE Folder Execution

When RoundhousE executes on a database folder, there is specific database migration logic that occurs each folder. For example, the Dashboard folder contains the following folders:

Up Folder

The "up" folder contains any schema or data update scripts. Scripts in this folder are only executed once. After a script in the up folder has been executed on the database, the script cannot be changed, otherwise RoundhousE will throw an error.

Permissions Folder

The "permissions" folder contains permission scripts (surprise!) that are run every time on the database which catches auto wiring of permissions.

Indexes Folder

Scripts in the "indexes" folder are run any time a script has been added or updated in the folder.

AfterMigration Folder

The "afterMigration" folder contains script that are run every time on the database. This is a custom RoundhousE every time script folder that is not part of the default configuration. This folder contains scripts for growing the database, creating database diagrams, and so forth.

More information on RoundhousE script folders can be found on the Wiki.

RoundhousE Script Execution Order and Script Naming Conventions

Scripts in the "up," "permissions," "indexes," and "afterMigration" folders execute based on the order that RoundhousE finds them. For example, the "Dashboard\up" folder has the following scripts:

The Dashboard Schema script will be executed before the Dashboard Data script based on its timestamp numbering. RoundhousE can run scripts appended with 0001, 0002, 0003 as well. As a convention, the SQL scripts in the ETL Database migration solution use the appended format YYYYMMDDHHmm. This naming convention resolves any script merge/ordering conflicts if multiple developers are adding update scripts to the same database.

Targeting ODS Versions and Agencies 

Any folder containing 3.1 in the "Database\Scripts" folder, targets the specific ODS version this dashboard supports. Folders with the naming "Glendale" contain the scripts for creating/updating the testing Glendale databases.

For example, when running the power shell command .\build rebuild 3.1 from the Databases folder, will rebuild the Glendale dataset for ODS 3.1. It will combine scripts from the Ods_3.1_Glendale folder with the Ods_3.1 folder, it will combine scripts from the Application_Glendale and Application folders, and combine scripts from the DashboardDW_Glendale with the DashboardDW folder in a temporary folder. It will use the combined scripts in the temporary folder to create the Application, Dashboard, Dashboard DW, ETL Log, and ODS 3.1 databases.

Database Migration Commands

The following commands can be executed from power shell in the Database folder to update and/or create the Application, Dashboard, Dashboard DW, ETL Log, and ODS databases.

CommandDescription
.\build rebuild [OdsVersion]The rebuild command by default will create the necessary Application, Dashboard, Dashboard DW, ETL Log, and ODS for the Glendale dataset. By default, it restores the Glendale dataset. 
.\build dashboard [OdsVersion] The dashboard command is for setting up the dashboard with a custom ODS. Executing the command will:
  • Create the Dashboard, DashboardDW, and ETL Log Db.
  • Update an Application Db if present or create one if not.
  • Updated the ODS will the necessary ETL scripts.

.\build updatedashboard [OdsVersion]

Update the Dashboard, DashboardDW, ETL Log Db, Application, and ODS with the latest scripts.
.\build samplesRestores the sample datasets Dashboard, DashboardDW, Application, and ODS preloaded with data by the ETL for the Glendale dataset. By default, it restores the Glendale dataset.


Content

  • No labels