Skip to content

Commit 972ca20

Browse files
auxesisauxesis
authored
Merge pull request #81 from cipherstash/docs/add-more-details-ci-docs
Explain how testing and CI works in more detail
2 parents 1373d67 + 2e90937 commit 972ca20

File tree

2 files changed

+194
-15
lines changed

2 files changed

+194
-15
lines changed

‎README.md

Lines changed: 185 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,8 @@ Store encrypted data alongside your existing data:
4141
- [How is data encrypted in the database?](#how-is-data-encrypted-in-the-database)
4242
- [Helper packages](#helper-packages-and-examples)
4343
- [Releasing](#releasing)
44+
- [Developing](#developing)
45+
- [Testing](#testing)
4446

4547
---
4648

@@ -393,20 +395,14 @@ To cut a [release](https://github.com/cipherstash/encrypt-query-language/release
393395

394396
This will trigger the [Release EQL](https://github.com/cipherstash/encrypt-query-language/actions/workflows/release-eql.yml) workflow, which will build and attach artifacts to [the release](https://github.com/cipherstash/encrypt-query-language/releases/).
395397

396-
## Testing
397-
398-
There are tests for EQL for PostgreSQL versions 14–17.
399-
400-
They easiest way to run them is in [GitHub Actions](https://github.com/cipherstash/encrypt-query-language/actions/workflows/test-eql.yml).
401-
402-
### Running tests locally
398+
## Developing
403399

404400
> [!IMPORTANT]
405-
> **Before you run the tests** you need to have this software installed:
401+
> **Before you follow the quickstart* you need to have this software installed:
406402
> - [mise](https://mise.jdx.dev/) — see the [installing mise](#installing-mise) instructions
407403
> - [Docker](https://www.docker.com/) — see Docker's [documentation for installing](https://docs.docker.com/get-started/get-docker/)
408404
409-
To run tests locally:
405+
Local development quickstart:
410406

411407
``` shell
412408
# Clone the repo
@@ -416,17 +412,190 @@ cd encrypt-query-language
416412
# Install dependencies
417413
mise trust --yes
418414

419-
# Start a postgres instance
420-
mise run postgres:up postgres-17 --extra-args "--detach --wait"
415+
# Build EQL installer and uninstaller, outputting to release/
416+
mise run build
417+
418+
# Start a postgres instance (defaults to PostgreSQL 17)
419+
mise run postgres:up --extra-args "--detach --wait"
420+
421+
# Run the tests (defaults to PostgreSQL 17)
422+
mise run test
423+
424+
# Stop and remove all containers and networks
425+
mise run postgres:down
426+
```
427+
428+
### Installing mise
429+
430+
> [!IMPORTANT]
431+
> You must complete this step to set up a local development environment.
432+
433+
Local development and task running in CI is managed through [mise](https://mise.jdx.dev/).
434+
435+
To install mise:
436+
437+
- If you're on macOS, run `brew install mise`
438+
- If you're on another platform, check out the mise [installation methods documentation](https://mise.jdx.dev/installing-mise.html#installation-methods)
439+
440+
Then add mise to your shell:
441+
442+
```shell
443+
# If you're running Bash
444+
echo 'eval "$(mise activate bash)"' >> ~/.bashrc
445+
446+
# If you're running Zsh
447+
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
448+
```
449+
450+
We use [`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall) for faster installation of tools installed via `mise` and Cargo.
451+
We install `cargo-binstall` via `mise` when installing development and testing dependencies.
452+
453+
> [!TIP]
454+
> We provide abbreviations for most of the commands that follow.
455+
> For example, `mise run postgres:setup` can be abbreviated to `mise r s`.
456+
> Run `mise tasks --extended` to see the task shortcuts.
457+
458+
### How this project is organised
459+
460+
Development is managed through [mise](https://mise.jdx.dev/), both locally and [in CI](https://github.com/cipherstash/encrypt-query-language/actions).
461+
462+
mise has tasks for:
463+
464+
- Building EQL install and uninstall scripts (`build`)
465+
- Starting and stopping PostgreSQL containers (`postgres:up`, `postgres:down`)
466+
- Running unit and integration tests (`test`, `reset`)
421467

422-
# Run the tests
423-
mise run test --postgres 17
468+
These are the important files in the repo:
469+
470+
```
471+
.
472+
├── mise.toml <-- the main config file for mise
473+
├── tasks/ <-- mise tasks
474+
├── sql/ <-- The individual SQL components that make up EQL
475+
├── docs/ <-- Tutorial, reference, and concept documentation
476+
├── tests/ <-- Unit and integration tests
477+
│ ├── docker-compose.yml <-- Docker configuration for running PostgreSQL instances
478+
│ └── *.sql <-- Individual unit and integration tests
479+
├── release/ <-- Build artifacts produced by the `build` task
480+
├── examples/ <-- Example uses of EQL in different languages
481+
└── playground/ <-- Playground enviroment for experimenting with EQL and CipherStash Proxy
482+
```
483+
484+
## Testing
485+
486+
There are tests for checking EQL against PostgreSQL versions 14–17, that verify:
487+
488+
- Adding, removing, and modifying encrypted data and indexes
489+
- Validating, applying, and removing configuration for encrypted data and encrypted indexes
490+
- Validating schemas for EQL configuration, encrypted data, and encrypted indexes
491+
- Using PostgreSQL operators on encrypted data and indexes (`=`, `<>`, `@>`)
492+
493+
The easiest way to run the tests [is in GitHub Actions](./.github/workflows/test-eql.yml):
494+
495+
- Automatically whenever there are changes in the `sql/`, `tests/`, or `tasks/` directories
496+
- By manually running [the workflow](https://github.com/cipherstash/encrypt-query-language/actions/workflows/test-eql.yml)
497+
498+
This is how the `test-eql.yml` workflow functions:
499+
500+
```mermaid
501+
---
502+
title: Testing EQL
503+
---
504+
stateDiagram-v2
505+
direction LR
506+
classDef code font-family:monospace;
507+
508+
509+
state "🧍 Human makes changes to EQL sources" as changes
510+
state sources_fork <<fork>>
511+
state sources_join <<join>>
512+
state "sql/*.sql" as source_sql
513+
state "tasks/**/*" as source_tasks
514+
state "tests/**/*" as source_tests
515+
state sources_changed <<choice>>
516+
517+
state "🛠️ Trigger GitHub Actions workflow test-eql.yml" as build_triggered
518+
state "Matrix: Test EQL SQL components" as matrix
519+
state "Test with Postgres 14" as pg14
520+
state "Test with Postgres 15" as pg15
521+
state "Test with Postgres 16" as pg16
522+
state "Test with Postgres 17" as pg17
523+
state "Check build results" as check
524+
state if_state <<choice>>
525+
526+
changes --> sources_fork
527+
sources_fork --> source_sql:::code
528+
sources_fork --> source_tests:::code
529+
sources_fork --> source_tasks:::code
530+
source_sql --> sources_join
531+
source_tests --> sources_join
532+
source_tasks --> sources_join
533+
sources_join --> source_changed_check
534+
source_changed_check --> sources_changed
535+
sources_changed --> build_triggered : Some changes
536+
sources_changed --> [*]: No changes
537+
538+
state "Check source changes" as source_changed_check
539+
540+
[*] --> changes
541+
542+
build_triggered --> matrix
543+
544+
state fork_state <<fork>>
545+
matrix --> fork_state
546+
fork_state --> pg14
547+
fork_state --> pg15
548+
fork_state --> pg16
549+
fork_state --> pg17
550+
551+
state join_state <<join>>
552+
pg14 --> join_state
553+
pg15 --> join_state
554+
pg16 --> join_state
555+
pg17 --> join_state
556+
557+
state "✅ Pass build" as build_pass
558+
state "❌ Fail build" as build_fail
559+
join_state --> check
560+
check --> if_state
561+
if_state --> build_pass: All success
562+
if_state --> build_fail : Any failures
563+
build_pass --> [*]
564+
build_fail --> [*]
565+
```
566+
567+
You can also [run the tests locally](#running-tests-locally) when doing local development.
568+
569+
### Running tests locally
570+
571+
> [!IMPORTANT]
572+
> **Before you run the tests locally** you need to [set up a local dev environment](#developing).
573+
574+
To run tests locally with PostgreSQL 17:
575+
576+
``` shell
577+
# Start a postgres instance (defaults to PostgreSQL 17)
578+
mise run postgres:up --extra-args "--detach --wait"
579+
580+
# Run the tests (defaults to PostgreSQL 17)
581+
mise run test
424582

425583
# Stop and remove all containers and networks
426584
mise run postgres:down
427585
```
428586

429-
You can run the same tasks for Postgres 14, 15, 16, and 17.
587+
You can run the same tasks for Postgres 14, 15, 16, and 17 by specifying arguments:
588+
589+
```shell
590+
# Start a postgres 14 instance
591+
mise run postgres:up postgres-14 --extra-args "--detach --wait"
592+
593+
# Run the tests against postgres 14
594+
mise run test --postgres 14
595+
596+
# Stop postgres and remove all containers and networks
597+
mise run postgres:down
598+
```
430599

431600
The configuration for the Postgres containers in `tests/docker-compose.yml`.
432601

@@ -437,4 +606,5 @@ Limitations:
437606
`tests/docker-compose.yml`
438607
- **You can't run multiple Postgres containers at the same time.**
439608
All the containers bind to the same port (`7543`). If you want to run
440-
multiple containers at the same time, you'll have to change the ports.
609+
multiple containers at the same time, you have to change the ports by
610+
editing `tests/docker-compose.yml`

‎tasks/build.sh

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,12 @@ cat sql/666-rename_configuration_table.sql >> release/cipherstash-encrypt-uninst
4141
# remove the drop file
4242
rm release/cipherstash-encrypt-tmp-drop-install.sql
4343
rm release/cipherstash-encrypt-tmp-drop-uninstall.sql
44+
45+
set +x
46+
echo
47+
echo '###############################################'
48+
echo "# ✅Build succeeded"
49+
echo '###############################################'
50+
echo
51+
echo 'Installer: release/cipherstash-encrypt.sql'
52+
echo 'Uninstaller: release/cipherstash-encrypt-uninstall.sql'

0 commit comments

Comments
 (0)