-
Notifications
You must be signed in to change notification settings - Fork 819
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Expose parameter status messages (GUC_REPORT) to the user
Add a new `Map PGConnection.getParameterStatuses()` method that tracks the latest values of all `GUC_REPORT` parameters reported by the server in `ParameterStatus` protocol messages from the server. The map is read-only. A convenience `PGConnection.getParameterStatus(String)` wrapper is also provided. This provides a PgJDBC equivalent to the `PQparameterStatus(...)` `libpq` API function. Extensions may define custom GUCs that are set as `GUC_REPORT` when they `DefineCustomStringVariable(...)` etc. This feature will properly handle such GUCs, allowing applications to generate parameter status change messages in their extensions and have them available to the JDBC driver without needing round trips. No assumptions are made about which server GUCs are `GUC_REPORT` or their names, so it'll work (with possible test case tweaks) on current and future server versions. Github issue #1428
- Loading branch information
Showing
11 changed files
with
430 additions
and
5 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,63 @@ | ||
--- | ||
layout: default_docs | ||
title: Physical and Logical replication API | ||
header: Chapter 9. PostgreSQL™ Extensions to the JDBC API | ||
resource: media | ||
previoustitle: Parameter Status Messages | ||
previous: server-prepare.html | ||
nexttitle: Physical and Logical replication API | ||
next: replication.html | ||
--- | ||
|
||
# Parameter Status Messages | ||
|
||
PostgreSQL supports server parameters, also called server variables or, | ||
internally, Grand Unified Configuration (GUC) variables. These variables are | ||
manipulated by the `SET` command, `postgresql.conf`, `ALTER SYSTEM SET`, `ALTER | ||
USER SET`, `ALTER DATABASE SET`, the `set_config(...)` SQL-callable function, | ||
etc. See [the PostgreSQL manual](https://www.postgresql.org/docs/current/config-setting.html). | ||
|
||
For a subset of these variables the server will *automatically report changes | ||
to the value to the client driver and application*. These variables are known | ||
internally as `GUC_REPORT` variables after the name of the flag that enables | ||
the functionality. | ||
|
||
The server keeps track of all the variable scopes and reports when a variable | ||
reverts to a prior value, so the client doesn't have to guess what the current | ||
value is and whether some server-side function could've changed it. Whenever | ||
the value changes, no matter why or how it changes, the server reports the new | ||
effective value in a *Parameter Status* protocol message to the client. PgJDBC | ||
uses many of these reports internally. | ||
|
||
As of PgJDBC 42.2.6, it also exposes the parameter status information to user | ||
applications via the PGConnection extensions interface. | ||
|
||
## Methods | ||
|
||
Two methods on `org.postgresql.PGConnection` provide the client interface to | ||
reported parameters. Parameter names are case-insensitive and case-preserving. | ||
|
||
* `Map PGConnection.getParameterStatuses()` - return a map of all reported | ||
parameters and their values. | ||
|
||
* `String PGConnection.getParameterStatus()` - shorthand to retrieve one | ||
value by name, or null if no value has been reported. | ||
|
||
See the `PGConnection` JavaDoc for details. | ||
|
||
## Example | ||
|
||
If you're working directly with a `java.sql.Connection` you can | ||
|
||
import org.postgresql.PGConnection; | ||
|
||
void my_function(Connection conn) { | ||
|
||
System.out.println("My application name is " + | ||
((PGConnection)conn).getParameterStatus("application_name")); | ||
|
||
} | ||
|
||
## Other client drivers | ||
|
||
The `libpq` equivalent is the `PQparameterStatus(...)` API function. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.