CONTRIBUTING.md

Contributing

If you're reading this, thank you so much for trying to contribute to squirrel! I tried to do my best and comment the code as much as possible and make it easy to understand. Each module also starts with a small comment to explain what it does, so it should be easier to dive in the codebase.

💡 If you feel like some pieces of code are not commented enough or are too obscure, than that's a bug! Please do reach out, I'd love to hear your feedback and make squirrel easier to contribute to!

Adding support for a new type

If you want to add support for a new postgres type there's a couple of steps to go through:

• Add a new case to squirrel/internal/database/postgres.pg_to_gleam_type turning the postgres type to the corresponding Gleam type
• If the Gleam type you're looking for is not defined then you'll also need to add a new variant to the squirrel/internal/gleam.Type type
• And then the compiler errors will guide you through all the needed steps to support the new Gleam type. In short:
  • You'll need to define how that is decoded adding a case to the squirrel/internal/query.gleam_type_to_decoder function. This is used when the type has to be read from the database
  • You'll need to define how that is encoded adding a case to the squirrel/internal/query.gleam_type_to_encoder function. This is used when the type has to be passed in as one of the query holes
  • You'll need to define how that is written down in a type signature adding a case to the squirrel/internal/query.gleam_type_to_field_type function. This is used when the type is in the values returned by the query to write down the type of the corresponding field
• And don't forget to add some tests and integration tests :)

Writing tests

squirrel uses a lot of snapshot tests, to add new tests for the code generation bits you can have a look and copy the existing ones. There's no hard requirements but I have some suggestion to write good snapshot tests:

• Have at most one snapshot per test function
• Try to keep the snapshots as small as possible. Ideally one snapshot should assert a single property of the generated code so that it is easier to focus on a specific aspect of the code when reviewing it
• Use a long descriptive title for the snapshots: a title should describe what one expects to see in the produced snapshot to guide the review process

Integration tests

Squirrel also has some integration tests to check that the generated code actually compiles and produces the expected results.

• To add a new integration test you can add a new item to the integration_tests list in test/integration_test.gleam
• To run the tests you can run the ./integration_test script in this project. Read below to set up all the required bits for tests to work

Running the tests

Most of the tests are snapshot tests that directly call the postgres.main function to let it type the queries. In order to do that squirrel will have to connect to a Postgres server at localhost's port 5432.

• In CI this is taken care of automatically
• Locally you have two options:
  • Use Docker Compose: the project comes with a docker-compose.yaml file that sets up the instance, so you can run docker compose up to start it and run your tests
  • Manually set up a Postgres server: you'll have to make sure you have a server running with a user called squirrel_test that must be able to read and write to a database called squirrel_test