Interface DatabaseAdminClient

public interface DatabaseAdminClient

Client to do admin operations on a Cloud Spanner Database.

Methods

cancelOperation(String name)

public abstract void cancelOperation(String name)

Cancels the specified long-running operation.

Parameter
NameDescription
nameString

createBackup(Backup backup)

public abstract OperationFuture<Backup,CreateBackupMetadata> createBackup(Backup backup)

Creates a new backup from a database in a Cloud Spanner. Any configuration options in the Backup instance will be included in the com.google.spanner.admin.database.v1.CreateBackupRequest.

Example to create an encrypted backup.


 BackupId backupId = BackupId.of("project", "instance", "backup-id");
 DatabaseId databaseId = DatabaseId.of("project", "instance", "database-id");
 Timestamp expireTime = Timestamp.ofTimeMicroseconds(expireTimeMicros);
 Timestamp versionTime = Timestamp.ofTimeMicroseconds(versionTimeMicros);
 EncryptionConfig encryptionConfig =
         EncryptionConfig.ofKey(
             "projects/my-project/locations/some-location/keyRings/my-keyring/cryptoKeys/my-key"));

 Backup backupToCreate = dbAdminClient
     .newBackupBuilder(backupId)
     .setDatabase(databaseId)
     .setExpireTime(expireTime)
     .setVersionTime(versionTime)
     .setEncryptionConfig(encryptionConfig)
     .build();

 OperationFuture
Parameter
NameDescription
backupBackup

the backup to be created

Returns
TypeDescription
OperationFuture<Backup,CreateBackupMetadata>
Exceptions
TypeDescription
SpannerException

createBackup(String sourceInstanceId, String backupId, String databaseId, Timestamp expireTime)

public abstract OperationFuture<Backup,CreateBackupMetadata> createBackup(String sourceInstanceId, String backupId, String databaseId, Timestamp expireTime)

Creates a new backup from a database in a Cloud Spanner instance.

Example to create a backup.


 String instance       = my_instance_id;
 String backupId       = my_backup_id;
 String databaseId     = my_database_id;
 Timestamp expireTime  = Timestamp.ofTimeMicroseconds(micros);
 OperationFuture
Parameters
NameDescription
sourceInstanceIdString

the id of the instance where the database to backup is located and where the backup will be created.

backupIdString

the id of the backup which will be created. It must conform to the regular expression a-z*[a-z0-9] and be between 2 and 60 characters in length.

databaseIdString

the id of the database to backup.

expireTimecom.google.cloud.Timestamp

the time that the backup will automatically expire.

Returns
TypeDescription
OperationFuture<Backup,CreateBackupMetadata>
Exceptions
TypeDescription
SpannerException

createDatabase(Database database, Iterable<String> statements)

public abstract OperationFuture<Database,CreateDatabaseMetadata> createDatabase(Database database, Iterable<String> statements)

Creates a database in a Cloud Spanner instance. Any configuration options in the Database instance will be included in the CreateDatabaseRequest.

Example to create an encrypted database.


 Database dbInfo =
     dbClient
         .newDatabaseBuilder(DatabaseId.of("my-project", "my-instance", "my-database"))
         .setEncryptionConfig(
             EncryptionConfig.ofKey(
                 "projects/my-project/locations/some-location/keyRings/my-keyring/cryptoKeys/my-key"))
         .build();
 Operation

See Also: also#createDatabase(String, String, Iterable)

Parameters
NameDescription
databaseDatabase
statementsIterable<String>
Returns
TypeDescription
OperationFuture<Database,CreateDatabaseMetadata>
Exceptions
TypeDescription
SpannerException

createDatabase(String instanceId, String databaseId, Iterable<String> statements)

public abstract OperationFuture<Database,CreateDatabaseMetadata> createDatabase(String instanceId, String databaseId, Iterable<String> statements)

Creates a new database in a Cloud Spanner instance.

Example to create database.


 String instanceId = my_instance_id;
 String databaseId = my_database_id;
 Operation
Parameters
NameDescription
instanceIdString

the id of the instance in which to create the database.

databaseIdString

the id of the database which will be created. It must conform to the regular expression a-z*[a-z0-9] and be between 2 and 30 characters in length

statementsIterable<String>

DDL statements to run while creating the database, for example CREATE TABLE MyTable ( ... ). This should not include CREATE DATABASE statement.

Returns
TypeDescription
OperationFuture<Database,CreateDatabaseMetadata>
Exceptions
TypeDescription
SpannerException

deleteBackup(String instanceId, String backupId)

public abstract void deleteBackup(String instanceId, String backupId)

Deletes a pending or completed backup.

Parameters
NameDescription
instanceIdString

Required. The instance where the backup exists.

backupIdString

Required. The id of the backup to delete.

dropDatabase(String instanceId, String databaseId)

public abstract void dropDatabase(String instanceId, String databaseId)

Drops a Cloud Spanner database.

Example to drop a Cloud Spanner database.


 String instanceId = my_instance_id;
 String databaseId = my_database_id;
 dbAdminClient.dropDatabase(instanceId, databaseId);
 
Parameters
NameDescription
instanceIdString
databaseIdString
Exceptions
TypeDescription
SpannerException

getBackup(String instanceId, String backupId)

public abstract Backup getBackup(String instanceId, String backupId)

Gets the current state of a Cloud Spanner database backup.

Example to get a backup.


 String instanceId = my_instance_id;
 String backupId   = my_backup_id;
 Backup backup = dbAdminClient.getBackup(instanceId, backupId);
 
Parameters
NameDescription
instanceIdString
backupIdString
Returns
TypeDescription
Backup
Exceptions
TypeDescription
SpannerException

getBackupIAMPolicy(String instanceId, String backupId)

public abstract Policy getBackupIAMPolicy(String instanceId, String backupId)

Returns the IAM policy for the given backup.

Parameters
NameDescription
instanceIdString
backupIdString
Returns
TypeDescription
com.google.cloud.Policy

getDatabase(String instanceId, String databaseId)

public abstract Database getDatabase(String instanceId, String databaseId)

Gets the current state of a Cloud Spanner database.

Example to getDatabase.


 String instanceId = my_instance_id;
 String databaseId = my_database_id;
 Database db = dbAdminClient.getDatabase(instanceId, databaseId);
 
Parameters
NameDescription
instanceIdString
databaseIdString
Returns
TypeDescription
Database
Exceptions
TypeDescription
SpannerException

getDatabaseDdl(String instanceId, String databaseId)

public abstract List<String> getDatabaseDdl(String instanceId, String databaseId)

Returns the schema of a Cloud Spanner database as a list of formatted DDL statements. This method does not show pending schema updates.

Example to get the schema of a Cloud Spanner database.


 String instanceId = my_instance_id;
 String databaseId = my_database_id;
 List<String> statementsInDb = dbAdminClient.getDatabaseDdl(instanceId, databaseId);
 
Parameters
NameDescription
instanceIdString
databaseIdString
Returns
TypeDescription
List<String>

getDatabaseIAMPolicy(String instanceId, String databaseId)

public abstract Policy getDatabaseIAMPolicy(String instanceId, String databaseId)

Returns the IAM policy for the given database.

Parameters
NameDescription
instanceIdString
databaseIdString
Returns
TypeDescription
com.google.cloud.Policy

getOperation(String name)

public abstract Operation getOperation(String name)

Gets the specified long-running operation.

Parameter
NameDescription
nameString
Returns
TypeDescription
Operation

listBackupOperations(String instanceId, Options.ListOption[] options)

public abstract Page<Operation> listBackupOperations(String instanceId, Options.ListOption[] options)

Lists long-running backup operations on the specified instance.

Parameters
NameDescription
instanceIdString
optionsListOption[]
Returns
TypeDescription
Page<Operation>

listBackups(String instanceId, Options.ListOption[] options)

public abstract Page<Backup> listBackups(String instanceId, Options.ListOption[] options)

Returns the list of Cloud Spanner backups in the given instance.

Example to get the list of Cloud Spanner backups in the given instance.


 String instanceId = my_instance_id;
 Page<Backup> page = dbAdminClient.listBackups(instanceId, Options.pageSize(1));
 List<Backup> backups = new ArrayList<>();
 while (page != null) {
   Backup backup = Iterables.getOnlyElement(page.getValues());
   dbs.add(backup);
   page = page.getNextPage();
 }
 
Parameters
NameDescription
instanceIdString
optionsListOption[]
Returns
TypeDescription
Page<Backup>

listDatabaseOperations(String instanceId, Options.ListOption[] options)

public abstract Page<Operation> listDatabaseOperations(String instanceId, Options.ListOption[] options)

Lists long-running database operations on the specified instance.

Parameters
NameDescription
instanceIdString
optionsListOption[]
Returns
TypeDescription
Page<Operation>

listDatabases(String instanceId, Options.ListOption[] options)

public abstract Page<Database> listDatabases(String instanceId, Options.ListOption[] options)

Returns the list of Cloud Spanner database in the given instance.

Example to get the list of Cloud Spanner database in the given instance.


 String instanceId = my_instance_id;
 Page<Database> page = dbAdminClient.listDatabases(instanceId, Options.pageSize(1));
 List<Database> dbs = new ArrayList<>();
 while (page != null) {
   Database db = Iterables.getOnlyElement(page.getValues());
   dbs.add(db);
   page = page.getNextPage();
 }
 
Parameters
NameDescription
instanceIdString
optionsListOption[]
Returns
TypeDescription
Page<Database>

newBackupBuilder(BackupId id)

public abstract Backup.Builder newBackupBuilder(BackupId id)

Returns a builder for a Backup object with the given id.

Parameter
NameDescription
idBackupId
Returns
TypeDescription
Backup.Builder

newDatabaseBuilder(DatabaseId id)

public abstract Database.Builder newDatabaseBuilder(DatabaseId id)

Returns a builder for a Database object with the given id.

Parameter
NameDescription
idDatabaseId
Returns
TypeDescription
Database.Builder

newRestoreBuilder(BackupId source, DatabaseId destination)

public abstract Restore.Builder newRestoreBuilder(BackupId source, DatabaseId destination)

Returns a builder for a Restore object with the given source and destination

Parameters
NameDescription
sourceBackupId
destinationDatabaseId
Returns
TypeDescription
Restore.Builder

restoreDatabase(Restore restore)

public abstract OperationFuture<Database,RestoreDatabaseMetadata> restoreDatabase(Restore restore)

Restore a database from a backup. The database that is restored will be created and may not already exist.

Example to restore an encrypted database.


 final Restore restore = dbAdminClient
     .newRestoreBuilder(
         BackupId.of("my-project", "my-instance", "my-backup"),
         DatabaseId.of("my-project", "my-instance", "my-database")
     )
     .setEncryptionConfig(EncryptionConfig.ofKey(
         "projects/my-project/locations/some-location/keyRings/my-keyring/cryptoKeys/my-key"))
     .build();

 final OperationFuture
Parameter
NameDescription
restoreRestore

a Restore instance with the backup source and destination database

Returns
TypeDescription
OperationFuture<Database,RestoreDatabaseMetadata>
Exceptions
TypeDescription
SpannerException

restoreDatabase(String backupInstanceId, String backupId, String restoreInstanceId, String restoreDatabaseId)

public abstract OperationFuture<Database,RestoreDatabaseMetadata> restoreDatabase(String backupInstanceId, String backupId, String restoreInstanceId, String restoreDatabaseId)

Restore a database from a backup. The database that is restored will be created and may not already exist.

Example to restore a database.


 String backupInstanceId   = my_instance_id;
 String backupId           = my_backup_id;
 String restoreInstanceId  = my_db_instance_id;
 String restoreDatabaseId  = my_database_id;
 OperationFuture
Parameters
NameDescription
backupInstanceIdString

the id of the instance where the backup is located.

backupIdString

the id of the backup to restore.

restoreInstanceIdString

the id of the instance where the database should be created. This may be a different instance than where the backup is stored.

restoreDatabaseIdString

the id of the database to restore to.

Returns
TypeDescription
OperationFuture<Database,RestoreDatabaseMetadata>
Exceptions
TypeDescription
SpannerException

setBackupIAMPolicy(String instanceId, String backupId, Policy policy)

public abstract Policy setBackupIAMPolicy(String instanceId, String backupId, Policy policy)

Updates the IAM policy for the given backup and returns the resulting policy. It is highly recommended to first get the current policy and base the updated policy on the returned policy. See Policy.Builder#setEtag(String) for information on the recommended read-modify-write cycle.

Parameters
NameDescription
instanceIdString
backupIdString
policycom.google.cloud.Policy
Returns
TypeDescription
com.google.cloud.Policy

setDatabaseIAMPolicy(String instanceId, String databaseId, Policy policy)

public abstract Policy setDatabaseIAMPolicy(String instanceId, String databaseId, Policy policy)

Updates the IAM policy for the given database and returns the resulting policy. It is highly recommended to first get the current policy and base the updated policy on the returned policy. See Policy.Builder#setEtag(String) for information on the recommended read-modify-write cycle.

Parameters
NameDescription
instanceIdString
databaseIdString
policycom.google.cloud.Policy
Returns
TypeDescription
com.google.cloud.Policy

testBackupIAMPermissions(String instanceId, String backupId, Iterable<String> permissions)

public abstract Iterable<String> testBackupIAMPermissions(String instanceId, String backupId, Iterable<String> permissions)

Tests for the given permissions on the specified backup for the caller.

Parameters
NameDescription
instanceIdString

the id of the instance where the backup to test is located.

backupIdString

the id of the backup to test.

permissionsIterable<String>

the permissions to test for. Permissions with wildcards (such as '', 'spanner.', 'spanner.instances.*') are not allowed.

Returns
TypeDescription
Iterable<String>

the subset of the tested permissions that the caller is allowed.

testDatabaseIAMPermissions(String instanceId, String databaseId, Iterable<String> permissions)

public abstract Iterable<String> testDatabaseIAMPermissions(String instanceId, String databaseId, Iterable<String> permissions)

Tests for the given permissions on the specified database for the caller.

Parameters
NameDescription
instanceIdString

the id of the instance where the database to test is located.

databaseIdString

the id of the database to test.

permissionsIterable<String>

the permissions to test for. Permissions with wildcards (such as '', 'spanner.', 'spanner.instances.*') are not allowed.

Returns
TypeDescription
Iterable<String>

the subset of the tested permissions that the caller is allowed.

updateBackup(String instanceId, String backupId, Timestamp expireTime)

public abstract Backup updateBackup(String instanceId, String backupId, Timestamp expireTime)

Updates the expire time of a backup.

Parameters
NameDescription
instanceIdString

Required. The instance of the backup to update.

backupIdString

Required. The backup id of the backup to update.

expireTimecom.google.cloud.Timestamp

Required. The new expire time of the backup to set to.

Returns
TypeDescription
Backup

the updated Backup object.

updateDatabaseDdl(String instanceId, String databaseId, Iterable<String> statements, String operationId)

public abstract OperationFuture<Void,UpdateDatabaseDdlMetadata> updateDatabaseDdl(String instanceId, String databaseId, Iterable<String> statements, String operationId)

Enqueues the given DDL statements to be applied, in order but not necessarily all at once, to the database schema at some point (or points) in the future. The server checks that the statements are executable (syntactically valid, name tables that exist, etc.) before enqueueing them, but they may still fail upon later execution (e.g., if a statement from another batch of statements is applied first and it conflicts in some way, or if there is some data-related problem like a NULL value in a column to which NOT NULL would be added). If a statement fails, all subsequent statements in the batch are automatically cancelled.

If an operation already exists with the given operation id, the operation will be resumed and the returned future will complete when the original operation finishes. See more information in com.google.cloud.spanner.spi.v1.GapicSpannerRpc#updateDatabaseDdl(String, Iterable, String)

Example to update the database DDL.


 String instanceId = my_instance_id;
 String databaseId = my_database_id;
 dbAdminClient.updateDatabaseDdl(instanceId,
     databaseId,
     Arrays.asList("ALTER TABLE Albums ADD COLUMN MarketingBudget INT64"),
     null).waitFor();
 
Parameters
NameDescription
instanceIdString
databaseIdString
statementsIterable<String>
operationIdString

Operation id assigned to this operation. If null, system will autogenerate one. This must be unique within a database abd must be a valid identifier a-zA-Z*.

Returns
TypeDescription
OperationFuture<Void,UpdateDatabaseDdlMetadata>
Exceptions
TypeDescription
SpannerException