feature: the tfvars store keeps Terraform modules, their instances and the instances' variable files in PostgreSQL.

README.md

@@ -64,6 +64,7 @@ code; `vite` for the Vite helpers.
 | `readJsonObject(path, options)` | a JSON object file and its version, the SHA-256 of its bytes; optionally `{}` for a missing file |
 | `encryptionKey()`, `encrypt(text, key)`, `decrypt(encrypted, key)` | the key of the secrets and AES-256-GCM encryption; see [Credential store](#credential-store) |
 | `CredentialStore`, `credentialProblems`, `credentialValues`, `registerCredentialRoutes`, `POSTGRESQL_KIND` | the credential store; see [Credential store](#credential-store) |
+| `createTfvarsStore`, `versionOf`, `tfvarsText`, `TfModule`, `TfInstance`, `TfvarsFileStatus`, `TF_NAME_PATTERN`, `TFVARS_FILE_PATTERN`, `STATE_SCHEMA_PATTERN` | the Terraform modules, their instances and their variable files in PostgreSQL; see [Tfvars store](#tfvars-store) |
 
 ## sk-react-toolkit/web
 
@@ -79,6 +80,7 @@ code; `vite` for the Vite helpers.
 | `RowDialog`, `useValidation` | a dialog that edits a value validated by the server as it changes, and the validation hook |
 | `createBrowserSettings(keys, event)` | switches kept in localStorage and followed across tabs |
 | `CredentialsButton` | the dialog of a credential store; see [Credential store](#credential-store) |
+| `TfModule`, `TfInstance`, `TfvarsFileStatus`, `TF_NAME_PATTERN`, `TFVARS_FILE_PATTERN`, `STATE_SCHEMA_PATTERN` | the types and name patterns of the [Tfvars store](#tfvars-store) |
 
 ## sk-react-toolkit/vite
 
@@ -159,11 +161,43 @@ them; a tab with a problem has a red label. A secret shows only whether it is ke
 replaces it and Remove drops it. Save writes each store that changed, each write with the version
 the previous one answers.
 
+## Tfvars store
+
+The tfvars store keeps Terraform modules, their instances and the variable files of each
+instance in PostgreSQL, for Cloud Platform, which deploys the instances, and the configurators,
+which edit their variables. `createTfvarsStore(pool)` takes a `pg` pool and applies
+`server/sql/tfvars_store.sql` at its first use, in the schema of the connection's search path:
+
+| Table | Rows |
+| --- | --- |
+| `tf_modules` | `name`, `root`, the folder of the Terraform code, `description` and `configurator_url` |
+| `tf_instances` | `module`, `name` and `state_schema`, the schema of the instance's state in the pg backend, unique, and `created` |
+| `tf_variable_files` | `module`, `instance`, `name` (`*.tfvars.json`), `content` and `previous`, the object it replaced, as `jsonb`, and `updated` |
+
+Names of modules and instances are `TF_NAME_PATTERN`, of variable files `TFVARS_FILE_PATTERN`,
+of state schemas `STATE_SCHEMA_PATTERN`.
+
+- `modules.list()`, `modules.put(module)`, which creates or changes, and `modules.delete(name)`.
+- `instances.list(module)`, `instances.create(module, name, stateSchema)` and
+  `instances.delete(module, name)`, which deletes its variable files too.
+- `variables(module, instance)`: `read()` answers the files, their sizes and times and the
+  version, `versionOf` the files, the name and the SHA-256 of each in name order. `write(version,
+  contents)` writes files given by name as JSON text and `remove(version, name)` deletes one; both
+  lock the table, compare the version and change in one transaction, and answer `false`, changing
+  nothing, when the files changed since the version.
+
+A change the tables refuse throws `HttpError`: 409 for a name or a state schema in use and for a
+module that has instances, 404 for a module or an instance that does not exist, 400 for a name or
+a content the tables do not accept. The content of a file is the object as `jsonb` keeps it,
+written by `tfvarsText`, so the order of object keys is `jsonb`'s; arrays keep theirs.
+
 ## Development
 
 `npm install` installs the peer dependencies as development dependencies; `npm run typecheck`
-and `npm run lint` check the code. `npm run build` (`build.mjs`) builds the published package in
-`dist/`: the code compiled to JavaScript with its declarations, README.md, CHANGELOG.md and a
+and `npm run lint` check the code. `npm test` tests the tfvars store in a scratch database it
+creates and drops on the PostgreSQL server the `PG*` variables name, connected to through the
+database `postgres`. `npm run build` (`build.mjs`) builds the published package in
+`dist/`: the code compiled to JavaScript with its declarations, the SQL of the server, README.md, CHANGELOG.md and a
 `package.json` whose exports name the compiled files.
 
 ## Releases