Skip to content

Commit c22e654

Browse files
olavloiteolavloite
authored
docs: auto-generate connection properties documentation (googleapis#1860)
* docs: auto-generate connection properties documentation * docs: add link to README * chore: only run during test phase
1 parent 6c08ffa commit c22e654

File tree

7 files changed

+234
-23
lines changed

7 files changed

+234
-23
lines changed

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,9 @@ The Cloud Spanner JDBC driver supports the following connection URL properties.
105105
these can also be supplied in a Properties instance that is passed to the
106106
`DriverManager#getConnection(String url, Properties properties)` method.
107107

108+
See [Supported Connection Properties](documentation/connection_properties.md) for a full list of all
109+
supported connection properties.
110+
108111
#### Commonly Used Properties
109112
- credentials (String): URL for the credentials file to use for the connection. If you do not specify any credentials at all, the default credentials of the environment as returned by `GoogleCredentials#getApplicationDefault()` is used. Example: `jdbc:cloudspanner:/projects/my-project/instances/my-instance/databases/my-db;credentials=/path/to/credentials.json`
110113
- autocommit (boolean): Sets the initial autocommit mode for the connection. Default is true.
@@ -135,7 +138,8 @@ these can also be supplied in a Properties instance that is passed to the
135138
- oauthToken (string): A valid pre-existing OAuth token to use for authentication for this connection. Setting this property will take precedence over any value set for a credentials file.
136139
- lenient (boolean): Enable this to force the JDBC driver to ignore unknown properties in the connection URL. Some applications automatically add additional properties to the URL that are not recognized by the JDBC driver. Normally, the JDBC driver will reject this, unless `lenient` mode is enabled.
137140

138-
For a full list of supported connection properties see https://github.com/googleapis/java-spanner/blob/main/google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/ConnectionProperties.java.
141+
For a full list of supported connection properties, see
142+
[Supported Connection Properties](documentation/connection_properties.md).
139143

140144
### Jar with Dependencies
141145
A single jar with all dependencies can be downloaded from https://repo1.maven.org/maven2/com/google/cloud/google-cloud-spanner-jdbc/latest

‎documentation/connection_properties.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Supported Connection Properties
2+
3+
This file contains all supported connection properties for the Spanner JDBC driver. These properties can be specified both in the connection URL and in the Properties map that is used to create a connection.
4+
5+
The 'Context' value indicates whether the property can only be set when a connection is created (STARTUP), or whether the value can also be changed after a connection has been created.
6+
7+
| Name | Description | Default | Enum values | Context |
8+
|------|-------------|---------|-------------|---------|
9+
| auto_batch_dml | Automatically buffer DML statements that are executed on this connection and execute them as one batch when a non-DML statement is executed, or when the current transaction is committed. The update count that is returned for DML statements that are buffered is by default 1. This default can be changed by setting the connection variable auto_batch_dml_update_count to value other than 1. This setting is only in read/write transactions. DML statements in auto-commit mode are executed directly. | false | | USER |
10+
| auto_batch_dml_update_count | DML statements that are executed when auto_batch_dml is set to true, are not directly sent to Spanner, but are buffered in the client until the batch is flushed. This property determines the update count that is returned for these DML statements. The default is 1, as that is the update count that is expected by most ORMs (e.g. Hibernate). | 1 | | USER |
11+
| auto_batch_dml_update_count_verification | The update count that is returned for DML statements that are buffered during an automatic DML batch is by default 1. This value can be changed by setting the connection variable auto_batch_dml_update_count. The update counts that are returned by Spanner when the DML statements are actually executed are verified against the update counts that were returned when they were buffered. If these do not match, a com.google.cloud.spanner.DmlBatchUpdateCountVerificationFailedException will be thrown. You can disable this verification by setting auto_batch_dml_update_count_verification to false. | true | | USER |
12+
| autocommit | Should the connection start in autocommit (true/false) | true | | USER |
13+
| autocommit_dml_mode | Should the connection automatically retry Aborted errors (true/false) | TRANSACTIONAL | | USER |
14+
| autoconfigemulator | Automatically configure the connection to try to connect to the Cloud Spanner emulator (true/false). The instance and database in the connection string will automatically be created if these do not yet exist on the emulator. Add dialect=postgresql to the connection string to make sure that the database that is created uses the PostgreSQL dialect. | false | | STARTUP |
15+
| autopartitionmode | Execute all queries on this connection as partitioned queries. Executing a query that cannot be partitioned will fail. Executing a query in a read/write transaction will also fail. | false | | USER |
16+
| channelprovider | The name of the channel provider class. The name must reference an implementation of ExternalChannelProvider. If this property is not set, the connection will use the default grpc channel provider. | | | STARTUP |
17+
| connection_state_type | The type of connection state to use for this connection. Can only be set at start up. If no value is set, then the database dialect default will be used, which is NON_TRANSACTIONAL for GoogleSQL and TRANSACTIONAL for PostgreSQL. | | | STARTUP |
18+
| credentials | The location of the credentials file to use for this connection. If neither this property or encoded credentials are set, the connection will use the default Google Cloud credentials for the runtime environment. | | | STARTUP |
19+
| credentialsprovider | The class name of the com.google.api.gax.core.CredentialsProvider implementation that should be used to obtain credentials for connections. | | | STARTUP |
20+
| databaserole | Sets the database role to use for this connection. The default is privileges assigned to IAM role | | | STARTUP |
21+
| databoostenabled | Enable data boost for all partitioned queries that are executed by this connection. This setting is only used for partitioned queries and is ignored by all other statements. | false | | USER |
22+
| ddlintransactionmode | Determines how the connection should handle DDL statements in a read/write transaction. | ALLOW_IN_EMPTY_TRANSACTION | | USER |
23+
| delaytransactionstartuntilfirstwrite | Enabling this option will delay the actual start of a read/write transaction until the first write operation is seen in that transaction. All reads that happen before the first write in a transaction will instead be executed as if the connection was in auto-commit mode. Enabling this option will make read/write transactions lose their SERIALIZABLE isolation level. Read operations that are executed after the first write operation in a read/write transaction will be executed using the read/write transaction. Enabling this mode can reduce locking and improve performance for applications that can handle the lower transaction isolation semantics. | false | | USER |
24+
| dialect | Sets the dialect to use for new databases that are created by this connection. | GOOGLE_STANDARD_SQL | | STARTUP |
25+
| directed_read | The directed read options to apply to read-only transactions. | | | USER |
26+
| enableapitracing | Add OpenTelemetry traces for each individual RPC call. Enable this to get a detailed view of each RPC that is being executed by your application, or if you want to debug potential latency problems caused by RPCs that are being retried. | | | STARTUP |
27+
| enableendtoendtracing | Enable end-to-end tracing (true/false) to generate traces for both the time that is spent in the client, as well as time that is spent in the Spanner server. Server side traces can only go to Google Cloud Trace, so to see end to end traces, the application should configure an exporter that exports the traces to Google Cloud Trace. | false | | STARTUP |
28+
| enableextendedtracing | Include the SQL string in the OpenTelemetry traces that are generated by this connection. The SQL string is added as the standard OpenTelemetry attribute 'db.statement'. | | | STARTUP |
29+
| encodedcredentials | Base64-encoded credentials to use for this connection. If neither this property or a credentials location are set, the connection will use the default Google Cloud credentials for the runtime environment. | | | STARTUP |
30+
| endpoint | The endpoint that the JDBC driver should connect to. The default is the default Spanner production endpoint when autoConfigEmulator=false, and the default Spanner emulator endpoint (localhost:9010) when autoConfigEmulator=true. This property takes precedence over any host name at the start of the connection URL. | | | STARTUP |
31+
| keeptransactionalive | Enabling this option will trigger the connection to keep read/write transactions alive by executing a SELECT 1 query once every 10 seconds if no other statements are being executed. This option should be used with caution, as it can keep transactions alive and hold on to locks longer than intended. This option should typically be used for CLI-type application that might wait for user input for a longer period of time. | false | | USER |
32+
| lenient | Silently ignore unknown properties in the connection string/properties (true/false) | false | | STARTUP |
33+
| maxcommitdelay | The max delay that Spanner may apply to commit requests to improve throughput. | | | USER |
34+
| maxpartitionedparallelism | The max partitions hint value to use for partitioned queries. Use 0 if you do not want to specify a hint. | 1 | | USER |
35+
| maxpartitions | The max partitions hint value to use for partitioned queries. Use 0 if you do not want to specify a hint. | 0 | | USER |
36+
| maxsessions | The maximum number of sessions in the backing session pool. The default is 400. | | | STARTUP |
37+
| minsessions | The minimum number of sessions in the backing session pool. The default is 100. | | | STARTUP |
38+
| numchannels | The number of gRPC channels to use to communicate with Cloud Spanner. The default is 4. | | | STARTUP |
39+
| oauthtoken | A valid pre-existing OAuth token to use for authentication for this connection. Setting this property will take precedence over any value set for a credentials file. | | | STARTUP |
40+
| optimizerstatisticspackage | Sets the query optimizer statistics package to use for this connection. | | | USER |
41+
| optimizerversion | Sets the default query optimizer version to use for this connection. | | | USER |
42+
| read_only_staleness | The read-only staleness to use for read-only transactions and single-use queries. | strong | | USER |
43+
| readonly | Should the connection start in read-only mode (true/false) | false | | USER |
44+
| retryabortsinternally | Should the connection automatically retry Aborted errors (true/false) | true | | USER |
45+
| returncommitstats | Request that Spanner returns commit statistics for read/write transactions (true/false) | false | | USER |
46+
| routetoleader | Should read/write transactions and partitioned DML be routed to leader region (true/false) | true | | STARTUP |
47+
| rpcpriority | Sets the priority for all RPC invocations from this connection (HIGH/MEDIUM/LOW). The default is HIGH. | | | USER |
48+
| savepoint_support | Determines the behavior of the connection when savepoints are used. | FAIL_AFTER_ROLLBACK | | USER |
49+
| tracing_prefix | The prefix that will be prepended to all OpenTelemetry traces that are generated by a Connection. | CloudSpanner | | STARTUP |
50+
| trackconnectionleaks | Capture the call stack of the thread that created a connection. This will pre-create a LeakedConnectionException already when a connection is created. This can be disabled, for example if a monitoring system logs the pre-created exception. If disabled, the LeakedConnectionException will only be created when an actual connection leak is detected. The stack trace of the exception will in that case not contain the call stack of when the connection was created. | true | | STARTUP |
51+
| tracksessionleaks | Capture the call stack of the thread that checked out a session of the session pool. This will pre-create a LeakedSessionException already when a session is checked out. This can be disabled, for example if a monitoring system logs the pre-created exception. If disabled, the LeakedSessionException will only be created when an actual session leak is detected. The stack trace of the exception will in that case not contain the call stack of when the session was checked out. | true | | STARTUP |
52+
| useautosavepointsforemulator | Automatically creates savepoints for each statement in a read/write transaction when using the Emulator. This is no longer needed when using Emulator version 1.5.23 or higher. | false | | STARTUP |
53+
| useplaintext | Use a plain text communication channel (i.e. non-TLS) for communicating with the server (true/false). Set this value to true for communication with the Cloud Spanner emulator. | false | | STARTUP |
54+
| useragent | The custom user-agent property name to use when communicating with Cloud Spanner. This property is intended for internal library usage, and should not be set by applications. | | | STARTUP |
55+
| usevirtualgrpctransportthreads | Use a virtual thread instead of a platform thread for the gRPC executor (true/false). This option only has any effect if the application is running on Java 21 or higher. In all other cases, the option is ignored. | false | | STARTUP |
56+
| usevirtualthreads | Use a virtual thread instead of a platform thread for each connection (true/false). This option only has any effect if the application is running on Java 21 or higher. In all other cases, the option is ignored. | false | | STARTUP |

‎pom.xml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -334,6 +334,25 @@
334334
<groupId>org.codehaus.mojo</groupId>
335335
<artifactId>flatten-maven-plugin</artifactId>
336336
</plugin>
337+
338+
<plugin>
339+
<groupId>org.codehaus.mojo</groupId>
340+
<artifactId>exec-maven-plugin</artifactId>
341+
<executions>
342+
<execution>
343+
<id>generate_connection_properties_documentation</id>
344+
<phase>test</phase>
345+
<goals>
346+
<goal>java</goal>
347+
</goals>
348+
<configuration>
349+
<mainClass>com.google.cloud.spanner.connection.ConnectionPropertiesFileGenerator</mainClass>
350+
<classpathScope>test</classpathScope>
351+
<skip>false</skip>
352+
</configuration>
353+
</execution>
354+
</executions>
355+
</plugin>
337356
</plugins>
338357
<pluginManagement>
339358
<plugins>

‎src/main/java/com/google/cloud/spanner/connection/ConnectionPropertiesHelper.java‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
/*
2+
* Copyright 2024 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.cloud.spanner.connection;
18+
19+
import com.google.api.core.InternalApi;
20+
import com.google.common.collect.ImmutableList;
21+
import java.sql.DriverPropertyInfo;
22+
import java.util.Arrays;
23+
import java.util.Comparator;
24+
import java.util.regex.Matcher;
25+
import java.util.regex.Pattern;
26+
import java.util.stream.Collectors;
27+
28+
// TODO: Remove this class when the Connection API has made the list of properties public.
29+
@InternalApi
30+
public class ConnectionPropertiesHelper {
31+
public static ImmutableList<ConnectionProperty<?>> VALID_CONNECTION_PROPERTIES =
32+
ImmutableList.copyOf(
33+
ConnectionProperties.CONNECTION_PROPERTIES.values().stream()
34+
.sorted(Comparator.comparing(ConnectionProperty::getName))
35+
.collect(Collectors.toList()));
36+
37+
public static DriverPropertyInfo toDriverPropertyInfo(
38+
String connectionUri, ConnectionProperty<?> connectionProperty) {
39+
DriverPropertyInfo result =
40+
new DriverPropertyInfo(
41+
connectionProperty.getName(),
42+
parseUriProperty(
43+
connectionUri,
44+
connectionProperty.getName(),
45+
connectionProperty.getDefaultValue() == null
46+
? null
47+
: connectionProperty.getDefaultValue().toString()));
48+
result.description = connectionProperty.getDescription();
49+
result.choices =
50+
connectionProperty.getValidValues() == null
51+
? null
52+
: Arrays.stream(connectionProperty.getValidValues())
53+
.map(Object::toString)
54+
.toArray(String[]::new);
55+
return result;
56+
}
57+
58+
public static String getConnectionPropertyName(ConnectionProperty<?> connectionProperty) {
59+
return connectionProperty.getName();
60+
}
61+
62+
private static String parseUriProperty(String uri, String property, String defaultValue) {
63+
Pattern pattern = Pattern.compile(String.format("(?is)(?:;|\\?)%s=(.*?)(?:;|$)", property));
64+
Matcher matcher = pattern.matcher(uri);
65+
if (matcher.find() && matcher.groupCount() == 1) {
66+
return matcher.group(1);
67+
}
68+
return defaultValue;
69+
}
70+
71+
private ConnectionPropertiesHelper() {}
72+
}

‎src/main/java/com/google/cloud/spanner/jdbc/JdbcDriver.java‎

Lines changed: 6 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,8 @@
2222
import com.google.cloud.spanner.SessionPoolOptionsHelper;
2323
import com.google.cloud.spanner.SpannerException;
2424
import com.google.cloud.spanner.connection.ConnectionOptions;
25-
import com.google.cloud.spanner.connection.ConnectionOptions.ConnectionProperty;
25+
import com.google.cloud.spanner.connection.ConnectionPropertiesHelper;
26+
import com.google.cloud.spanner.connection.ConnectionProperty;
2627
import com.google.rpc.Code;
2728
import io.opentelemetry.api.OpenTelemetry;
2829
import java.sql.Connection;
@@ -265,29 +266,16 @@ public boolean acceptsURL(String url) {
265266
@Override
266267
public DriverPropertyInfo[] getPropertyInfo(String url, Properties info) {
267268
String connectionUri = appendPropertiesToUrl(url.substring(5), info);
268-
DriverPropertyInfo[] res = new DriverPropertyInfo[ConnectionOptions.VALID_PROPERTIES.size()];
269+
DriverPropertyInfo[] res =
270+
new DriverPropertyInfo[ConnectionPropertiesHelper.VALID_CONNECTION_PROPERTIES.size()];
269271
int i = 0;
270-
for (ConnectionProperty prop : ConnectionOptions.VALID_PROPERTIES) {
271-
res[i] =
272-
new DriverPropertyInfo(
273-
prop.getName(),
274-
parseUriProperty(connectionUri, prop.getName(), prop.getDefaultValue()));
275-
res[i].description = prop.getDescription();
276-
res[i].choices = prop.getValidValues();
272+
for (ConnectionProperty<?> prop : ConnectionPropertiesHelper.VALID_CONNECTION_PROPERTIES) {
273+
res[i] = ConnectionPropertiesHelper.toDriverPropertyInfo(connectionUri, prop);
277274
i++;
278275
}
279276
return res;
280277
}
281278

282-
private String parseUriProperty(String uri, String property, String defaultValue) {
283-
Pattern pattern = Pattern.compile(String.format("(?is)(?:;|\\?)%s=(.*?)(?:;|$)", property));
284-
Matcher matcher = pattern.matcher(uri);
285-
if (matcher.find() && matcher.groupCount() == 1) {
286-
return matcher.group(1);
287-
}
288-
return defaultValue;
289-
}
290-
291279
@Override
292280
public int getMajorVersion() {
293281
return MAJOR_VERSION;

0 commit comments

Comments
 (0)