What's New

EdFi.Db.Deploy

Summary of key enhancements with this release:

1. Install as a dotnet tool
2. Changed the execution syntax to use verbs (examples below)
3. Now contains full Admin and Security databases
4. Support for deploying Change Queries as a feature
5. Support for deploying extensions
6. Support for testing if any migration scripts need to be run, using whatif  verb.

Installing Alpha 2

See readme for more details.

Install the pre-compiled version from binaries on MyGet using dotnet tool  global installation with --version 1.0.0-alpha2  for getting this pre-release version:

dotnet tool install -g EdFi.Db.Deploy --add-source https://www.myget.org/F/ed-fi/api/v3/index.json --version 1.0.0-alpha2

Alternately, you can get the source code from https://github.com/Ed-Fi-Alliance/Ed-Fi-Databases and checkout tag 1.0.0-alpha2  or tag roadrunner-alpha2.

<?xml version="1.0" encoding="utf-8"?>
<log4net>
  <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender">
    <threshold value="INFO" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread] %-5level %logger{1} - %message%newline" />
    </layout>
  </appender>
  <appender name="FileAppender" type="log4net.Appender.FileAppender">
    <threshold value="DEBUG" />
    <file value="Ed-Fi-Db-Deploy.log" />
    <appendToFile value="true" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread] %-5level %logger{1} - %message%newline" />
    </layout>
  </appender>
  <root>
    <appender-ref ref="ConsoleAppender" />
    <appender-ref ref="FileAppender" />
  </root>
</log4net>

New Deploy Verb

For detailed examples, run the tool with no arguments provided and view the output, or see the readme.

The command syntax has shifted to use a verb format to indicate what action to take. This paves the way for some future verbs. The key verb for deployment is deploy , which will run the DbUp-based migrations. There is also a new argument flag ( -d  or --databaseType) to indicate which database you wish to install (Admin, ODS, or Security). For example, assuming dotnet tool install  was run as shown above, the following command will install the Admin database on Postgres:

EdFi.Db.Deploy deploy -d Admin -c "server=localhost;database=EdFi_Admin;username=…;password=…" -p PostgreSQL

Installing Change Queries

Change queries support is only for SQL Server at this time. Use argument -f Changes  to install.

EdFi.Db.Deploy deploy -d ODS -c "server=localhost;database=EdFi_ODS;integrated security=sspi" -p SqlServer -f Changes

Installing Extensions

While RoadRunner will not officially support extensions, this tool will be incorporated into initdev in the near future and must be able to install extensions for SQL Server-based ODS implementations. Use argument -x  to deploy extensions, providing a list of "supporting artifacts" directories.

$supportingArtifacts = @(
  "C:\Source\3.x\Ed-Fi-Ods-Implementation\Application\EdFi.Ods.Extensions.GrandBend\SupportingArtifacts\Database",
  "C:\Source\3.x\Ed-Fi-Ods-Implementation\Application\EdFi.Ods.Extensions.Sample\SupportingArtifacts\Database"
)

EdFi.Db.Deploy deploy -d ODS -c "server=localhost;database=EdFi_ODS;integrated security=sspi" -p SqlServer -x $supportingArtifacts

WhatIf Verb

The whatif  verb checks to see if any scripts need to be installed without performing the installation. This functionality was added to support scenarios where you want to run a task before deploying new migration scripts to the database (e.g. run a backup). Exits with status code 1 if there are migration scripts to execute and 0 otherwise.

EdFi.Db.Deploy whatif -d ODS -c "server=localhost;database=EdFi_ODS;integrated security=sspi" -p SqlServer

# Check $LASTEXITCODE for 1 or 0

ODS/API

Authentication an authorization are now working on PostgreSQL. Check out the roadrunner-alpha2  tags in the three repositories Ed-Fi-Common, Ed-Fi-ODS, and Ed-Fi-ODS-Implementation. Be sure to install all three databases in PostgreSQL using the alpha 2 version of the DB Deploy tool (described above). If starting the ODS/API from Visual Studio, switch to the new "Npgsql" build configuration 

Doing so will automatically transform the WebApi project's web.config file using Web.Npgsql.config to apply default settings. You will need to adjust the PostgreSQL connection strings in your copy of the Npgsql.config transform file to adjust your installation. This config transform shows all of the required configuration elements for a successful deployment to a server. Only startup Swagger and the WebAPI, as the sandbox Admin Web is not supported on PostgreSQL

In order to test the authentication and authorization processes, you will need to populate some data into the EdFi_Admin and EdFi_Security databases. There are two SQL scripts attached to ODS-3433 that will create very basic security data, including sample key/secret of "testKey" / "testSecret". Once you have run these two scripts in their respective databases, you can try authenticating and then posting to a resource endpoint ( GET requests will fail as the sample configuration does not fully setup the claims). The POST should fail with 500 since the NHibernate mappings to the ODS are not set up yet. If you get a 401/403 then there is something wrong with the data setup in either the Admin or Security database.

POST http://localhost:54576/oauth/token HTTP/1.1
Host: localhost:54746
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dGVzdEtleTp0ZXN0U2VjcmV0

grant_type=client_credentials

Capture bearer token from the response:

{
  "access_token": "b519347ee4df46a1808ccf2b07a3db27",
  "expires_in": 1800,
  "token_type": "bearer"
}

Use that bearer token to perform a POST, and then confirm in the ODS/API log file that the ODS mappings are the source of the 500 (as desired/expected at this point).

POST http://localhost:54576/data/v3/ed-fi/academicWeeks HTTP/1.1
Host: localhost:54746
Content-Type: application/json
Authorization: Bearer b519347ee4df46a1808ccf2b07a3db27
Content-Length: 332

{
  "weekIdentifier": "asdfasdfasdf5",
  "schoolReference": {
    "schoolId": 255901001
  },
  "beginDate": "2011-02-22",
  "endDate": "2019-02-28",
  "totalInstructionalDays": 0
}

Coming Soon

• NHibernate mappings for the ODS database on PostgreSQL.
• Populated and minimal template data sets for PostgreSQL.

Providing Feedback

Have feedback on this pre-release code? Three available channels:

• Slack #roadrunner is a good place for general Q&A and discussion.
• Drop a comment at the bottom of this page to share additional documentation notes.
• Found a bug? Please create a Bug Report in the ODS project.