Build nuget package of grate.core too (#438)

Build nuget package of grate.core too * Add NuGet.md to grate.core, update NuGet.md for the other packages * Improve build step names
erikbra · Feb 12, 2024 · db60f7f · db60f7f
1 parent 47203c1
commit db60f7f
Show file tree

Hide file tree

Showing 8 changed files with 224 additions and 69 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -69,15 +69,17 @@ jobs:
 
   build-nuget-package:
     needs: set-version-number
-    name: Build Nuget Packages
+    name: Build Nuget
 
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        package: [  "grate.mariadb", 
-                "grate.oracle", 
+        package: [
+                "grate.core",
+                "grate.mariadb",
+                "grate.oracle",
                 "grate.postgresql",
-                "grate.sqlite", 
+                "grate.sqlite",
                 "grate.sqlserver"
               ]
     steps:
@@ -101,7 +103,7 @@ jobs:
       run: dotnet nuget push /tmp/grate/nupkg/*.nupkg --source https://api.nuget.org/v3/index.json --api-key ${{secrets.NUGET_ORG_KEY}} --skip-duplicate
 
   build-standalone:
-    name: Build
+    name: Build cli
     needs: set-version-number
 
     runs-on: ubuntu-latest

diff --git a/src/grate.core/NuGet.md b/src/grate.core/NuGet.md
@@ -0,0 +1,63 @@
+# grate
+
+grate is a SQL scripts migration runner, using plain, old SQL for migrations. No meta-language, no code, no config,
+no EF migrations. It gives you full flexibility, and full control of your migrations, and lets you use
+all the fancy features of you particular database system. You are not constrained to any lowest common
+feature set of all supported databases.
+
+# grate.core
+[![NuGet](https://img.shields.io/nuget/v/grate.core.svg)](https://www.nuget.org/packages/grate.core/)
+
+This is the core package, which does nothing by itself. You need to add a database specific package to use it.
+See below for the list of supported databases.
+
+
+# grate (dotnet tool)
+[![NuGet](https://img.shields.io/nuget/v/grate.svg)](https://www.nuget.org/packages/grate/)
+
+grate is also available as a dotnet tool, which can be installed with the following command:
+
+```shell
+dotnet tool install -g grate
+```
+
+
+## Minimal example
+The only required argument to pass to grate is a **connection string** to tell it where to find your database. 
+It will deploy to that database, looking for sql scripts in the current directory.
+
+```csharp
+[Fact]
+public async Task Run_migration_agains_target_db()
+{
+    var serviceCollection = new ServiceCollection();
+    serviceCollection.AddLogging();
+    serviceCollection.AddGrate(builder =>
+    {
+        builder
+            .WithSqlFilesDirectory("/db")
+            .WithConnectionString("mariadb/mysql connection string here")
+    })
+    .UseMariaDb(); // Important!, you need to specify the database type to use.
+    var serviceProvider = serviceCollection.BuildServiceProvider();
+    var grateMigrator = serviceProvider.GetRequiredService<IGrateMigrator>();
+    await grateMigrator.Migrate();
+}
+```
+
+for more configuration options, see the [documentation](https://erikbra.github.io/grate/configuration-options/).
+
+
+## grate supports the following DMBS's
+
+| Database  | NuGet package |
+|--|--|
+| Microsoft SQL server (sqlserver) | [![NuGet](https://img.shields.io/nuget/v/grate.sqlserver.svg)](https://www.nuget.org/packages/grate.sqlserver/) |
+| PostgreSQL (postgresql) | [![NuGet](https://img.shields.io/nuget/v/grate.postgresql.svg)](https://www.nuget.org/packages/grate.postgresql/) |
+| MariaDB/MySQL (mariadb) | [![NuGet](https://img.shields.io/nuget/v/grate.mariadb.svg)](https://www.nuget.org/packages/grate.mariadb/) |
+| Sqlite (sqlite) | [![NuGet](https://img.shields.io/nuget/v/grate.sqlite.svg)](https://www.nuget.org/packages/grate.sqlite/) |
+| Oracle (oracle) | [![NuGet](https://img.shields.io/nuget/v/grate.oracle.svg)](https://www.nuget.org/packages/grate.oracle/) |
+
+Full documentation can be found at [https://erikbra.github.io/grate/](https://erikbra.github.io/grate/).
+
+
diff --git a/src/grate.core/grate.core.csproj b/src/grate.core/grate.core.csproj
@@ -29,5 +29,16 @@
     <PackageReference Include="Microsoft.Extensions.Hosting"  />
     <PackageReference Include="Dapper" />
   </ItemGroup>
+
+  <ItemGroup>
+    <None Include="NuGet.md" Pack="true" PackagePath="\" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Update="NuGet.md">
+      <Pack>true</Pack>
+      <PackagePath>/</PackagePath>
+    </None>
+  </ItemGroup>
 
 </Project>
diff --git a/src/grate.mariadb/NuGet.md b/src/grate.mariadb/NuGet.md
@@ -5,7 +5,14 @@ no EF migrations. It gives you full flexibility, and full control of your migrat
 all the fancy features of you particular database system. You are not constrained to any lowest common
 feature set of all supported databases.
 
-## Minimal example
+## grate.mariadb
+
+This is the MariaDB/MySQL provider for grate. It is used to deploy SQL scripts 
+programmatically to a MariaDB or MySQL database. For command line usage, please see the
+[grate (dotnet tool)](https://www.nuget.org/packages/grate/) package.
+
+
+## Minimal code example
 The only required argument to pass to grate is a **connection string** to tell it where to find your database. 
 It will deploy to that database, looking for sql scripts in the current directory.
 
@@ -17,27 +24,38 @@ public async Task Run_migration_agains_target_db()
     serviceCollection.AddLogging();
     serviceCollection.AddGrate(builder =>
     {
-        builder.WithSqlFilesDirectory("/db")
-                .WithConnectionString("mariadb/mysql connection string here")
-                .UseMariaDb(); // Important!, you need to specify the database type to use.
-    });
+        builder
+            .WithSqlFilesDirectory("/db")
+            .WithConnectionString("mariadb/mysql connection string here")
+    })
+    .UseMariaDb(); // Important!, you need to specify the database type to use.
     var serviceProvider = serviceCollection.BuildServiceProvider();
-    var grateMigrator = serviceProvider.GetService<IGrateMigrator>();
-    await grateMigrator!.Migrate();
+    var grateMigrator = serviceProvider.GetRequiredService<IGrateMigrator>();
+    await grateMigrator.Migrate();
 }
 ```
 
 for more configuration options, see the [documentation](https://erikbra.github.io/grate/configuration-options/).
 
+## grate supports the following DMBS's
+
+| Database  | NuGet package |
+|--|--|
+| Microsoft SQL server (sqlserver) | [![NuGet](https://img.shields.io/nuget/v/grate.sqlserver.svg)](https://www.nuget.org/packages/grate.sqlserver/) |
+| PostgreSQL (postgresql) | [![NuGet](https://img.shields.io/nuget/v/grate.postgresql.svg)](https://www.nuget.org/packages/grate.postgresql/) |
+| MariaDB/MySQL (mariadb) | [![NuGet](https://img.shields.io/nuget/v/grate.mariadb.svg)](https://www.nuget.org/packages/grate.mariadb/) |
+| Sqlite (sqlite) | [![NuGet](https://img.shields.io/nuget/v/grate.sqlite.svg)](https://www.nuget.org/packages/grate.sqlite/) |
+| Oracle (oracle) | [![NuGet](https://img.shields.io/nuget/v/grate.oracle.svg)](https://www.nuget.org/packages/grate.oracle/) |
 
 
-## grate supports the following DMBS's
+## grate.core
+[![NuGet](https://img.shields.io/nuget/v/grate.core.svg)](https://www.nuget.org/packages/grate.core/)
+
+This is the core package, which does nothing by itself. It is mostly useful for writing extensions to grate, 
+or for writing your own database provider. Please feel free to create your own database provider, and submit it a pull request,
+if you need support for a database that is not supported yet.
+
 
-* Microsoft SQL server (sqlserver)
-* PostgreSQL (postgresql)
-* MariaDB/MySQL (mariadb)
-* Sqlite (sqlite)
-* Oracle (oracle)
 
 Full documentation can be found at [https://erikbra.github.io/grate/](https://erikbra.github.io/grate/).
 

diff --git a/src/grate.oracle/NuGet.md b/src/grate.oracle/NuGet.md
@@ -5,7 +5,13 @@ no EF migrations. It gives you full flexibility, and full control of your migrat
 all the fancy features of you particular database system. You are not constrained to any lowest common
 feature set of all supported databases.
 
-## Minimal example
+## grate.oracle
+
+This is the Oracle provider for grate. It is used to deploy SQL scripts
+programmatically to an Oracle database. For command line usage, please see the
+[grate (dotnet tool)](https://www.nuget.org/packages/grate/) package.
+
+## Minimal code example
 The only required argument to pass to grate is a **connection string** to tell it where to find your database. 
 It will deploy to that database, looking for sql scripts in the current directory.
 
@@ -17,13 +23,14 @@ public async Task Run_migration_agains_target_db()
     serviceCollection.AddLogging();
     serviceCollection.AddGrate(builder =>
     {
-        builder.WithSqlFilesDirectory("/db")
-                .WithConnectionString("oracle connection string here")
-                .UseOracle(); // Important!, you need to specify the database type to use.
-    });
+        builder
+            .WithSqlFilesDirectory("/db")
+            .WithConnectionString("oracle connection string here")
+    })
+    .UseOracle(); // Important!, you need to specify the database type to use.
     var serviceProvider = serviceCollection.BuildServiceProvider();
-    var grateMigrator = serviceProvider.GetService<IGrateMigrator>();
-    await grateMigrator!.Migrate();
+    var grateMigrator = serviceProvider.GetRequiredService<IGrateMigrator>();
+    await grateMigrator.Migrate();
 }
 ```
 
@@ -33,11 +40,21 @@ for more configuration options, see the [documentation](https://erikbra.github.i
 
 ## grate supports the following DMBS's
 
-* Microsoft SQL server (sqlserver)
-* PostgreSQL (postgresql)
-* MariaDB/MySQL (mariadb)
-* Sqlite (sqlite)
-* Oracle (oracle)
+| Database  | NuGet package |
+|--|--|
+| Microsoft SQL server (sqlserver) | [![NuGet](https://img.shields.io/nuget/v/grate.sqlserver.svg)](https://www.nuget.org/packages/grate.sqlserver/) |
+| PostgreSQL (postgresql) | [![NuGet](https://img.shields.io/nuget/v/grate.postgresql.svg)](https://www.nuget.org/packages/grate.postgresql/) |
+| MariaDB/MySQL (mariadb) | [![NuGet](https://img.shields.io/nuget/v/grate.mariadb.svg)](https://www.nuget.org/packages/grate.mariadb/) |
+| Sqlite (sqlite) | [![NuGet](https://img.shields.io/nuget/v/grate.sqlite.svg)](https://www.nuget.org/packages/grate.sqlite/) |
+| Oracle (oracle) | [![NuGet](https://img.shields.io/nuget/v/grate.oracle.svg)](https://www.nuget.org/packages/grate.oracle/) |
+
+## grate.core
+[![NuGet](https://img.shields.io/nuget/v/grate.core.svg)](https://www.nuget.org/packages/grate.core/)
+
+This is the core package, which does nothing by itself. It is mostly useful for writing extensions to grate,
+or for writing your own database provider. Please feel free to create your own database provider, and submit it a pull request,
+if you need support for a database that is not supported yet.
+
 
 Full documentation can be found at [https://erikbra.github.io/grate/](https://erikbra.github.io/grate/).
 

diff --git a/src/grate.postgresql/NuGet.md b/src/grate.postgresql/NuGet.md
@@ -5,7 +5,13 @@ no EF migrations. It gives you full flexibility, and full control of your migrat
 all the fancy features of you particular database system. You are not constrained to any lowest common
 feature set of all supported databases.
 
-## Minimal example
+## grate.postgresql
+
+This is the PostgreSQL provider for grate. It is used to deploy SQL scripts
+programmatically to a PostgreSQL database. For command line usage, please see the
+[grate (dotnet tool)](https://www.nuget.org/packages/grate/) package.
+
+## Minimal code example
 The only required argument to pass to grate is a **connection string** to tell it where to find your database. 
 It will deploy to that database, looking for sql scripts in the current directory.
 
@@ -17,27 +23,35 @@ public async Task Run_migration_agains_target_db()
     serviceCollection.AddLogging();
     serviceCollection.AddGrate(builder =>
     {
-        builder.WithSqlFilesDirectory("/db")
-                .WithConnectionString("postgresql connection string here")
-                .UsePostgreSql(); // Important!, you need to specify the database type to use.
-    });
+        builder
+            .WithSqlFilesDirectory("/db")
+            .WithConnectionString("postgresql connection string here")
+    })
+    .UsePostgreSql(); // Important!, you need to specify the database type to use.
     var serviceProvider = serviceCollection.BuildServiceProvider();
-    var grateMigrator = serviceProvider.GetService<IGrateMigrator>();
-    await grateMigrator!.Migrate();
+    var grateMigrator = serviceProvider.GetRequiredService<IGrateMigrator>();
+    await grateMigrator.Migrate();
 }
 ```
 
 for more configuration options, see the [documentation](https://erikbra.github.io/grate/configuration-options/).
 
+## grate supports the following DMBS's
 
+| Database  | NuGet package |
+|--|--|
+| Microsoft SQL server (sqlserver) | [![NuGet](https://img.shields.io/nuget/v/grate.sqlserver.svg)](https://www.nuget.org/packages/grate.sqlserver/) |
+| PostgreSQL (postgresql) | [![NuGet](https://img.shields.io/nuget/v/grate.postgresql.svg)](https://www.nuget.org/packages/grate.postgresql/) |
+| MariaDB/MySQL (mariadb) | [![NuGet](https://img.shields.io/nuget/v/grate.mariadb.svg)](https://www.nuget.org/packages/grate.mariadb/) |
+| Sqlite (sqlite) | [![NuGet](https://img.shields.io/nuget/v/grate.sqlite.svg)](https://www.nuget.org/packages/grate.sqlite/) |
+| Oracle (oracle) | [![NuGet](https://img.shields.io/nuget/v/grate.oracle.svg)](https://www.nuget.org/packages/grate.oracle/) |
 
-## grate supports the following DMBS's
+## grate.core
+[![NuGet](https://img.shields.io/nuget/v/grate.core.svg)](https://www.nuget.org/packages/grate.core/)
 
-* Microsoft SQL server (sqlserver)
-* PostgreSQL (postgresql)
-* MariaDB/MySQL (mariadb)
-* Sqlite (sqlite)
-* Oracle (oracle)
+This is the core package, which does nothing by itself. It is mostly useful for writing extensions to grate,
+or for writing your own database provider. Please feel free to create your own database provider, and submit it a pull request,
+if you need support for a database that is not supported yet.
 
 Full documentation can be found at [https://erikbra.github.io/grate/](https://erikbra.github.io/grate/).
 

diff --git a/src/grate.sqlite/NuGet.md b/src/grate.sqlite/NuGet.md
@@ -5,7 +5,13 @@ no EF migrations. It gives you full flexibility, and full control of your migrat
 all the fancy features of you particular database system. You are not constrained to any lowest common
 feature set of all supported databases.
 
-## Minimal example
+## grate.sqlite
+
+This is the SQLite provider for grate. It is used to deploy SQL scripts
+programmatically to a SQLite database. For command line usage, please see the
+[grate (dotnet tool)](https://www.nuget.org/packages/grate/) package.
+
+## Minimal code example
 The only required argument to pass to grate is a **connection string** to tell it where to find your database. 
 It will deploy to that database, looking for sql scripts in the current directory.
 
@@ -17,27 +23,36 @@ public async Task Run_migration_agains_target_db()
     serviceCollection.AddLogging();
     serviceCollection.AddGrate(builder =>
     {
-        builder.WithSqlFilesDirectory("/db")
-                .WithConnectionString("sqlite connection string here")
-                .UseSqlite(); // Important!, you need to specify the database type to use.
-    });
+        builder
+            .WithSqlFilesDirectory("/db")
+            .WithConnectionString("sqlite connection string here")
+    })
+    .UseSqlite(); // Important!, you need to specify the database type to use.
     var serviceProvider = serviceCollection.BuildServiceProvider();
-    var grateMigrator = serviceProvider.GetService<IGrateMigrator>();
-    await grateMigrator!.Migrate();
+    var grateMigrator = serviceProvider.GetRequiredService<IGrateMigrator>();
+    await grateMigrator.Migrate();
 }
 ```
 
+
 for more configuration options, see the [documentation](https://erikbra.github.io/grate/configuration-options/).
 
+## grate supports the following DMBS's
 
+| Database  | NuGet package |
+|--|--|
+| Microsoft SQL server (sqlserver) | [![NuGet](https://img.shields.io/nuget/v/grate.sqlserver.svg)](https://www.nuget.org/packages/grate.sqlserver/) |
+| PostgreSQL (postgresql) | [![NuGet](https://img.shields.io/nuget/v/grate.postgresql.svg)](https://www.nuget.org/packages/grate.postgresql/) |
+| MariaDB/MySQL (mariadb) | [![NuGet](https://img.shields.io/nuget/v/grate.mariadb.svg)](https://www.nuget.org/packages/grate.mariadb/) |
+| Sqlite (sqlite) | [![NuGet](https://img.shields.io/nuget/v/grate.sqlite.svg)](https://www.nuget.org/packages/grate.sqlite/) |
+| Oracle (oracle) | [![NuGet](https://img.shields.io/nuget/v/grate.oracle.svg)](https://www.nuget.org/packages/grate.oracle/) |
 
-## grate supports the following DMBS's
+## grate.core
+[![NuGet](https://img.shields.io/nuget/v/grate.core.svg)](https://www.nuget.org/packages/grate.core/)
 
-* Microsoft SQL server (sqlserver)
-* PostgreSQL (postgresql)
-* MariaDB/MySQL (mariadb)
-* Sqlite (sqlite)
-* Oracle (oracle)
+This is the core package, which does nothing by itself. It is mostly useful for writing extensions to grate,
+or for writing your own database provider. Please feel free to create your own database provider, and submit it a pull request,
+if you need support for a database that is not supported yet.
 
 Full documentation can be found at [https://erikbra.github.io/grate/](https://erikbra.github.io/grate/).