Package com.google.cloud.spanner.admin.database.v1 (6.58.0)

A client to Cloud Spanner API

The interfaces provided are listed below, along with usage samples.

DatabaseAdminClient

Service Description: Cloud Spanner Database Admin API

The Cloud Spanner Database Admin API can be used to: * create, drop, and list databases * update the schema of pre-existing databases * create, delete and list backups for a database * restore a database from an existing backup

Sample for DatabaseAdminClient:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 try (DatabaseAdminClient databaseAdminClient = DatabaseAdminClient.create()) {
   DatabaseName name = DatabaseName.of("[PROJECT]", "[INSTANCE]", "[DATABASE]");
   Database response = databaseAdminClient.getDatabase(name);
 }
 

Classes

DatabaseAdminClient

Service Description: Cloud Spanner Database Admin API

The Cloud Spanner Database Admin API can be used to: * create, drop, and list databases * update the schema of pre-existing databases * create, delete and list backups for a database * restore a database from an existing backup

This class provides the ability to make remote calls to the backing service through method calls that map to API methods. Sample code to get started:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 try (DatabaseAdminClient databaseAdminClient = DatabaseAdminClient.create()) {
   DatabaseName name = DatabaseName.of("[PROJECT]", "[INSTANCE]", "[DATABASE]");
   Database response = databaseAdminClient.getDatabase(name);
 }
 

Note: close() needs to be called on the DatabaseAdminClient object to clean up resources such as threads. In the example above, try-with-resources is used, which automatically calls close().

Methods
MethodDescriptionMethod Variants

ListDatabases

Lists Cloud Spanner databases.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • listDatabases(ListDatabasesRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • listDatabases(InstanceName parent)

  • listDatabases(String parent)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • listDatabasesPagedCallable()

  • listDatabasesCallable()

CreateDatabase

Creates a new Cloud Spanner database and starts to prepare it for serving. The returned long-running operation will have a name of the format <database_name>/operations/<operation_id> and can be used to track preparation of the database. The metadata field type is CreateDatabaseMetadata. The response field type is Database, if successful.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • createDatabaseAsync(CreateDatabaseRequest request)

Methods that return long-running operations have "Async" method variants that return OperationFuture, which is used to track polling of the service.

  • createDatabaseAsync(InstanceName parent, String createStatement)

  • createDatabaseAsync(String parent, String createStatement)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • createDatabaseOperationCallable()

  • createDatabaseCallable()

GetDatabase

Gets the state of a Cloud Spanner database.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • getDatabase(GetDatabaseRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • getDatabase(DatabaseName name)

  • getDatabase(String name)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • getDatabaseCallable()

UpdateDatabase

Updates a Cloud Spanner database. The returned long-running operation can be used to track the progress of updating the database. If the named database does not exist, returns NOT_FOUND.

While the operation is pending:

* The database's reconciling field is set to true. * Cancelling the operation is best-effort. If the cancellation succeeds, the operation metadata's cancel_time is set, the updates are reverted, and the operation terminates with a CANCELLED status. * New UpdateDatabase requests will return a FAILED_PRECONDITION error until the pending operation is done (returns successfully or with error). * Reading the database via the API continues to give the pre-request values.

Upon completion of the returned operation:

* The new values are in effect and readable via the API. * The database's reconciling field becomes false.

The returned long-running operation will have a name of the format projects/<project>/instances/<instance>/databases/<database>/operations/<operation_id> and can be used to track the database modification. The metadata field type is UpdateDatabaseMetadata. The response field type is Database, if successful.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • updateDatabaseAsync(UpdateDatabaseRequest request)

Methods that return long-running operations have "Async" method variants that return OperationFuture, which is used to track polling of the service.

  • updateDatabaseAsync(Database database, FieldMask updateMask)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • updateDatabaseOperationCallable()

  • updateDatabaseCallable()

UpdateDatabaseDdl

Updates the schema of a Cloud Spanner database by creating/altering/dropping tables, columns, indexes, etc. The returned long-running operation will have a name of the format <database_name>/operations/<operation_id> and can be used to track execution of the schema change(s). The metadata field type is UpdateDatabaseDdlMetadata. The operation has no response.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • updateDatabaseDdlAsync(UpdateDatabaseDdlRequest request)

Methods that return long-running operations have "Async" method variants that return OperationFuture, which is used to track polling of the service.

  • updateDatabaseDdlAsync(DatabaseName database, List<String> statements)

  • updateDatabaseDdlAsync(String database, List<String> statements)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • updateDatabaseDdlOperationCallable()

  • updateDatabaseDdlCallable()

DropDatabase

Drops (aka deletes) a Cloud Spanner database. Completed backups for the database will be retained according to their expire_time. Note: Cloud Spanner might continue to accept requests for a few seconds after the database has been deleted.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • dropDatabase(DropDatabaseRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • dropDatabase(DatabaseName database)

  • dropDatabase(String database)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • dropDatabaseCallable()

GetDatabaseDdl

Returns the schema of a Cloud Spanner database as a list of formatted DDL statements. This method does not show pending schema updates, those may be queried using the Operations API.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • getDatabaseDdl(GetDatabaseDdlRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • getDatabaseDdl(DatabaseName database)

  • getDatabaseDdl(String database)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • getDatabaseDdlCallable()

SetIamPolicy

Sets the access control policy on a database or backup resource. Replaces any existing policy.

Authorization requires spanner.databases.setIamPolicy permission on resource. For backups, authorization requires spanner.backups.setIamPolicy permission on resource.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • setIamPolicy(SetIamPolicyRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • setIamPolicy(ResourceName resource, Policy policy)

  • setIamPolicy(String resource, Policy policy)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • setIamPolicyCallable()

GetIamPolicy

Gets the access control policy for a database or backup resource. Returns an empty policy if a database or backup exists but does not have a policy set.

Authorization requires spanner.databases.getIamPolicy permission on resource. For backups, authorization requires spanner.backups.getIamPolicy permission on resource.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • getIamPolicy(GetIamPolicyRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • getIamPolicy(ResourceName resource)

  • getIamPolicy(String resource)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • getIamPolicyCallable()

TestIamPermissions

Returns permissions that the caller has on the specified database or backup resource.

Attempting this RPC on a non-existent Cloud Spanner database will result in a NOT_FOUND error if the user has spanner.databases.list permission on the containing Cloud Spanner instance. Otherwise returns an empty set of permissions. Calling this method on a backup that does not exist will result in a NOT_FOUND error if the user has spanner.backups.list permission on the containing instance.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • testIamPermissions(TestIamPermissionsRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • testIamPermissions(ResourceName resource, List<String> permissions)

  • testIamPermissions(String resource, List<String> permissions)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • testIamPermissionsCallable()

CreateBackup

Starts creating a new Cloud Spanner Backup. The returned backup long-running operation will have a name of the format projects/<project>/instances/<instance>/backups/<backup>/operations/<operation_id> and can be used to track creation of the backup. The metadata field type is CreateBackupMetadata. The response field type is Backup, if successful. Cancelling the returned operation will stop the creation and delete the backup. There can be only one pending backup creation per database. Backup creation of different databases can run concurrently.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • createBackupAsync(CreateBackupRequest request)

Methods that return long-running operations have "Async" method variants that return OperationFuture, which is used to track polling of the service.

  • createBackupAsync(InstanceName parent, Backup backup, String backupId)

  • createBackupAsync(String parent, Backup backup, String backupId)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • createBackupOperationCallable()

  • createBackupCallable()

CopyBackup

Starts copying a Cloud Spanner Backup. The returned backup long-running operation will have a name of the format projects/<project>/instances/<instance>/backups/<backup>/operations/<operation_id> and can be used to track copying of the backup. The operation is associated with the destination backup. The metadata field type is CopyBackupMetadata. The response field type is Backup, if successful. Cancelling the returned operation will stop the copying and delete the backup. Concurrent CopyBackup requests can run on the same source backup.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • copyBackupAsync(CopyBackupRequest request)

Methods that return long-running operations have "Async" method variants that return OperationFuture, which is used to track polling of the service.

  • copyBackupAsync(InstanceName parent, String backupId, BackupName sourceBackup, Timestamp expireTime)

  • copyBackupAsync(InstanceName parent, String backupId, String sourceBackup, Timestamp expireTime)

  • copyBackupAsync(String parent, String backupId, BackupName sourceBackup, Timestamp expireTime)

  • copyBackupAsync(String parent, String backupId, String sourceBackup, Timestamp expireTime)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • copyBackupOperationCallable()

  • copyBackupCallable()

GetBackup

Gets metadata on a pending or completed Backup.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • getBackup(GetBackupRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • getBackup(BackupName name)

  • getBackup(String name)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • getBackupCallable()

UpdateBackup

Updates a pending or completed Backup.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • updateBackup(UpdateBackupRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • updateBackup(Backup backup, FieldMask updateMask)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • updateBackupCallable()

DeleteBackup

Deletes a pending or completed Backup.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • deleteBackup(DeleteBackupRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • deleteBackup(BackupName name)

  • deleteBackup(String name)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • deleteBackupCallable()

ListBackups

Lists completed and pending backups. Backups returned are ordered by create_time in descending order, starting from the most recent create_time.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • listBackups(ListBackupsRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • listBackups(InstanceName parent)

  • listBackups(String parent)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • listBackupsPagedCallable()

  • listBackupsCallable()

RestoreDatabase

Create a new database by restoring from a completed backup. The new database must be in the same project and in an instance with the same instance configuration as the instance containing the backup. The returned database long-running operation has a name of the format projects/<project>/instances/<instance>/databases/<database>/operations/<operation_id>, and can be used to track the progress of the operation, and to cancel it. The metadata field type is RestoreDatabaseMetadata. The response type is Database, if successful. Cancelling the returned operation will stop the restore and delete the database. There can be only one database being restored into an instance at a time. Once the restore operation completes, a new restore operation can be initiated, without waiting for the optimize operation associated with the first restore to complete.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • restoreDatabaseAsync(RestoreDatabaseRequest request)

Methods that return long-running operations have "Async" method variants that return OperationFuture, which is used to track polling of the service.

  • restoreDatabaseAsync(InstanceName parent, String databaseId, BackupName backup)

  • restoreDatabaseAsync(InstanceName parent, String databaseId, String backup)

  • restoreDatabaseAsync(String parent, String databaseId, BackupName backup)

  • restoreDatabaseAsync(String parent, String databaseId, String backup)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • restoreDatabaseOperationCallable()

  • restoreDatabaseCallable()

ListDatabaseOperations

Lists database longrunning-operations. A database operation has a name of the form projects/<project>/instances/<instance>/databases/<database>/operations/<operation>. The long-running operation metadata field type metadata.type_url describes the type of the metadata. Operations returned include those that have completed/failed/canceled within the last 7 days, and pending operations.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • listDatabaseOperations(ListDatabaseOperationsRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • listDatabaseOperations(InstanceName parent)

  • listDatabaseOperations(String parent)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • listDatabaseOperationsPagedCallable()

  • listDatabaseOperationsCallable()

ListBackupOperations

Lists the backup long-running operations in the given instance. A backup operation has a name of the form projects/<project>/instances/<instance>/backups/<backup>/operations/<operation>. The long-running operation metadata field type metadata.type_url describes the type of the metadata. Operations returned include those that have completed/failed/canceled within the last 7 days, and pending operations. Operations returned are ordered by operation.metadata.value.progress.start_time in descending order starting from the most recently started operation.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • listBackupOperations(ListBackupOperationsRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • listBackupOperations(InstanceName parent)

  • listBackupOperations(String parent)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • listBackupOperationsPagedCallable()

  • listBackupOperationsCallable()

ListDatabaseRoles

Lists Cloud Spanner database roles.

Request object method variants only take one parameter, a request object, which must be constructed before the call.

  • listDatabaseRoles(ListDatabaseRolesRequest request)

"Flattened" method variants have converted the fields of the request object into function parameters to enable multiple ways to call the same method.

  • listDatabaseRoles(DatabaseName parent)

  • listDatabaseRoles(String parent)

Callable method variants take no parameters and return an immutable API callable object, which can be used to initiate calls to the service.

  • listDatabaseRolesPagedCallable()

  • listDatabaseRolesCallable()

See the individual methods for example code.

Many parameters require resource names to be formatted in a particular way. To assist with these names, this class includes a format method for each type of name, and additionally a parse method to extract the individual identifiers contained within names that are returned.

This class can be customized by passing in a custom instance of DatabaseAdminSettings to create(). For example:

To customize credentials:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 DatabaseAdminSettings databaseAdminSettings =
     DatabaseAdminSettings.newBuilder()
         .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
         .build();
 DatabaseAdminClient databaseAdminClient = DatabaseAdminClient.create(databaseAdminSettings);
 

To customize the endpoint:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 DatabaseAdminSettings databaseAdminSettings =
     DatabaseAdminSettings.newBuilder().setEndpoint(myEndpoint).build();
 DatabaseAdminClient databaseAdminClient = DatabaseAdminClient.create(databaseAdminSettings);
 

To use REST (HTTP1.1/JSON) transport (instead of gRPC) for sending and receiving requests over the wire:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 DatabaseAdminSettings databaseAdminSettings =
     DatabaseAdminSettings.newHttpJsonBuilder().build();
 DatabaseAdminClient databaseAdminClient = DatabaseAdminClient.create(databaseAdminSettings);
 

Please refer to the GitHub repository's samples for more quickstart code snippets.

DatabaseAdminClient.ListBackupOperationsFixedSizeCollection

DatabaseAdminClient.ListBackupOperationsPage

DatabaseAdminClient.ListBackupOperationsPagedResponse

DatabaseAdminClient.ListBackupsFixedSizeCollection

DatabaseAdminClient.ListBackupsPage

DatabaseAdminClient.ListBackupsPagedResponse

DatabaseAdminClient.ListDatabaseOperationsFixedSizeCollection

DatabaseAdminClient.ListDatabaseOperationsPage

DatabaseAdminClient.ListDatabaseOperationsPagedResponse

DatabaseAdminClient.ListDatabaseRolesFixedSizeCollection

DatabaseAdminClient.ListDatabaseRolesPage

DatabaseAdminClient.ListDatabaseRolesPagedResponse

DatabaseAdminClient.ListDatabasesFixedSizeCollection

DatabaseAdminClient.ListDatabasesPage

DatabaseAdminClient.ListDatabasesPagedResponse

DatabaseAdminSettings

Settings class to configure an instance of DatabaseAdminClient.

The default instance has everything set to sensible defaults:

  • The default service address (spanner.googleapis.com) and default port (443) are used.
  • Credentials are acquired automatically through Application Default Credentials.
  • Retries are configured for idempotent methods but not for non-idempotent methods.

The builder of this class is recursive, so contained classes are themselves builders. When build() is called, the tree of builders is called to create the complete settings object.

For example, to set the total timeout of getDatabase to 30 seconds:


 // This snippet has been automatically generated and should be regarded as a code template only.
 // It will require modifications to work:
 // - It may require correct/in-range values for request initialization.
 // - It may require specifying regional endpoints when creating the service client as shown in
 // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
 DatabaseAdminSettings.Builder databaseAdminSettingsBuilder = DatabaseAdminSettings.newBuilder();
 databaseAdminSettingsBuilder
     .getDatabaseSettings()
     .setRetrySettings(
         databaseAdminSettingsBuilder
             .getDatabaseSettings()
             .getRetrySettings()
             .toBuilder()
             .setTotalTimeout(Duration.ofSeconds(30))
             .build());
 DatabaseAdminSettings databaseAdminSettings = databaseAdminSettingsBuilder.build();
 

DatabaseAdminSettings.Builder

Builder for DatabaseAdminSettings.