diff --git a/.vale/config/vocabularies/docs/accept.txt b/.vale/config/vocabularies/docs/accept.txt index 7c9c7dc..746d83a 100644 --- a/.vale/config/vocabularies/docs/accept.txt +++ b/.vale/config/vocabularies/docs/accept.txt @@ -63,10 +63,10 @@ dialTimeout backoff backoffMultiplier disableBackoffCaps -API -DBA -DBRE -SRE +APIs? +DBAs? +DBREs? +SREs? [Uu]psert pid maxBackups @@ -93,3 +93,19 @@ Affero (?i)WAFs middleware (?i)Protobuf +startupParams +cleartext +psql +[Ss]ubcommands +(?i)APIs +grpcurl +[Tt]ensorflow +[Kk]eras +[Cc]onfigs +loadBalancer +proxied_connections +proxy_passthroughs_to_client_total +proxy_passthroughs_to_server_total +[Pp]assthroughs +api_requests_total +api_requests_errors_total diff --git a/using-gatewayd/clients.md b/using-gatewayd/clients.md index f0fd854..1cc9aee 100644 --- a/using-gatewayd/clients.md +++ b/using-gatewayd/clients.md @@ -9,7 +9,13 @@ parent: Using GatewayD # Clients -Client object is a client that can connect to the database servers over TCP, UDP and Unix Domain Socket. When GatewayD starts, a set of client objects are created that immediately connect to the users' database and are put into the [pool](/using-gatewayd/pools). Each client works independently, and a group of connections are connected to the same database server. The connection are gradually recycled. +Client object is a client that can connect to the database servers over TCP, UDP and Unix Domain Socket. When GatewayD starts, a set of client objects are created that immediately connect to the users' database and are put into the [pool](/using-gatewayd/pools). Each client works independently, and a group of connections are connected to the same database server. The connections are gradually recycled. + +## Pre-authentication + +When [`startupParams`](/using-gatewayd/global-configuration/clients#startupparams) is configured, each backend connection performs the full PostgreSQL startup handshake (including authentication) immediately after the TCP connection is established. This means pool connections are pre-authenticated and ready for queries before any database client connects. GatewayD supports trust, cleartext, MD5, and SCRAM-SHA-256 authentication methods. + +With pre-authentication enabled, GatewayD also uses a lightweight session reset (`DISCARD ALL`) when a database client disconnects, instead of closing and recreating the backend TCP connection. This is significantly cheaper than a full reconnect and reduces latency for subsequent clients. ## Pools and proxies diff --git a/using-gatewayd/connection-lifecycle.md b/using-gatewayd/connection-lifecycle.md index f030cc2..2f51d34 100644 --- a/using-gatewayd/connection-lifecycle.md +++ b/using-gatewayd/connection-lifecycle.md @@ -13,7 +13,7 @@ The connection lifecycle is the process of establishing a connection between a c The connection lifecycle is composed of the following steps: -1. GatewayD starts with a pool of client connections to database server. +1. GatewayD starts with a pool of client connections to database server. If [`startupParams`](/using-gatewayd/global-configuration/clients#startupparams) is configured, each connection performs the PostgreSQL startup handshake (including authentication) immediately, so pool connections are pre-authenticated and ready for queries. 2. The database client initiates a connection to the GatewayD. 3. GatewayD accepts the connection and assigns it to a client connection. 4. The client sends a query to the GatewayD. @@ -21,8 +21,8 @@ The connection lifecycle is composed of the following steps: 6. GatewayD receives the response from the database server. 7. GatewayD sends the response to the client. 8. Database client disconnects from GatewayD. -9. The client connection closes and a new client connection is created. -10. The new client connection is added to the pool of client connections. +9. The client connection is recycled. If `startupParams` is configured, GatewayD sends `DISCARD ALL` to reset the session state without closing the TCP connection. Otherwise, the connection is closed and a new one is created. +10. The recycled or new client connection is returned to the pool of client connections. 11. The process repeats from step 2. The above steps are partially illustrated in [traffic handling diagram](/using-gatewayd/proxies#traffic-handling) of the proxies page. diff --git a/using-gatewayd/global-configuration/clients.md b/using-gatewayd/global-configuration/clients.md index 415c284..49f226f 100644 --- a/using-gatewayd/global-configuration/clients.md +++ b/using-gatewayd/global-configuration/clients.md @@ -29,6 +29,19 @@ GatewayD supports multiple client configurations. Each client within a configura | backoff | duration (string) | 1s | Valid duration strings | The amount of time to wait before retrying a failed connection. `0s` means no backoff. | | backoffMultiplier | number | 2.0 | Positive integers | The multiplier to apply to the backoff duration. `0` means no backoff. | | disableBackoffCaps | boolean | False | True, False | Whether to disable the backoff caps for backoff multiplier and backoff duration. | +| startupParams | object | (not set) | See below | PostgreSQL startup parameters for pre-authenticating backend connections. When set, GatewayD performs the PostgreSQL startup handshake (including authentication) immediately after establishing each backend TCP connection. | + +### startupParams + +The `startupParams` option enables pre-authentication of backend pool connections. When configured, GatewayD performs the full PostgreSQL startup handshake (including authentication via trust, cleartext, MD5, or SCRAM-SHA-256) right after each backend TCP connection is established. This means pool connections are already authenticated and ready for queries when a database client connects. + +When `startupParams` is configured, GatewayD also uses a lightweight `DISCARD ALL` session reset instead of tearing down and recreating backend connections when a database client disconnects. This is significantly cheaper than a full reconnect. + +| Name | Type | Default value | Possible values | Description | +| -------- | ------ | ------------- | --------------- | ------------------------------------------------ | +| user | string | (required) | Valid username | The PostgreSQL user for backend authentication. | +| database | string | (required) | Valid database | The PostgreSQL database for backend connections. | +| password | string | (required) | Valid password | The password for backend authentication. | ```yaml clients: @@ -48,4 +61,9 @@ clients: backoff: 1s # duration backoffMultiplier: 2.0 # 0 means no backoff disableBackoffCaps: false + # PostgreSQL pre-authentication (optional) + # startupParams: + # user: postgres + # database: postgres + # password: postgres ```