Skip to content

Commit a15754e

Browse files
author
Darcy Ye
authored
chore: add PgBouncer/RDS Proxy guidance for DATABASE_STATEMENT_TIMEOUT (#1353)
* chore: add PgBouncer/RDS Proxy guidance for DATABASE_STATEMENT_TIMEOUT * chore: update docs
1 parent 1d86b09 commit a15754e

4 files changed

Lines changed: 37 additions & 15 deletions

File tree

‎docs/concepts/core-service/configuration.md‎

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -19,20 +19,21 @@ If you run Logto via `npm start` in the project root, `NODE_ENV` will always be
1919

2020
In default values, `protocol` will be either `http` or `https` according to your HTTPS config.
2121

22-
| Key | Default Value | Type | Description |
23-
| ----------------------- | ------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
24-
| NODE_ENV | `undefined` | <code>'production' &#124; 'test' &#124; undefined</code> | What kind of environment that Logto runs in. |
25-
| PORT | `3001` | `number` | The local port that Logto listens to. |
26-
| ADMIN_PORT | `3002` | `number` | The local port that Logto Admin Console listens to. |
27-
| ADMIN_DISABLE_LOCALHOST | N/A | <code>string &#124; boolean &#124; number</code> | Set it to `1` or `true` to disable the port for Admin Console. With `ADMIN_ENDPOINT` unset, it'll completely disable the Admin Console. |
28-
| DB_URL | N/A | `string` | The [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) for Logto database. |
29-
| HTTPS_CERT_PATH | `undefined` | <code>string &#124; undefined</code> | See [Enabling HTTPS](#enabling-https) for details. |
30-
| HTTPS_KEY_PATH | `undefined` | <code>string &#124; undefined</code> | Ditto. |
31-
| TRUST_PROXY_HEADER | `false` | `boolean` | Ditto. |
32-
| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | You may specify a URL with your custom domain for online testing or production. This will also affect the value of the [OIDC issuer identifier](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). |
33-
| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | You may specify a URL with your custom domain for production (E.g. `ADMIN_ENDPOINT=https://admin.domain.com`). This will also affect the value of Admin Console Redirect URIs. |
34-
| CASE_SENSITIVE_USERNAME | `true` | `boolean` | Specifies whether the username is case-sensitive. Exercise caution when modifying this value; changes will not automatically adjust existing database data, requiring manual management. |
35-
| SECRET_VAULT_KEK | `undefined` | `string` | The Key Encryption Key (KEK) used to encrypt Data Encryption Keys (DEK) in the [Secret Vault](/secret-vault). Required for the Secret Vault to function properly. Must be a base64-encoded string. AES-256 (32 bytes) is recommended. Example: `crypto.randomBytes(32).toString('base64')` |
22+
| Key | Default Value | Type | Description |
23+
| -------------------------- | ------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
24+
| NODE_ENV | `undefined` | <code>'production' &#124; 'test' &#124; undefined</code> | What kind of environment that Logto runs in. |
25+
| PORT | `3001` | `number` | The local port that Logto listens to. |
26+
| ADMIN_PORT | `3002` | `number` | The local port that Logto Admin Console listens to. |
27+
| ADMIN_DISABLE_LOCALHOST | N/A | <code>string &#124; boolean &#124; number</code> | Set it to `1` or `true` to disable the port for Admin Console. With `ADMIN_ENDPOINT` unset, it'll completely disable the Admin Console. |
28+
| DB_URL | N/A | `string` | The [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) for Logto database. |
29+
| DATABASE_STATEMENT_TIMEOUT | N/A | `string` | (v1.36.0+) PostgreSQL `statement_timeout` in milliseconds. Use a numeric string (e.g., `5000`) to set it, or `DISABLE_TIMEOUT` to omit the startup parameter (recommended for PgBouncer/RDS Proxy). If unset or invalid, the client default is 60000 ms. |
30+
| HTTPS_CERT_PATH | `undefined` | <code>string &#124; undefined</code> | See [Enabling HTTPS](#enabling-https) for details. |
31+
| HTTPS_KEY_PATH | `undefined` | <code>string &#124; undefined</code> | Ditto. |
32+
| TRUST_PROXY_HEADER | `false` | `boolean` | Ditto. |
33+
| ENDPOINT | `'protocol://localhost:$PORT'` | `string` | You may specify a URL with your custom domain for online testing or production. This will also affect the value of the [OIDC issuer identifier](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier). |
34+
| ADMIN_ENDPOINT | `'protocol://localhost:$ADMIN_PORT'` | `string` | You may specify a URL with your custom domain for production (E.g. `ADMIN_ENDPOINT=https://admin.domain.com`). This will also affect the value of Admin Console Redirect URIs. |
35+
| CASE_SENSITIVE_USERNAME | `true` | `boolean` | Specifies whether the username is case-sensitive. Exercise caution when modifying this value; changes will not automatically adjust existing database data, requiring manual management. |
36+
| SECRET_VAULT_KEK | `undefined` | `string` | The Key Encryption Key (KEK) used to encrypt Data Encryption Keys (DEK) in the [Secret Vault](/secret-vault). Required for the Secret Vault to function properly. Must be a base64-encoded string. AES-256 (32 bytes) is recommended. Example: `crypto.randomBytes(32).toString('base64')` |
3637

3738
### Enabling HTTPS {#enabling-https}
3839

‎docs/logto-oss/deployment-and-configuration.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ You can set env directly or put a `.env` file inside the Logto project root. If
1515
### Essentials \{#essentials}
1616

1717
- `DB_URL` The [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) for Logto database.
18+
- `DATABASE_STATEMENT_TIMEOUT` (v1.36.0+) PostgreSQL `statement_timeout` in milliseconds. Use a numeric string (e.g., `5000`) or `DISABLE_TIMEOUT` for PgBouncer/RDS Proxy. See [Configuration](/concepts/core-service/configuration/) for details.
1819
- `PORT` The port that Logto listens to. Default `3001`.
1920
- `ENDPOINT` You may specify a URL with your custom domain for production (E.g. `ENDPOINT=https://logto.domain.com`). This will also affect the value of the [OIDC issuer identifier](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier).
2021

‎docs/logto-oss/get-started-with-oss.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,9 +104,10 @@ TRUST_PROXY_HEADER: 1 # Set to 1 if you have an HTTPS proxy (e.g. Nginx) in fron
104104
ENDPOINT: https://<your-logto-domain> # (Optional) Replace with your Logto endpoint URL if you are using a custom domain
105105
ADMIN_ENDPOINT: https://<your-logto-admin-domain> # (Optional) Replace with your Logto admin URL if you are using a custom domain
106106
DB_URL: postgres://username:password@your_postgres_url:port/db_name # Replace with your Postgres DSN
107+
DATABASE_STATEMENT_TIMEOUT: DISABLE_TIMEOUT # (v1.36.0+) Disable statement_timeout for PgBouncer/RDS Proxy
107108
```
108109
109-
Run the container with all the environment variables above:
110+
Run the container with the required environment variables above (optional ones are omitted below; add them as needed):
110111
111112
```bash
112113
docker run \
@@ -124,6 +125,7 @@ docker run \
124125

125126
- If you are using Docker Hub, use `svhd/logto:latest` instead of `ghcr.io/logto-io/logto:latest`.
126127
- Use `host.docker.internal` or `172.17.0.1` in `DB_URL` to refer to the host IP.
128+
- If you are using PgBouncer or RDS Proxy and see `unsupported startup parameter: statement_timeout`, set `DATABASE_STATEMENT_TIMEOUT=DISABLE_TIMEOUT` (v1.36.0+).
127129

128130
:::
129131

‎docs/logto-oss/troubleshooting-oss.mdx‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,24 @@ If you are using a custom domain rather than `localhost`, you need to set the en
4848

4949
<summary>
5050

51+
### I'm using PgBouncer or RDS Proxy and Logto fails to connect (error `unsupported startup parameter: statement_timeout`) \{#im-using-pgbouncer-or-rds-proxy-and-logto-fails-to-connect-error-unsupported-startup-parameter-statement-timeout}
52+
53+
</summary>
54+
55+
Some database proxies reject the `statement_timeout` startup parameter. Since Logto v1.36.0, you can disable sending this parameter by setting:
56+
57+
```
58+
DATABASE_STATEMENT_TIMEOUT=DISABLE_TIMEOUT
59+
```
60+
61+
If you want to set a custom timeout instead, provide a numeric string in milliseconds (for example, `5000`). When unset or invalid, Logto uses the client default of 60000 ms.
62+
63+
</details>
64+
65+
<details>
66+
67+
<summary>
68+
5169
### I'm facing CORS issues. \{#im-facing-cors-issues}
5270

5371
</summary>

0 commit comments

Comments
 (0)