diff --git a/README.md b/README.md index b3fd962..7bfcfc9 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,12 @@ The order of precedence for configured values is as follows: 1. Values provided in explicit cli arguments ( `--username`, `--password`, `--host`, `--port`, etc. ) 2. Values provided in cli `--url` 3. Values provided in `PILGRIM_*` environment variables - - Values in `PILGRIM_URL` are of lowest precedence and are overridden by their explicit `PILGRIM_*` equivalents + - Values in `PILGRIM_URL` are of lowest precedence and are overridden by their + explicit `PILGRIM_*` equivalents -By default, pilgrim will search for a `.pilgrim` file in the directory it has been run in and will use the values within to replace values that have not been provided in a higher precedence form. +By default, pilgrim will search for a `.pilgrim` file in the directory it has +been run in and will use the values within to replace values that have not been +provided in a higher precedence form. #### CLI Arguments @@ -47,8 +50,9 @@ By default, pilgrim will search for a `.pilgrim` file in the directory it has be ##### Conflicts between `--down` and `--up` -If both `--down` and `--up` are provided, `pilgrim` will return an error and will not migrate the database. -The `--script` name provided must adhere to the [migration naming convention and contain the folder it is located in](#migration-naming-convention-folder-structure). +If both `--down` and `--up` are provided, `pilgrim` will return an error and +will not migrate the database. The `--script` name provided must adhere to the +[migration naming convention and contain the folder it is located in](#migration-naming-convention-folder-structure). #### Environment Variables @@ -68,9 +72,11 @@ The `--script` name provided must adhere to the [migration naming convention and #### Migration Naming Convention & Folder Structure -`pilgrim` requires that migration files be named uniquely, and can be ordered. To ensure this, migrations -must be sorted by date, and then further within each date-named directory, the contained migration files must begin with a number. -The numbers need not be unique ( you can have multiple scripts starting with `1_`, for example ), but the name of the migration does. +`pilgrim` requires that migration files be named uniquely, and can be ordered. +To ensure this, migrations must be sorted by date, and then further within each +date-named directory, the contained migration files must begin with a number. +The numbers need not be unique ( you can have multiple scripts starting with +`1_`, for example ), but the name of the migration does. Example migration directory: @@ -89,7 +95,8 @@ migrations #### Migration Definition -Creating a pilgrim migration involves creating a regular SQL file, with some mandatory comments contained within: +Creating a pilgrim migration involves creating a regular SQL file, with some +mandatory comments contained within: ```sql -- PILGRIM::UP @@ -101,15 +108,15 @@ CREATE TABLE ... DROP TABLE ... ``` -Everything between `-- PILGRIM::UP` and `-- PILGRIM::DOWN` is run during the `--up` phase of migration. -Everything after `--PILGRIM::DOWN` to the end of the file is run during the `--down` phase of migration. +Everything between `-- PILGRIM::UP` and `-- PILGRIM::DOWN` is run during the +`--up` phase of migration. +Everything after `--PILGRIM::DOWN` to the end of the file is run during the +`--down` phase of migration. + +If a file is missing these comments, the migration will not be run, and the file +will be ignored. ## Development -This project is built using golang `1.23.1`. - -1. Checkout this repository -2. Run `go build -o target` - -This will build a `pilgrim` binary in the `target` folder. \ No newline at end of file +See [Development Documentation](./docs/README.md) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..dd55399 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# Development Documentation + +All documentation related to development of the pilgrim project is to be found +here in the `docs` folder. + +## Index + +1. [Setup](./SETUP.md) +2. [Testing](./TESTS.md) \ No newline at end of file diff --git a/docs/SETUP.md b/docs/SETUP.md new file mode 100644 index 0000000..6e0bf7b --- /dev/null +++ b/docs/SETUP.md @@ -0,0 +1,10 @@ +# Setup + +This project is built using golang `1.23.1`. + +#### Setup steps + +1. Checkout this repository +2. Run `go build -o target` + +This will build a `pilgrim` binary in the `target` folder. \ No newline at end of file diff --git a/docs/TESTS.md b/docs/TESTS.md new file mode 100644 index 0000000..4e60851 --- /dev/null +++ b/docs/TESTS.md @@ -0,0 +1,21 @@ +# Writing & Maintaining Tests + +Pilgrim's tests are written using the testify framework and mockery. + +#### Generate Mocks + +The below command, when executed from the project root, will generate mocks for +all interfaces in all packages of the project, and put them in the `mocks` +directory, under the `pilgrim_mock` package + +```bash +mockery --all --outpkg pilgrim_mock --output ./internal/mocks +``` + +#### Run Tests + +To run all tests, execute the following from the root directory + +```bash +go test ./... +``` \ No newline at end of file diff --git a/internal/pilgrim_conf_test/context_test.go b/internal/pilgrim_conf_test/context_test.go index 7b3c306..0a119df 100644 --- a/internal/pilgrim_conf_test/context_test.go +++ b/internal/pilgrim_conf_test/context_test.go @@ -75,6 +75,20 @@ func Test_PilgrimContext_CliDriverOverridesCliUrlDriver(t *testing.T) { ) } +func Test_PilgrimContext_EnvDriverOverridesEnvUrlDriver(t *testing.T) { + runTest( + func(env *pilgrim_mock.EnvVarRetriever, cli *pilgrim_mock.CliFlagRetriever) { + env.EXPECT().Driver().Return(pilgrim_conf.DbDriver_MSSQL, true) // This should be highest priority + env.EXPECT().Url().Return("postgres://env_host:5432", true) + }, + func(env *pilgrim_mock.EnvVarRetriever, cli *pilgrim_mock.CliFlagRetriever) { + ctx := pilgrim_conf.NewPilgrimContext(cli, env) + + assert.Equal(t, pilgrim_conf.DbDriver_MSSQL, ctx.UrlParts().Driver) + }, + ) +} + // func Test_PilgrimContext_EnvDriverOverridesEnvUrlDriver(t *testing.T) { // context, _, _ := createPilgrimContextWithDependencies( // map[string]string{}, diff --git a/pilgrim.go b/main.go similarity index 100% rename from pilgrim.go rename to main.go