Contributing - JordanMarr/SqlHydra GitHub Wiki

Using vs-code and devcontainer

  • To run the code within a devcontainer, you will need vs-code with the Remote-Containers extension installed.
  • Upon opening the src folder in vs-code, you should be prompted to reopen the project within a devcontainer.
  • To be able to run the tests, you will first need to manually run the SQL Server install script:
    • To initialize SQL Server after the mssql container spins up, open the mssql CLI via Docker and run bash install.sh.
    • (Please help if you think you can make this script run automatically in the docker file!)

Running Tests in devcontainer

  • From the vs-code terminal, cd to src/Tests and execute dotnet run.
  • To focus certain tests in Expecto, simply change a test or testTask to ftest or ftestTask before executing dotnet run.

Using Visual Studio or Rider

  • If you prefer to use Visual Studio or Rider, you must have the appropriate version of .NET installed (currently net5.0, but soon to be net6.0).
  • You can manually run docker-compose in the src/.devcontainer to spin up the database containers.
  • To be able to run the tests, you will first need to manually run the SQL Server install script:
    • To initialize SQL Server after the mssql container spins up, open the mssql CLI via Docker and run bash install.sh.
    • (Please help if you think you can make this script run automatically in the docker file!)
  • Tests can be run or debugged via the Visual Studio Test Explorer.

Running Tests Locally

  • To run the tests locally (not in devcontainer), you must use the DebugLocal Solution Configuration. This is because the docker containers have different ports specified for running local than they do in the devcontainer (to avoid port conflicts).

Adding New Database Tables

When contributing a bug fix or new feature that requires a custom table, you will need to add the table definition to the .sql build script for the targeted database. Then you will need to rebuild the docker container for the targeted database to run the updated script.

SQL Server:

  1. Add table to: src/.devcontainer/mssql/install.sql
  2. Run docker-compose up --build mssql from the src/.devcontainer folder.

PostgreSQL:

  1. Add table to: src/.devcontainer/postgresql/install.sql
  2. Run docker-compose up --build postgresql from the src/.devcontainer folder.

Oracle:

  1. Add a new sql file to: src/.devcontainer/oracle/oracle-sample-database/ folder.
  2. Edit runOracle.sh to add a new .sql file (near the bottom of the file).
  3. Run docker-compose up --build oracle from the src/.devcontainer folder.

Sqlite:

  1. Edit the Sqlite database file at: src/Tests/TestData/AdventureWorksLT.db.

Troubleshooting

Problem: Unable to build in devcontainer: Access Denied

when I cd into "src/Tests" and run "dotnet run" I get the following: vscode ➜ /workspace/src/tests (main ✗) $ dotnet run /usr/share/dotnet/sdk/5.0.402/Microsoft.Common.CurrentVersion.targets(4679,5): error MSB3021: Unable to copy file "/home/vscode/.nuget/packages/microsoft.build.framework/16.11.0/lib/netstandard2.0/Microsoft.Build.Framework.dll" to "bin/Debug/net5.0/Microsoft.Build.Framework.dll". Access to the path is denied. [/workspace/src/SqlHydra.Sqlite/SqlHydra.Sqlite.fsproj]"

Solution

This can occur if you have previously built the sln locally before opening in the devcontainer. The fix is to delete the sln obj and bin folders on your local pc. Once those are removed, you should be able to build and run test.