grate.dotnet-template 0.2.0

grate dotnet-new template

This is a dotnet new template for grate, an opinionated example on how to use grate with dotnet projects to organize the SQL scripts.

Installing the template

To use the template, you first need to install it:

dotnet new install grate.dotnet-template

Using the template to create a new grate dotnet project

Given that you have installed the template, as described above, you can use the template to create new database projects:

cd /tmp/
mkdir TestProject
cd TestProject
dotnet new grate --database MyDatabase

This will give you a new project skeleton in the current directory, with a couple of scripts to run them with grate too.

A brief walk-through of the generated project.

This projects (ab)uses a .csproj file to store just SQL files, and some related tools. In the project file we override the default Build and ResolveReferences targets of msbuild, to try to avoid creating any DLLs, which we don't want. There are also a few properties that makes dotnet pack include content files in the output, and make the result appropriate for distributing SQL files instead.

The project includes a .config folder, which specifies which .net local tool to use (grate and optionally gitversion).

Using the project

For both local development, and in CI/CD scenarios, to run the database migration (which grate calls it), you need to set a couple of environment variables:

• ConnectionStrings__MyDatabase
• GrateEnvironment

then you can just run the Deploy.ps1 script. It should install grate as a .net local tool, and call it with the correct parameters.

Running locally

To migrate your local database, simply, in the project directory, run:

❯ ./Deploy.ps1 

Packaging your new project

The template creates a project fit for packaging as a .nupkg and shipping. To package it, just run

nuget pack

in your newly created project directory. This should create a .nupkg file (which is simply a zip-file with a special file structure and a different extension), which can be downloaded somewhere (build server, etc), and run.

Using your packaged project

To use your project, use some way of downloading the .nupkg, and just use the files to run the install scripts. You can use nuget, but it's not a necessity, you can just download the file from somewhere, and treat it as a zip file, if that better suits your needs.

Example, using NuGet:

❯ nuget install MyDatabase -OutputDirectory somewhere -DirectDownload -Source /tmp/MyDatabase/package/
❯ cd ./somewhere/MyDatabase.1.0.0/content/
❯ ./Deploy.ps1

Changelog

0.2.0

• grate → 1.4.0
• GitVersion.Tool → 5.11.1
• Fixed a couple of small bugs in Deploy.ps1
• Added .envrc with default, sensible variables (works only on *nix, see https://direnv.net/)