Skip to content

docs(spanner-jdbc): update connection_properties.md documentation #14035

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
olavloite wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs(spanner-jdbc): update connection_properties.md documentation #14035

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3982f66
docs(spanner-jdbc): update connection_properties.md documentation
olavloite Aug 11, 2026
d16429b
fix(spanner-jdbc): use wildcards for excluded artifacts
olavloite Aug 11, 2026
6f77130
build(spanner-jdbc): fix GraalVM build
olavloite Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions java-spanner-jdbc/documentation/connection_properties.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,12 @@ The 'Context' value indicates whether the property can only be set when a connec
| credentialsprovider | The class name of the com.google.api.gax.core.CredentialsProvider implementation that should be used to obtain credentials for connections. | | | STARTUP |
| databaserole | Sets the database role to use for this connection. The default is privileges assigned to IAM role | | | STARTUP |
| 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 | true, false | USER |
| dcpconcurrentstreamslowwatermark | The concurrent streams low watermark in the dynamic channel pool. Only used when enableDynamicChannelPool is true. | | | STARTUP |
Comment thread
olavloite marked this conversation as resolved.
| dcpinitialchannels | The initial number of channels in the dynamic channel pool. Only used when enableDynamicChannelPool is true. The default is SpannerOptions.DEFAULT_DYNAMIC_POOL_INITIAL_SIZE (4). | | | STARTUP |
| dcpmaxchannels | The maximum number of channels in the dynamic channel pool. Only used when enableDynamicChannelPool is true. The default is SpannerOptions.DEFAULT_DYNAMIC_POOL_MAX_CHANNELS (10). | | | STARTUP |
| dcpmaxrpcperchannel | The maximum number of desired RPCs per channel in the dynamic channel pool. Only used when enableDynamicChannelPool is true. The default is null. | | | STARTUP |
Comment thread
olavloite marked this conversation as resolved.
| dcpminchannels | The minimum number of channels in the dynamic channel pool. Only used when enableDynamicChannelPool is true. The default is SpannerOptions.DEFAULT_DYNAMIC_POOL_MIN_CHANNELS (2). | | | STARTUP |
| dcpminrpcperchannel | The minimum number of desired RPCs per channel in the dynamic channel pool. Only used when enableDynamicChannelPool is true. The default is null. | | | STARTUP |
Comment thread
olavloite marked this conversation as resolved.
| ddlintransactionmode | Determines how the connection should handle DDL statements in a read/write transaction. | ALLOW_IN_EMPTY_TRANSACTION | FAIL, ALLOW_IN_EMPTY_TRANSACTION, AUTO_COMMIT_TRANSACTION | USER |
| default_isolation_level | The transaction isolation level that is used by default for read/write transactions. The default is isolation_level_unspecified, which means that the connection will use the default isolation level of the database that it is connected to. | ISOLATION_LEVEL_UNSPECIFIED | ISOLATION_LEVEL_UNSPECIFIED, SERIALIZABLE, REPEATABLE_READ | USER |
| defaultsequencekind | The default sequence kind that should be used for the database. This property is only used when a DDL statement that requires a default sequence kind is executed on this connection. | | | USER |
Expand All @@ -36,9 +39,12 @@ The 'Context' value indicates whether the property can only be set when a connec
| enabledynamicchannelpool | Enable dynamic channel pooling for automatic gRPC channel scaling. When enabled, the client will automatically scale the number of channels based on load. Setting numChannels will disable dynamic channel pooling even if this is set to true. The default is currently false (disabled), but this may change to true in a future version. Set this property explicitly to ensure consistent behavior. | | true, false | STARTUP |
| 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 | true, false | STARTUP |
| 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'. | | true, false | STARTUP |
| enablegrpcgcp | Enable or disable grpc-gcp channel pool (true/false). Setting this to false will disable grpc-gcp and use the Gax gRPC channel pool. Disabling grpc-gcp also automatically disables dynamic channel pooling, regardless of the value of enableDynamicChannelPool, as Spanner only supports dynamic channel pooling in combination with grpc-gcp. | | true, false | STARTUP |
Comment thread
olavloite marked this conversation as resolved.
| 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. WARNING: Enabling this property without proper validation can expose the application to security risks. It is intended for use with credentials from a trusted source only, as it could otherwise allow end-users to supply arbitrary credentials. For more information, seehttps://cloud.google.com/docs/authentication/client-libraries#external-credentials | | | STARTUP |
| 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 |
| grpc_interceptor_provider | The class name of a com.google.api.gax.grpc.GrpcInterceptorProvider implementation that should be used to provide interceptors for the underlying Spanner client. This is a guarded property that can only be set if the Java System Property ENABLE_GRPC_INTERCEPTOR_PROVIDER has been set to true. This property should only be set to true on systems where an untrusted user cannot modify the connection URL, as using this property will dynamically invoke the constructor of the class specified. This means that any user that can modify the connection URL, can also dynamically invoke code on the host where the application is running. | | | STARTUP |
| grpckeepalivetime | The keepalive time for gRPC connections (e.g. '120s', '20s'). Setting a lower keep-alive time (minimum 10s enforced by the gRPC library) helps detect disconnected connections faster. | | | STARTUP |
| grpckeepalivetimeout | The keepalive timeout for gRPC connections (e.g. '20s', '5s'). This determines how long the client waits for a keep-alive ping response before terminating the connection. A lower timeout helps speed up recovery during network failures. | | | STARTUP |
| isexperimentalhost | Set this value to true for communication with a Experimental Host. | false | true, false | STARTUP |
| 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 | true, false | USER |
| lenient | Silently ignore unknown properties in the connection string/properties (true/false) | false | true, false | STARTUP |
Expand All @@ -51,6 +57,7 @@ The 'Context' value indicates whether the property can only be set when a connec
| 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 |
| optimizerstatisticspackage | Sets the query optimizer statistics package to use for this connection. | | | USER |
| optimizerversion | Sets the default query optimizer version to use for this connection. | | | USER |
| password | The password to use for OPAQUE login. | | | STARTUP |
| read_lock_mode | This option controls the locking behavior for read operations and queries within a read/write transaction. It works in conjunction with the transaction's isolation level. PESSIMISTIC: Read locks are acquired immediately on read. This mode only applies to SERIALIZABLE isolation. This mode prevents concurrent modifications by locking data throughout the transaction. This reduces commit-time aborts due to conflicts, but can increase how long transactions wait for locks and the overall contention. OPTIMISTIC: Locks for reads within the transaction are not acquired on read. Instead, the locks are acquired on commit to validate that read/queried data has not changed since the transaction started. If a conflict is detected, the transaction will fail. This mode only applies to SERIALIZABLE isolation. This mode defers locking until commit, which can reduce contention and improve throughput. However, be aware that this increases the risk of transaction aborts if there's significant write competition on the same data. READ_LOCK_MODE_UNSPECIFIED: This is the default if no mode is set. The locking behavior depends on the isolation level: REPEATABLE_READ: Locking semantics default to OPTIMISTIC. However, validation checks at commit are only performed for queries using SELECT FOR UPDATE, statements with {@code LOCK_SCANNED_RANGES} hints, and DML statements. For all other isolation levels: If the read lock mode is not set, it defaults to PESSIMISTIC locking. | READ_LOCK_MODE_UNSPECIFIED | READ_LOCK_MODE_UNSPECIFIED, PESSIMISTIC, OPTIMISTIC | USER |
| read_only_staleness | The read-only staleness to use for read-only transactions and single-use queries. | strong | | USER |
| readonly | Should the connection start in read-only mode (true/false) | false | true, false | USER |
Expand All @@ -64,10 +71,12 @@ The 'Context' value indicates whether the property can only be set when a connec
| 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 | true, false | STARTUP |
| 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 | true, false | STARTUP |
| transaction_timeout | Timeout for read/write transactions. | | | USER |
| type | Specifies the type of Spanner instance to connect to (cloud or omni). Setting it to omni is mandatory when connecting to a Spanner Omni instance. | CLOUD | CLOUD, OMNI | STARTUP |
| universedomain | Configure the connection to try to connect to Spanner using a different partner Google Universe than GDU (googleapis.com). | googleapis.com | | STARTUP |
| unknownlength | Spanner does not return the length of the selected columns in query results. When returning meta-data about these columns through functions like ResultSetMetaData.getColumnDisplaySize and ResultSetMetaData.getPrecision, we must provide a value. Various client tools and applications have different ideas about what they would like to see. This property specifies the length to return for types of unknown length. | 50 | | USER |
| 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 | true, false | STARTUP |
| 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 | true, false | STARTUP |
| 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 |
| username | The username to use for OPAQUE login. | | | STARTUP |
| 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 | true, false | STARTUP |
| 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 | true, false | STARTUP |
10 changes: 10 additions & 0 deletions java-spanner-jdbc/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,16 @@
<exclude>junit:*</exclude>
</excludes>
</artifactSet>
<filters>
<filter>
<artifact>*:*</artifact>
<excludes>
<exclude>META-INF/*.SF</exclude>
<exclude>META-INF/*.DSA</exclude>
<exclude>META-INF/*.RSA</exclude>
</excludes>
</filter>
</filters>
<transformers>
<transformer
implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer" />
Expand Down
4 changes: 2 additions & 2 deletions .../META-INF/native-image/com.google.cloud/google-cloud-spanner-jdbc/native-image.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Args = --initialize-at-build-time==com.google.cloud.spanner.IntegrationTestEnv,\
Args = --initialize-at-build-time=com.google.cloud.spanner.IntegrationTestEnv,\
com.google.cloud.spanner.jdbc.it.JdbcIntegrationTestEnv,\
com.google.cloud.spanner.jdbc.it.DialectTestParameter,\
com.google.common.collect.RegularImmutableMap,\
Expand All @@ -16,4 +16,4 @@ Args = --initialize-at-build-time==com.google.cloud.spanner.IntegrationTestEnv,\
org.junit.FixMethodOrder,\
org.junit.experimental.categories.Category,\
org.junit.runners.parameterized.BlockJUnit4ClassRunnerWithParameters,\
org.junit.runners.model.FrameworkField,\
org.junit.runners.model.FrameworkField
4 changes: 3 additions & 1 deletion .../META-INF/native-image/com.google.cloud/google-cloud-spanner-jdbc/native-image.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
Args=--initialize-at-build-time=com.google.cloud.spanner.jdbc.it
Args=--initialize-at-build-time=org.junit.runner.RunWith \
--initialize-at-build-time=org.junit.experimental.categories.Category \
--initialize-at-build-time=org.junit.runners.model.FrameworkField
Loading