Merge pull request #353 from subsquid/misc-fixes-by-abernatskiy-jan11

Streamlining the environment variables documentation

docs/cloud/reference/manifest.mdx

@@ -11,11 +11,12 @@ The deployment manifest is named `squid.yaml` by convention. The manifest define
 With the introduction of the deployment manifest the add-ons (`postgres`) and the API services (`api`) become optional. This allows flexible deployment configuration for analytic use-cases (e.g. transform and write to s3 or BigQuery).
 
 :::tip
-Cloud [secrets](/cloud/resources/env-variables/#secrets) of the squid's [organization](/cloud/resources/organizations) are exposed as the `secrets` namespace. You can set any variable defined in any of the `env:` sections mentioned below:
+Cloud [secrets](/cloud/resources/env-variables/#secrets) of the squid's [organization](/cloud/resources/organizations) are exposed as the `secrets` context. You can set any variable defined in any of the `env:` sections mentioned below:
 ```yaml
 env:
   RPC_ENDPOINT: ${{ secrets.FAST_RPC_ENDPOINT_URL }}
 ```
+See the [Environment variables](/cloud/resources/env-variables) page for more info.
 :::
 
 ## Header

docs/cloud/reference/pg.md

@@ -6,7 +6,18 @@ description: Provision and scale postgres for a squid
 
 # Postgres add-on
 
-To provision a postgres instance, add the `addons.postgres:` section to the deployment manifest. The add-on deploys a Postgres 14 instance and injects the `DB_NAME`, `DB_USER`, `DB_PASS`, `DB_PORT` environment variables to the `api` and `processor` squid services.
+To provision a postgres instance, add the `addons.postgres:` section to the deployment manifest. The add-on deploys a Postgres 14 instance and [injects variables](#variable-shadowing) with database connection params into the environment of the `api` and `processor` squid services.
+
+## Variable shadowing
+
+Any of the following variables set globally or for `api` or `processor` squid services in the [manifest](/cloud/reference/manifest) will be overwritten with Cloud-supplied values:
+ * `DB_SSL`
+ * `DB_HOST`
+ * `DB_PORT`
+ * `DB_NAME`
+ * `DB_USER`
+ * `DB_PASS`
+ * `DB_URL`
 
 ## Config options
 
@@ -78,5 +89,3 @@ scale:
       storage: 100G
       profile: medium
 ```
-
-

docs/cloud/resources/env-variables.md

@@ -2,7 +2,7 @@
 sidebar_position: 20
 title: Environment variables
 description: |- 
-  Variables, namespaces, secrets
+  Variables, contexts, secrets
 ---
 
 :::info
@@ -27,17 +27,17 @@ deploy:
     MY_SQUIDWIDE_VAR: string_value
 ```
 
-Variables can be assigned either to strings, or to member variables of [namespaces](#namespaces) provided by the service. For example, to make a processor-scoped `API_KEY` variable and populate it with the value of `secrets.API_KEY`, do this:
+Variables can be assigned either to strings, or to member variables of [contexts](#contexts) provided by the service. For example, to make a processor-scoped `API_KEY` variable and populate it with the value of `secrets.API_KEY`, do this:
 ```yaml title="squid.yaml"
 deploy:
   processor:
     env:
       RPC_ENDPOINT: ${{ secrets.API_KEY }}
 ```
 
-## Database variables shadowing
+## Variable shadowing
 
-There is one special case in which the variables defined in the manifest will get overwritten by the Cloud: [database connection settings](/sdk/reference/store/typeorm/#database-connection-parameters) are shadowed by the system-defined values whenever the [`postgres` addon](/cloud/reference/pg) is enabled. For example, in the snippet below all the `DB_*` variable definitions will be ignored:
+There is one special case in which the variables defined in the manifest will get overwritten by the Cloud: [database connection settings](/sdk/reference/store/typeorm/#database-connection-parameters) are shadowed by the system-defined values whenever the [`postgres` addon](/cloud/reference/pg) is enabled (see the [Variable shadowing](/cloud/reference/pg/#variable-shadowing) section of the addon page). For example, in the snippet below all the `DB_*` variable definitions will be ignored:
 ```yaml title="squid.yaml"
 deploy:
   addons:
@@ -51,7 +51,13 @@ deploy:
     DB_SSL: true
 ```
 
-## Namespaces
+## Contexts
+
+The Cloud exposes some useful variables via a mechanism identical to [GitHub Actions contexts](https://docs.github.com/en/actions/learn-github-actions/contexts). Namely, any string
+```
+${{ <context> }}
+```
+added to the [manifest](/cloud/reference/manifest) at any environment variable definition gets replaced by the value supplied by the Cloud.
 
 ### Secrets
 

docs/sdk/reference/store/typeorm.md

@@ -199,13 +199,10 @@ Database credentials must be supplied via the environment variables:
 * `DB_PASS` (default `postgres`)
 * `DB_SSL` (default `false`)
 * `DB_SSL_REJECT_UNAUTHORIZED` (default `true`)
-* `DB_URL` (default `undefined`)
+* `DB_URL` (default `undefined`, see the [DB_URL section](#db_url))
 
 :::info
-To take advantage of `DB_SSL_REJECT_UNAUTHORIZED`, `DB_URL` and the client-side SSL variables use the `@next` version of `typeorm-store`:
-```bash
-npm i @subsquid/typeorm-store@next
-```
+When deploying to [Cloud](/cloud) with the [Postgres addon](/cloud/reference/pg) enabled in the [manifest](/cloud/reference/manifest), any user-supplied values are overwritten for most of these variables. See [Variable shadowing](/cloud/reference/pg/#variable-shadowing).
 :::
 
 `typorm-store` also supports the following variables for connecting to databases that require client-side SSL:
@@ -226,9 +223,9 @@ sqd secrets set DB_SSL_CA < ca.crt
 
 ### `DB_URL`
 
-When set, `DB_URL` takes precedence over individual variables. Its format is as follows:
+When set, `DB_URL` takes precedence over all individual variables. Its format is as follows:
 ```
-postgres[ql]://[username[:password]@][host[:port],]/database[?parameter_list]
+postgres[ql]://[username[:password]@][host[:port]]/database[?parameter_list]
 ```
 where `parameter_list` is an `&`-separated list of assignments of SSL connection parameters:
 * `ssl=(0|1|true|false)`

docs/squid-cli/secrets.md

@@ -3,7 +3,7 @@
 
 Manage account secrets
 
-The secrets are [exposed as a namespace](/cloud/resources/env-variables/#secrets), and are accessible to all the squids deployed by the current Subsquid Cloud [organization](/cloud/resources/organizations).
+The secrets are [exposed as a context](/cloud/resources/env-variables/#secrets), and are accessible to all the squids deployed by the current Subsquid Cloud [organization](/cloud/resources/organizations).
 
 * [`sqd secrets:ls`](#sqd-secretsls)
 * [`sqd secrets:rm NAME`](#sqd-secretsrm-name)