diff --git a/README.md b/README.md index fd73789..222d2ca 100644 --- a/README.md +++ b/README.md @@ -238,7 +238,7 @@ You development/testing flow should look like this: * You trigger your test command. 1..n test runners/processes start in parallel * **Once** per test runner/process: * Get migrations/fixtures files `hash` over all related database files - * `InitializeTemplate: POST /templates`: attempt to create a new PostgreSQL template database identifying though the above hash `payload: {"hash": "string"}` + * `InitializeTemplate: POST /api/v1/templates`: attempt to create a new PostgreSQL template database identified by the above hash `payload: {"hash": "string"}` * `StatusOK: 200` * Truncate * Apply all migrations @@ -417,7 +417,7 @@ This is actually the (simplified) strategy, that we have used in [allaboutapps-b Here's a quick benchmark of how this strategy typically performed back then: -``` +```bash --- -------------------------------- --- replicas switched: 50 avg=11ms min=1ms max=445ms replicas awaited: 1 prebuffer=8 avg=436ms max=436ms @@ -449,7 +449,7 @@ The cool thing about having a warm pool of replicas setup in the background, is Let's look at a sightly bigger testsuite and see how this approach may possibly scale: -``` +```bash --- ----------------------------------- --- replicas switched: 280 avg=26ms min=11ms max=447ms replicas awaited: 1 prebuffer=8 avg=417ms max=417ms diff --git a/docs/arch-1.svg b/docs/arch-1.svg new file mode 100644 index 0000000..47f51bf --- /dev/null +++ b/docs/arch-1.svg @@ -0,0 +1 @@ +ServerManagerTemplate[]templateCollectionHashPool[]poolCollectionHashPoolTestDatabasedatabaseTemplateTemplateDatabasedatabaseTestDatabaseintIDDatabasedatabaseTemplateDatabaseDatabasedatabaseDatabasestringTemplateHashConfigDatabaseConfigownshashasmanagessetsisis \ No newline at end of file diff --git a/docs/arch-2.svg b/docs/arch-2.svg new file mode 100644 index 0000000..ce33a3b --- /dev/null +++ b/docs/arch-2.svg @@ -0,0 +1 @@ +
Task EXTEND
HashPool
TestDatabase
init
GetTestDatabase()
ReturnTestDatabase()
RecreateTestDatabase()
Task CLEAN_DIRTY
generation++
retry (still in use)
ready
dirty
recreating
 \ No newline at end of file diff --git a/docs/arch.md b/docs/arch.md new file mode 100644 index 0000000..e13f481 --- /dev/null +++ b/docs/arch.md @@ -0,0 +1,27 @@ + + +# IntegreSQL Architecture + +## Pool structure + +The following describes the relationship between the components of IntegreSQL. + +![diagram](./arch-1.svg) + +## TestDatabase states + +The following describes the state and transitions of a TestDatabase. + +![diagram](./arch-2.svg) \ No newline at end of file diff --git a/docs/arch.template.md b/docs/arch.template.md new file mode 100644 index 0000000..a2a8366 --- /dev/null +++ b/docs/arch.template.md @@ -0,0 +1,70 @@ + + +# IntegreSQL Architecture + +## Pool structure + +The following describes the relationship between the components of IntegreSQL. + +```mermaid +erDiagram + Server ||--o| Manager : owns + Manager { + Template[] templateCollection + HashPool[] poolCollection + } + Manager ||--o{ HashPool : has + Manager ||--o{ Template : has + Template { + TemplateDatabase database + } + HashPool { + TestDatabase database + } + HashPool ||--o{ TestDatabase : "manages" + Template ||--|| TemplateDatabase : "sets" + TestDatabase { + int ID + Database database + } + TemplateDatabase { + Database database + } + Database { + string TemplateHash + Config DatabaseConfig + } + TestDatabase o|--|| Database : "is" + TemplateDatabase o|--|| Database : "is" +``` + +## TestDatabase states + +The following describes the state and transitions of a TestDatabase. + +```mermaid +stateDiagram-v2 + + HashPool --> TestDatabase: Task EXTEND + + state TestDatabase { + [*] --> ready: init + ready --> dirty: GetTestDatabase() + dirty --> ready: ReturnTestDatabase() + dirty --> recreating: RecreateTestDatabase()\nTask CLEAN_DIRTY + recreating --> ready: generation++ + recreating --> recreating: retry (still in use) + } +``` \ No newline at end of file diff --git a/docs/integration-1.svg b/docs/integration-1.svg new file mode 100644 index 0000000..6808002 --- /dev/null +++ b/docs/integration-1.svg @@ -0,0 +1 @@ +PostgreSQLIntegreSQLTestrunnerYouPostgreSQLIntegreSQLTestrunnerYouCompute a migrations/fixtures files hash over all related database filesCreate a new PostgreSQL template database identified a the same unique hash payload: {"hash": "string"}Parse the received database connection payload and connect to the template database.Finalize the template so it can be used!You can now get isolated test databases from the pool!In case you have multiple testrunners/processes and call with the same template hash againSome other process has already recreated a PostgreSQL template database for this hash (or is currently doing it), you can just consider the template ready at this point.Typically happens if IntegreSQL cannot communicate withPostgreSQL, fail the test runner processmake testInitializeTemplate: POST /api/v1/templatesCREATE DATABASE template_<hash>​StatusOK: 200Truncate, apply all migrations, seed all fixtures, ..., disconnect.​FinalizeTemplate: PUT /api/v1/templates/:hashStatusOK: 200InitializeTemplate: POST /api/v1/templatesStatusLocked: 423StatusServiceUnavailable: 503 \ No newline at end of file diff --git a/docs/integration.md b/docs/integration.md new file mode 100644 index 0000000..021eede --- /dev/null +++ b/docs/integration.md @@ -0,0 +1,19 @@ + + +# Integrate via REST API + +## Once per test runner/process: + +![diagram](./integration-1.svg) diff --git a/docs/integration.template.md b/docs/integration.template.md new file mode 100644 index 0000000..3de450a --- /dev/null +++ b/docs/integration.template.md @@ -0,0 +1,57 @@ + + +# Integrate via REST API + +## Once per test runner/process: + +```mermaid +sequenceDiagram + You->>Testrunner: make test + + Note right of Testrunner: Compute a migrations/fixtures files hash over all related database files + + + Testrunner->>IntegreSQL: InitializeTemplate: POST /api/v1/templates + + Note over Testrunner,IntegreSQL: Create a new PostgreSQL template database
identified a the same unique hash
payload: {"hash": "string"} + + IntegreSQL->>PostgreSQL: CREATE DATABASE
template_ + PostgreSQL-->>IntegreSQL: + + IntegreSQL-->>Testrunner: StatusOK: 200 + + Note over Testrunner,PostgreSQL: Parse the received database connection payload and connect to the template database. + + Testrunner->>PostgreSQL: Truncate, apply all migrations, seed all fixtures, ..., disconnect. + PostgreSQL-->>Testrunner: + + Note over Testrunner,IntegreSQL: Finalize the template so it can be used! + + Testrunner->>IntegreSQL: FinalizeTemplate: PUT /api/v1/templates/:hash + IntegreSQL-->>Testrunner: StatusOK: 200 + + Note over Testrunner,IntegreSQL: You can now get isolated test databases from the pool! + + Note over Testrunner,IntegreSQL: In case you have multiple testrunners/processes
and call with the same template hash again + + Testrunner->>IntegreSQL: InitializeTemplate: POST /api/v1/templates + IntegreSQL-->>Testrunner: StatusLocked: 423 + + Note over Testrunner,IntegreSQL: Some other process has already recreated
a PostgreSQL template database for this hash
(or is currently doing it), you can just consider
the template ready at this point. + + IntegreSQL-->>Testrunner: StatusServiceUnavailable: 503 + + Note over Testrunner,IntegreSQL: Typically happens if IntegreSQL cannot communicate with
PostgreSQL, fail the test runner process +```