com.google.cloud.spanner

Interface DatabaseAdminClient

public interface DatabaseAdminClient

Client to do admin operations on a Cloud Spanner Database.

Method Summary

Modifier and Type	Method and Description
void	cancelOperation(String name) Cancels the specified long-running operation.
default OperationFuture<Backup,CopyBackupMetadata>	copyBackup(BackupId sourceBackupId, Backup destinationBackup) Creates a copy of backup from an existing backup in Cloud Spanner in the same instance.
default OperationFuture<Backup,CopyBackupMetadata>	copyBackup(String instanceId, String sourceBackupId, String destinationBackupId, com.google.cloud.Timestamp expireTime) Creates a copy of backup from an existing backup in a Cloud Spanner instance.
OperationFuture<Backup,CreateBackupMetadata>	createBackup(Backup backup) Creates a new backup from a database in a Cloud Spanner.
OperationFuture<Backup,CreateBackupMetadata>	createBackup(String sourceInstanceId, String backupId, String databaseId, com.google.cloud.Timestamp expireTime) Creates a new backup from a database in a Cloud Spanner instance.
OperationFuture<Database,CreateDatabaseMetadata>	createDatabase(Database database, Iterable<String> statements) Creates a database in a Cloud Spanner instance.
default OperationFuture<Database,CreateDatabaseMetadata>	createDatabase(String instanceId, String createDatabaseStatement, Dialect dialect, Iterable<String> statements) Creates a new database in a Cloud Spanner instance with the given Dialect.
OperationFuture<Database,CreateDatabaseMetadata>	createDatabase(String instanceId, String databaseId, Iterable<String> statements) Creates a new database in a Cloud Spanner instance.
void	deleteBackup(String instanceId, String backupId) Deletes a pending or completed backup.
void	dropDatabase(String instanceId, String databaseId) Drops a Cloud Spanner database.
Backup	getBackup(String instanceId, String backupId) Gets the current state of a Cloud Spanner database backup.
com.google.cloud.Policy	getBackupIAMPolicy(String instanceId, String backupId) Returns the IAM policy for the given backup.
Database	getDatabase(String instanceId, String databaseId) Gets the current state of a Cloud Spanner database.
List<String>	getDatabaseDdl(String instanceId, String databaseId) Returns the schema of a Cloud Spanner database as a list of formatted DDL statements.
com.google.cloud.Policy	getDatabaseIAMPolicy(String instanceId, String databaseId) Returns the IAM policy for the given database.
Operation	getOperation(String name) Gets the specified long-running operation.
Page<Operation>	listBackupOperations(String instanceId, Options.ListOption... options) Lists long-running backup operations on the specified instance.
Page<Backup>	listBackups(String instanceId, Options.ListOption... options) Returns the list of Cloud Spanner backups in the given instance.
Page<Operation>	listDatabaseOperations(String instanceId, Options.ListOption... options) Lists long-running database operations on the specified instance.
Page<Database>	listDatabases(String instanceId, Options.ListOption... options) Returns the list of Cloud Spanner database in the given instance.
Backup.Builder	newBackupBuilder(BackupId id) Returns a builder for a Backup object with the given id.
Database.Builder	newDatabaseBuilder(DatabaseId id) Returns a builder for a Database object with the given id.
Restore.Builder	newRestoreBuilder(BackupId source, DatabaseId destination) Returns a builder for a Restore object with the given source and destination
OperationFuture<Database,RestoreDatabaseMetadata>	restoreDatabase(Restore restore) Restore a database from a backup.
OperationFuture<Database,RestoreDatabaseMetadata>	restoreDatabase(String backupInstanceId, String backupId, String restoreInstanceId, String restoreDatabaseId) Restore a database from a backup.
com.google.cloud.Policy	setBackupIAMPolicy(String instanceId, String backupId, com.google.cloud.Policy policy) Updates the IAM policy for the given backup and returns the resulting policy.
com.google.cloud.Policy	setDatabaseIAMPolicy(String instanceId, String databaseId, com.google.cloud.Policy policy) Updates the IAM policy for the given database and returns the resulting policy.
Iterable<String>	testBackupIAMPermissions(String instanceId, String backupId, Iterable<String> permissions) Tests for the given permissions on the specified backup for the caller.
Iterable<String>	testDatabaseIAMPermissions(String instanceId, String databaseId, Iterable<String> permissions) Tests for the given permissions on the specified database for the caller.
Backup	updateBackup(String instanceId, String backupId, com.google.cloud.Timestamp expireTime) Updates the expire time of a backup.
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.

Method Detail

createDatabase

OperationFuture<Database,CreateDatabaseMetadata> createDatabase(String instanceId,
                                                                String databaseId,
                                                                Iterable<String> statements)
                                                         throws SpannerException

Creates a new database in a Cloud Spanner instance.

Example to create database.

 String instanceId = my_instance_id;
 String databaseId = my_database_id;
 Operation<Database, CreateDatabaseMetadata> op = dbAdminClient
     .createDatabase(
         instanceId,
         databaseId,
         Arrays.asList(
             "CREATE TABLE Singers (\n"
                 + "  SingerId   INT64 NOT NULL,\n"
                 + "  FirstName  STRING(1024),\n"
                 + "  LastName   STRING(1024),\n"
                 + "  SingerInfo BYTES(MAX)\n"
                 + ") PRIMARY KEY (SingerId)",
             "CREATE TABLE Albums (\n"
                 + "  SingerId     INT64 NOT NULL,\n"
                 + "  AlbumId      INT64 NOT NULL,\n"
                 + "  AlbumTitle   STRING(MAX)\n"
                 + ") PRIMARY KEY (SingerId, AlbumId),\n"
                 + "  INTERLEAVE IN PARENT Singers ON DELETE CASCADE"));
 Database db = op.waitFor().getResult();
 

Parameters:

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

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

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

Throws:

SpannerException

createDatabase

default OperationFuture<Database,CreateDatabaseMetadata> createDatabase(String instanceId,
                                                                        String createDatabaseStatement,
                                                                        Dialect dialect,
                                                                        Iterable<String> statements)
                                                                 throws SpannerException

Creates a new database in a Cloud Spanner instance with the given Dialect.

Example to create database.

 String instanceId = "my_instance_id";
 String createDatabaseStatement = "CREATE DATABASE \"my-database\"";
 Operation<Database, CreateDatabaseMetadata> op = dbAdminClient
     .createDatabase(
         instanceId,
         createDatabaseStatement,
         Dialect.POSTGRESQL
         Collections.emptyList());
 Database db = op.waitFor().getResult();
 

Parameters:

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

createDatabaseStatement - the CREATE DATABASE statement for the database. This statement must use the dialect for the new database.

dialect - the dialect that the new database should use.

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

Throws:

SpannerException

createDatabase

OperationFuture<Database,CreateDatabaseMetadata> createDatabase(Database database,
                                                                Iterable<String> statements)
                                                         throws SpannerException

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<Database, CreateDatabaseMetadata> op = dbAdminClient
     .createDatabase(
         dbInfo,
         Arrays.asList(
             "CREATE TABLE Singers (\n"
                 + "  SingerId   INT64 NOT NULL,\n"
                 + "  FirstName  STRING(1024),\n"
                 + "  LastName   STRING(1024),\n"
                 + "  SingerInfo BYTES(MAX)\n"
                 + ") PRIMARY KEY (SingerId)",
             "CREATE TABLE Albums (\n"
                 + "  SingerId     INT64 NOT NULL,\n"
                 + "  AlbumId      INT64 NOT NULL,\n"
                 + "  AlbumTitle   STRING(MAX)\n"
                 + ") PRIMARY KEY (SingerId, AlbumId),\n"
                 + "  INTERLEAVE IN PARENT Singers ON DELETE CASCADE"));
 Database db = op.waitFor().getResult();
 

Throws:

SpannerException

See Also:

#createDatabase(String, String, Iterable)

newDatabaseBuilder

Database.Builder newDatabaseBuilder(DatabaseId id)

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

newBackupBuilder

Backup.Builder newBackupBuilder(BackupId id)

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

newRestoreBuilder

Restore.Builder newRestoreBuilder(BackupId source,
                                  DatabaseId destination)

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

createBackup

OperationFuture<Backup,CreateBackupMetadata> createBackup(String sourceInstanceId,
                                                          String backupId,
                                                          String databaseId,
                                                          com.google.cloud.Timestamp expireTime)
                                                   throws SpannerException

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<Backup, CreateBackupMetadata> op = dbAdminClient
     .createBackup(
         instanceId,
         backupId,
         databaseId,
         expireTime);
 Backup backup = op.get();
 

Parameters:

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

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

databaseId - the id of the database to backup.

expireTime - the time that the backup will automatically expire.

Throws:

SpannerException

createBackup

OperationFuture<Backup,CreateBackupMetadata> createBackup(Backup backup)
                                                   throws SpannerException

Creates a new backup from a database in a Cloud Spanner. Any configuration options in the Backup instance will be included in the 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<Backup, CreateBackupMetadata> op = dbAdminClient.createBackup(backupToCreate);
 Backup createdBackup = op.get();
 

Parameters:

backup - the backup to be created

Throws:

SpannerException

copyBackup

default OperationFuture<Backup,CopyBackupMetadata> copyBackup(String instanceId,
                                                              String sourceBackupId,
                                                              String destinationBackupId,
                                                              com.google.cloud.Timestamp expireTime)

Creates a copy of backup from an existing backup in a Cloud Spanner instance.

Example to copy a backup.

 String instanceId                  ="my_instance_id";
 String sourceBackupId              ="source_backup_id";
 String destinationBackupId         ="destination_backup_id";
 Timestamp expireTime               =Timestamp.ofTimeMicroseconds(micros);
 OperationFuture<Backup, CopyBackupMetadata> op = dbAdminClient
     .copyBackup(
         instanceId,
         sourceBackupId,
         destinationBackupId,
         expireTime);
 Backup backup = op.get();
 

Parameters:

instanceId - the id of the instance where the source backup is located and where the new backup will be created.

sourceBackupId - the source backup id.

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

expireTime - the time that the new backup will automatically expire.

copyBackup

default OperationFuture<Backup,CopyBackupMetadata> copyBackup(BackupId sourceBackupId,
                                                              Backup destinationBackup)

Creates a copy of backup from an existing backup in Cloud Spanner in the same instance. Any configuration options in the Backup instance will be included in the CopyBackupRequest.

The expire time of the new backup must be set and be at least 6 hours and at most 366 days after the creation time of the existing backup that is being copied.

Example to create a copy of a backup.

 BackupId sourceBackupId = BackupId.of("source-project", "source-instance", "source-backup-id");
 BackupId destinationBackupId = BackupId.of("destination-project", "destination-instance", "new-backup-id");
 Timestamp expireTime = Timestamp.ofTimeMicroseconds(expireTimeMicros);
 EncryptionConfig encryptionConfig =
         EncryptionConfig.ofKey(
             "projects/my-project/locations/some-location/keyRings/my-keyring/cryptoKeys/my-key"));

 Backup destinationBackup = dbAdminClient
     .newBackupBuilder(destinationBackupId)
     .setExpireTime(expireTime)
     .setEncryptionConfig(encryptionConfig)
     .build();

 OperationFuture<Backup, CopyBackupMetadata> op = dbAdminClient.copyBackup(sourceBackupId, destinationBackup);
 Backup copiedBackup = op.get();
 

Parameters:

sourceBackupId - the backup to be copied

destinationBackup - the new backup to create

restoreDatabase

OperationFuture<Database,RestoreDatabaseMetadata> restoreDatabase(String backupInstanceId,
                                                                  String backupId,
                                                                  String restoreInstanceId,
                                                                  String restoreDatabaseId)
                                                           throws SpannerException

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<Database, RestoreDatabaseMetadata> op = dbAdminClient
     .restoreDatabase(
         backupInstanceId,
         backupId,
         restoreInstanceId,
         restoreDatabaseId);
 Database database = op.get();
 

Parameters:

backupInstanceId - the id of the instance where the backup is located.

backupId - the id of the backup to restore.

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

restoreDatabaseId - the id of the database to restore to.

Throws:

SpannerException

restoreDatabase

OperationFuture<Database,RestoreDatabaseMetadata> restoreDatabase(Restore restore)
                                                           throws SpannerException

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<Database, RestoreDatabaseMetadata> op = dbAdminClient
     .restoreDatabase(restore);

 Database database = op.get();
 

Parameters:

restore - a Restore instance with the backup source and destination database

Throws:

SpannerException

listDatabaseOperations

Page<Operation> listDatabaseOperations(String instanceId,
                                       Options.ListOption... options)

Lists long-running database operations on the specified instance.

listBackupOperations

Page<Operation> listBackupOperations(String instanceId,
                                     Options.ListOption... options)

Lists long-running backup operations on the specified instance.

getDatabase

Database getDatabase(String instanceId,
                     String databaseId)
              throws SpannerException

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);
 

Throws:

SpannerException

getBackup

Backup getBackup(String instanceId,
                 String backupId)
          throws SpannerException

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);
 

Throws:

SpannerException

updateDatabaseDdl

OperationFuture<Void,UpdateDatabaseDdlMetadata> updateDatabaseDdl(String instanceId,
                                                                  String databaseId,
                                                                  Iterable<String> statements,
                                                                  @Nullable
                                                                  String operationId)
                                                           throws SpannerException

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 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:

operationId - 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][a-zA-Z0-9_]*.

Throws:

SpannerException

dropDatabase

void dropDatabase(String instanceId,
                  String databaseId)
           throws SpannerException

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);
 

Throws:

SpannerException

getDatabaseDdl

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);
 

listDatabases

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();
 }
 

listBackups

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();
 }
 

updateBackup

Backup updateBackup(String instanceId,
                    String backupId,
                    com.google.cloud.Timestamp expireTime)

Updates the expire time of a backup.

Parameters:

instanceId - Required. The instance of the backup to update.

backupId - Required. The backup id of the backup to update.

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

Returns:

the updated Backup object.

deleteBackup

void deleteBackup(String instanceId,
                  String backupId)

Deletes a pending or completed backup.

Parameters:

instanceId - Required. The instance where the backup exists.

backupId - Required. The id of the backup to delete.

cancelOperation

void cancelOperation(String name)

Cancels the specified long-running operation.

getOperation

Operation getOperation(String name)

Gets the specified long-running operation.

getDatabaseIAMPolicy

com.google.cloud.Policy getDatabaseIAMPolicy(String instanceId,
                                             String databaseId)

Returns the IAM policy for the given database.

setDatabaseIAMPolicy

com.google.cloud.Policy setDatabaseIAMPolicy(String instanceId,
                                             String databaseId,
                                             com.google.cloud.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.

testDatabaseIAMPermissions

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

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

Parameters:

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

databaseId - the id of the database to test.

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

Returns:

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

getBackupIAMPolicy

com.google.cloud.Policy getBackupIAMPolicy(String instanceId,
                                           String backupId)

Returns the IAM policy for the given backup.

setBackupIAMPolicy

com.google.cloud.Policy setBackupIAMPolicy(String instanceId,
                                           String backupId,
                                           com.google.cloud.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.

testBackupIAMPermissions

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

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

Parameters:

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

backupId - the id of the backup to test.

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

Returns:

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