Criar e gerenciar bancos de dados

Nesta página, descrevemos como criar e gerenciar bancos de dados do Spanner:

• Vários métodos para criar um banco de dados
• Modificar opções de banco de dados
• Excluir um banco de dados

Esta página contém informações sobre bancos de dados de dialeto do GoogleSQL e do PostgreSQL. Para saber como atualizar um esquema de banco de dados, consulte Fazer atualizações de esquema. Para mais informações sobre como criar uma instância, consulte Criar e gerenciar instâncias. É possível criar um banco de dados em uma instância atual de uma das seguintes maneiras:

• Criar um banco de dados: é possível criar um novo banco de dados selecionando o dialeto SQL e definindo o esquema.
• Importar seus próprios dados: é possível importar um arquivo CSV, arquivo dump do MySQL ou arquivo dump do PostgreSQL para um banco de dados novo ou atual.
• Importar um banco de dados do Cloud SQL: é possível importar um banco de dados do Cloud SQL para MySQL para o Spanner.
• Criar um banco de dados com dados de amostra: é possível preencher um banco de dados usando um dos conjuntos de dados de amostra disponíveis para testar os recursos do Spanner.

Criar um banco de dados

É possível criar um novo banco de dados em uma instância atual. Para bancos de dados de dialeto do GoogleSQL, é possível definir o esquema do banco de dados no momento da criação ou depois que ele for criado. Para bancos de dados de dialeto PostgreSQL, é preciso definir o esquema após a criação.

Os esquemas são definidos usando a linguagem de definição de banco de dados, que está documentada para GoogleSQL e PostgreSQL. Consulte os links a seguir para mais informações sobre como criar e atualizar esquemas:

• Modelo de dados e esquema
• Práticas recomendadas de criação de esquema
• Atualizações de esquema

Depois de criar o banco de dados, é possível proteger os bancos de dados importantes para seus aplicativos e serviços ativando a proteção contra exclusão de bancos de dados. Para mais informações, consulte Evitar a exclusão acidental do banco de dados.

Console do Google Cloud

1. No console do Google Cloud , acesse a página Instâncias do Spanner.

   Acessar as instâncias do Spanner

2. Selecione a instância em que o banco de dados será criado.

3. Clique em Criar banco de dados.

4. Digite os seguintes valores:

   • Um nome de banco de dados para exibir no console do Google Cloud .
   • O dialeto a ser usado para esse banco de dados.
   • Para bancos de dados de dialeto do GoogleSQL, forneça um conjunto de instruções DDL que definem seu esquema. Use os modelos de DDL para preencher automaticamente elementos comuns. Se houver erros nas instruções DDL, o console do Google Cloud vai retornar um erro quando você tentar criar o banco de dados.
   • Se quiser, selecione uma chave de criptografia gerenciada pelo cliente para usar neste banco de dados.

5. Clique em Criar para criar o banco de dados.

gcloud

Use o comando gcloud spanner databases create.

```sh
gcloud spanner databases create DATABASE \
  --instance=INSTANCE \
  [--async] \
  [--database-dialect=DATABASE_DIALECT] \
  [--ddl=DDL] \
  [--ddl-file=DDL_FILE] \
  [--kms-key=KMS_KEY : --kms-keyring=KMS_KEYRING --kms-location=KMS_LOCATION --kms-project=KMS_PROJECT] \
  [GCLOUD_WIDE_FLAG …]
```

As seguintes opções são obrigatórias:

DATABASE

ID do banco de dados ou identificador totalmente qualificado do banco de dados. Se você especificar o identificador totalmente qualificado, a flag --instance poderá ser omitida.

--instance=INSTANCE

A instância do Spanner para o banco de dados.

As seguintes opções são opcionais:

--async

Retorna imediatamente, sem aguardar a conclusão da operação em andamento.

--database-dialect=DATABASE_DIALECT

O dialeto SQL do banco de dados do Spanner. Precisa ser um destes: POSTGRESQL, GOOGLE_STANDARD_SQL.

--ddl=DDL

Instruções DDL (linguagem de definição de dados) separadas por ponto e vírgula para serem executadas no banco de dados recém-criado. Se houver um erro em qualquer instrução, o banco de dados não será criado. Essa flag será ignorada se --ddl_file estiver definido. Não é compatível com bancos de dados de dialeto PostgreSQL.

--ddl-file=DDL_FILE

Caminho de um arquivo que contém instruções DDL (linguagem de definição de dados) separadas por ponto e vírgula para serem executadas no banco de dados recém-criado. Se houver um erro em qualquer instrução, o banco de dados não será criado. Se --ddl_file estiver definido, --ddl será ignorado. Não é compatível com bancos de dados de dialeto PostgreSQL.

Se você estiver especificando uma chave do Cloud Key Management Service para usar ao criar o banco de dados, inclua as seguintes opções:

--kms-key=KMS_KEY

ID da chave ou identificador totalmente qualificado da chave.

Essa sinalização precisa ser especificada se algum dos outros argumentos neste grupo for especificado. Os outros argumentos podem ser omitidos se o identificador totalmente qualificado for fornecido.

--kms-keyring=KMS_KEYRING

ID do keyring do Cloud KMS da chave.

--kms-location=KMS_LOCATION

Google Cloud local da chave.

--kms-project=KMS_PROJECT

Google Cloud ID do projeto da chave.

Cliente (GoogleSQL)

C++

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

void CreateDatabase(google::cloud::spanner_admin::DatabaseAdminClient client,
                    std::string const& project_id,
                    std::string const& instance_id,
                    std::string const& database_id) {
  google::cloud::spanner::Database database(project_id, instance_id,
                                            database_id);
  google::spanner::admin::database::v1::CreateDatabaseRequest request;
  request.set_parent(database.instance().FullName());
  request.set_create_statement("CREATE DATABASE `" + database.database_id() +
                               "`");
  request.add_extra_statements(R"""(
      CREATE TABLE Singers (
          SingerId   INT64 NOT NULL,
          FirstName  STRING(1024),
          LastName   STRING(1024),
          SingerInfo BYTES(MAX),
          FullName   STRING(2049)
              AS (ARRAY_TO_STRING([FirstName, LastName], " ")) STORED
      ) PRIMARY KEY (SingerId))""");
  request.add_extra_statements(R"""(
      CREATE TABLE Albums (
          SingerId     INT64 NOT NULL,
          AlbumId      INT64 NOT NULL,
          AlbumTitle   STRING(MAX)
      ) PRIMARY KEY (SingerId, AlbumId),
          INTERLEAVE IN PARENT Singers ON DELETE CASCADE)""");
  auto db = client.CreateDatabase(request).get();
  if (!db) throw std::move(db).status();
  std::cout << "Database " << db->name() << " created.\n";
}

Go

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import (
	"context"
	"fmt"
	"io"
	"regexp"

	database "cloud.google.com/go/spanner/admin/database/apiv1"
	adminpb "cloud.google.com/go/spanner/admin/database/apiv1/databasepb"
)

func createDatabase(ctx context.Context, w io.Writer, db string) error {
	matches := regexp.MustCompile("^(.*)/databases/(.*)$").FindStringSubmatch(db)
	if matches == nil || len(matches) != 3 {
		return fmt.Errorf("Invalid database id %s", db)
	}

	adminClient, err := database.NewDatabaseAdminClient(ctx)
	if err != nil {
		return err
	}
	defer adminClient.Close()

	op, err := adminClient.CreateDatabase(ctx, &adminpb.CreateDatabaseRequest{
		Parent:          matches[1],
		CreateStatement: "CREATE DATABASE `" + matches[2] + "`",
		ExtraStatements: []string{
			`CREATE TABLE Singers (
				SingerId   INT64 NOT NULL,
				FirstName  STRING(1024),
				LastName   STRING(1024),
				SingerInfo BYTES(MAX),
				FullName   STRING(2048) AS (
					ARRAY_TO_STRING([FirstName, LastName], " ")
				) STORED
			) PRIMARY KEY (SingerId)`,
			`CREATE TABLE Albums (
				SingerId     INT64 NOT NULL,
				AlbumId      INT64 NOT NULL,
				AlbumTitle   STRING(MAX)
			) PRIMARY KEY (SingerId, AlbumId),
			INTERLEAVE IN PARENT Singers ON DELETE CASCADE`,
		},
	})
	if err != nil {
		return err
	}
	if _, err := op.Wait(ctx); err != nil {
		return err
	}
	fmt.Fprintf(w, "Created database [%s]\n", db)
	return nil
}

Java

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.spanner.SpannerException;
import com.google.cloud.spanner.SpannerExceptionFactory;
import com.google.cloud.spanner.admin.database.v1.DatabaseAdminClient;
import com.google.common.collect.ImmutableList;
import com.google.spanner.admin.database.v1.CreateDatabaseRequest;
import com.google.spanner.admin.database.v1.Database;
import java.io.IOException;
import java.util.concurrent.ExecutionException;

public class CreateDatabaseWithDefaultLeaderSample {

  static void createDatabaseWithDefaultLeader() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String instanceName = "projects/my-project/instances/my-instance-id";
    final String databaseId = "my-database-name";
    final String defaultLeader = "my-default-leader";
    createDatabaseWithDefaultLeader(instanceName, databaseId, defaultLeader);
  }

  static void createDatabaseWithDefaultLeader(String instanceName, String databaseId,
      String defaultLeader) throws IOException {
    try (DatabaseAdminClient databaseAdminClient = DatabaseAdminClient.create()) {
      Database createdDatabase =
          databaseAdminClient.createDatabaseAsync(
              CreateDatabaseRequest.newBuilder()
                  .setParent(instanceName)
                  .setCreateStatement("CREATE DATABASE `" + databaseId + "`")
                  .addAllExtraStatements(
                      ImmutableList.of("CREATE TABLE Singers ("
                              + "  SingerId   INT64 NOT NULL,"
                              + "  FirstName  STRING(1024),"
                              + "  LastName   STRING(1024),"
                              + "  SingerInfo BYTES(MAX)"
                              + ") PRIMARY KEY (SingerId)",
                          "CREATE TABLE Albums ("
                              + "  SingerId     INT64 NOT NULL,"
                              + "  AlbumId      INT64 NOT NULL,"
                              + "  AlbumTitle   STRING(MAX)"
                              + ") PRIMARY KEY (SingerId, AlbumId),"
                              + "  INTERLEAVE IN PARENT Singers ON DELETE CASCADE",
                          "ALTER DATABASE " + "`" + databaseId + "`"
                              + " SET OPTIONS ( default_leader = '" + defaultLeader + "' )"))
                  .build()).get();
      System.out.println("Created database [" + createdDatabase.getName() + "]");
      System.out.println("\tDefault leader: " + createdDatabase.getDefaultLeader());
    } catch (ExecutionException e) {
      // If the operation failed during execution, expose the cause.
      throw (SpannerException) e.getCause();
    } catch (InterruptedException e) {
      // Throw when a thread is waiting, sleeping, or otherwise occupied,
      // and the thread is interrupted, either before or during the activity.
      throw SpannerExceptionFactory.propagateInterrupt(e);
    }
  }
}

Observação: os exemplos antigos de código da interface da biblioteca de cliente para Java estão arquivados no GitHub.

Node.js

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance-id';
// const databaseId = 'my-database-id';
// const defaultLeader = 'my-default-leader'; example: 'asia-northeast1'

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

// creates a client
const spanner = new Spanner({
  projectId: projectId,
});

// Gets a reference to a Cloud Spanner Database Admin Client object
const databaseAdminClient = spanner.getDatabaseAdminClient();

async function createDatabaseWithDefaultLeader() {
  // Create a new database with an extra statement which will alter the
  // database after creation to set the default leader.
  console.log(
    `Creating database ${databaseAdminClient.databasePath(
      projectId,
      instanceId,
      databaseId,
    )}.`,
  );
  const createSingersTableStatement = `
    CREATE TABLE Singers (
      SingerId   INT64 NOT NULL,
      FirstName  STRING(1024),
      LastName   STRING(1024),
      SingerInfo BYTES(MAX)
    ) PRIMARY KEY (SingerId)`;
  const createAlbumsStatement = `
    CREATE TABLE Albums (
      SingerId     INT64 NOT NULL,
      AlbumId      INT64 NOT NULL,
      AlbumTitle   STRING(MAX)
    ) PRIMARY KEY (SingerId, AlbumId),
      INTERLEAVE IN PARENT Singers ON DELETE CASCADE`;

  // Default leader is one of the possible values in the leaderOptions field of the
  // instance config of the instance where the database is created.
  const setDefaultLeaderStatement = `
    ALTER DATABASE \`${databaseId}\`
    SET OPTIONS (default_leader = '${defaultLeader}')`;

  const [operation] = await databaseAdminClient.createDatabase({
    createStatement: 'CREATE DATABASE `' + databaseId + '`',
    extraStatements: [
      createSingersTableStatement,
      createAlbumsStatement,
      setDefaultLeaderStatement,
    ],
    parent: databaseAdminClient.instancePath(projectId, instanceId),
  });

  console.log(`Waiting for creation of ${databaseId} to complete...`);
  await operation.promise();
  console.log(
    `Created database ${databaseId} with default leader ${defaultLeader}.`,
  );
}
createDatabaseWithDefaultLeader();

Observação: os exemplos antigos de código da interface da biblioteca de cliente para Node.js estão arquivados no GitHub.

PHP

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

use Google\Cloud\Spanner\Admin\Database\V1\Client\DatabaseAdminClient;
use Google\Cloud\Spanner\Admin\Database\V1\CreateDatabaseRequest;

/**
 * Creates a database and tables for sample data.
 * Example:
 * ```
 * create_database($instanceId, $databaseId);
 * ```
 *
 * @param string $projectId The Google Cloud project ID.
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function create_database(string $projectId, string $instanceId, string $databaseId): void
{
    $databaseAdminClient = new DatabaseAdminClient();
    $instance = $databaseAdminClient->instanceName($projectId, $instanceId);

    $operation = $databaseAdminClient->createDatabase(
        new CreateDatabaseRequest([
            'parent' => $instance,
            'create_statement' => sprintf('CREATE DATABASE `%s`', $databaseId),
            'extra_statements' => [
                'CREATE TABLE Singers (' .
                'SingerId     INT64 NOT NULL,' .
                'FirstName    STRING(1024),' .
                'LastName     STRING(1024),' .
                'SingerInfo   BYTES(MAX),' .
                'FullName     STRING(2048) AS' .
                '(ARRAY_TO_STRING([FirstName, LastName], " ")) STORED' .
                ') PRIMARY KEY (SingerId)',
                'CREATE TABLE Albums (' .
                    'SingerId     INT64 NOT NULL,' .
                    'AlbumId      INT64 NOT NULL,' .
                    'AlbumTitle   STRING(MAX)' .
                ') PRIMARY KEY (SingerId, AlbumId),' .
                'INTERLEAVE IN PARENT Singers ON DELETE CASCADE'
            ]
        ])
    );

    print('Waiting for operation to complete...' . PHP_EOL);
    $operation->pollUntilComplete();

    printf('Created database %s on instance %s' . PHP_EOL,
        $databaseId, $instanceId);
}

Observação: os exemplos antigos de código da interface da biblioteca de cliente para PHP estão arquivados no GitHub.

Python

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

def create_database(instance_id, database_id):
    """Creates a database and tables for sample data."""
    from google.cloud.spanner_admin_database_v1.types import spanner_database_admin

    spanner_client = spanner.Client()
    database_admin_api = spanner_client.database_admin_api

    request = spanner_database_admin.CreateDatabaseRequest(
        parent=database_admin_api.instance_path(spanner_client.project, instance_id),
        create_statement=f"CREATE DATABASE `{database_id}`",
        extra_statements=[
            """CREATE TABLE Singers (
            SingerId     INT64 NOT NULL,
            FirstName    STRING(1024),
            LastName     STRING(1024),
            SingerInfo   BYTES(MAX),
            FullName   STRING(2048) AS (
                ARRAY_TO_STRING([FirstName, LastName], " ")
            ) STORED
        ) PRIMARY KEY (SingerId)""",
            """CREATE TABLE Albums (
            SingerId     INT64 NOT NULL,
            AlbumId      INT64 NOT NULL,
            AlbumTitle   STRING(MAX)
        ) PRIMARY KEY (SingerId, AlbumId),
        INTERLEAVE IN PARENT Singers ON DELETE CASCADE""",
        ],
    )

    operation = database_admin_api.create_database(request=request)

    print("Waiting for operation to complete...")
    database = operation.result(OPERATION_TIMEOUT_SECONDS)

    print(
        "Created database {} on instance {}".format(
            database.name,
            database_admin_api.instance_path(spanner_client.project, instance_id),
        )
    )

Observação: os exemplos antigos de código da interface da biblioteca de cliente para Python estão arquivados no GitHub.

Ruby

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"
require "google/cloud/spanner/admin/database"

database_admin_client = Google::Cloud::Spanner::Admin::Database.database_admin

instance_path = database_admin_client.instance_path project: project_id, instance: instance_id

job = database_admin_client.create_database parent: instance_path,
                                            create_statement: "CREATE DATABASE `#{database_id}`",
                                            extra_statements: [
                                              "CREATE TABLE Singers (
      SingerId     INT64 NOT NULL,
      FirstName    STRING(1024),
      LastName     STRING(1024),
      SingerInfo   BYTES(MAX)
    ) PRIMARY KEY (SingerId)",

                                              "CREATE TABLE Albums (
      SingerId     INT64 NOT NULL,
      AlbumId      INT64 NOT NULL,
      AlbumTitle   STRING(MAX)
    ) PRIMARY KEY (SingerId, AlbumId),
    INTERLEAVE IN PARENT Singers ON DELETE CASCADE"
                                            ]

puts "Waiting for create database operation to complete"

job.wait_until_done!

puts "Created database #{database_id} on instance #{instance_id}"

Cliente (PostgreSQL)

C++

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

void CreateDatabase(google::cloud::spanner_admin::DatabaseAdminClient client,
                    google::cloud::spanner::Database const& database) {
  google::spanner::admin::database::v1::CreateDatabaseRequest request;
  request.set_parent(database.instance().FullName());
  request.set_create_statement("CREATE DATABASE \"" + database.database_id() +
                               "\"");
  request.set_database_dialect(
      google::spanner::admin::database::v1::DatabaseDialect::POSTGRESQL);
  auto db = client.CreateDatabase(request).get();
  if (!db) throw std::move(db).status();
  std::cout << "Database " << db->name() << " created.\n";
}

Go

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import (
	"context"
	"fmt"
	"io"
	"regexp"

	database "cloud.google.com/go/spanner/admin/database/apiv1"
	adminpb "cloud.google.com/go/spanner/admin/database/apiv1/databasepb"
)

// pgCreateDatabase shows how to create a Spanner database that uses the
// PostgreSQL dialect.
func pgCreateDatabase(ctx context.Context, w io.Writer, db string) error {
	// db := "projects/my-project/instances/my-instance/databases/my-database"
	matches := regexp.MustCompile("^(.*)/databases/(.*)$").FindStringSubmatch(db)
	if matches == nil || len(matches) != 3 {
		return fmt.Errorf("invalid database id %v", db)
	}

	adminClient, err := database.NewDatabaseAdminClient(ctx)
	if err != nil {
		return err
	}
	defer adminClient.Close()

	// Databases with PostgreSQL dialect do not support extra DDL statements in the `CreateDatabase` call.
	req := &adminpb.CreateDatabaseRequest{
		Parent:          matches[1],
		DatabaseDialect: adminpb.DatabaseDialect_POSTGRESQL,
		// Note that PostgreSQL uses double quotes for quoting identifiers. This also
		// includes database names in the CREATE DATABASE statement.
		CreateStatement: `CREATE DATABASE "` + matches[2] + `"`,
	}
	opCreate, err := adminClient.CreateDatabase(ctx, req)
	if err != nil {
		return err
	}
	if _, err := opCreate.Wait(ctx); err != nil {
		return err
	}
	updateReq := &adminpb.UpdateDatabaseDdlRequest{
		Database: db,
		Statements: []string{
			`CREATE TABLE Singers (
				SingerId   bigint NOT NULL PRIMARY KEY,
				FirstName  varchar(1024),
				LastName   varchar(1024),
				SingerInfo bytea
			)`,
			`CREATE TABLE Albums (
				AlbumId      bigint NOT NULL,
				SingerId     bigint NOT NULL REFERENCES Singers (SingerId),
				AlbumTitle   text,
                PRIMARY KEY(SingerId, AlbumId)
			)`,
			`CREATE TABLE Venues (
				VenueId  bigint NOT NULL PRIMARY KEY,
				Name     varchar(1024) NOT NULL
			)`,
		},
	}
	opUpdate, err := adminClient.UpdateDatabaseDdl(ctx, updateReq)
	if err != nil {
		return err
	}
	if err := opUpdate.Wait(ctx); err != nil {
		return err
	}
	fmt.Fprintf(w, "Created Spanner PostgreSQL database [%v]\n", db)
	return nil
}

Java

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

static void createPostgreSqlDatabase(
    DatabaseAdminClient dbAdminClient, String projectId, String instanceId, String databaseId) {
  final CreateDatabaseRequest request =
      CreateDatabaseRequest.newBuilder()
          .setCreateStatement("CREATE DATABASE \"" + databaseId + "\"")
          .setParent(InstanceName.of(projectId, instanceId).toString())
          .setDatabaseDialect(DatabaseDialect.POSTGRESQL).build();

  try {
    // Initiate the request which returns an OperationFuture.
    Database db = dbAdminClient.createDatabaseAsync(request).get();
    System.out.println("Created database [" + db.getName() + "]");
  } catch (ExecutionException e) {
    // If the operation failed during execution, expose the cause.
    throw (SpannerException) e.getCause();
  } catch (InterruptedException e) {
    // Throw when a thread is waiting, sleeping, or otherwise occupied,
    // and the thread is interrupted, either before or during the activity.
    throw SpannerExceptionFactory.propagateInterrupt(e);
  }
}
static void createTableUsingDdl(DatabaseAdminClient dbAdminClient, DatabaseName databaseName) {
  try {
    // Initiate the request which returns an OperationFuture.
    dbAdminClient.updateDatabaseDdlAsync(
        databaseName,
        Arrays.asList(
            "CREATE TABLE Singers ("
                + "  SingerId   bigint NOT NULL,"
                + "  FirstName  character varying(1024),"
                + "  LastName   character varying(1024),"
                + "  SingerInfo bytea,"
                + "  FullName character varying(2048) GENERATED "
                + "  ALWAYS AS (FirstName || ' ' || LastName) STORED,"
                + "  PRIMARY KEY (SingerId)"
                + ")",
            "CREATE TABLE Albums ("
                + "  SingerId     bigint NOT NULL,"
                + "  AlbumId      bigint NOT NULL,"
                + "  AlbumTitle   character varying(1024),"
                + "  PRIMARY KEY (SingerId, AlbumId)"
                + ") INTERLEAVE IN PARENT Singers ON DELETE CASCADE")).get();
    System.out.println("Created Singers & Albums tables in database: [" + databaseName + "]");
  } catch (ExecutionException e) {
    // If the operation failed during execution, expose the cause.
    throw SpannerExceptionFactory.asSpannerException(e);
  } catch (InterruptedException e) {
    // Throw when a thread is waiting, sleeping, or otherwise occupied,
    // and the thread is interrupted, either before or during the activity.
    throw SpannerExceptionFactory.propagateInterrupt(e);
  }
}

Node.js

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const instanceId = 'my-instance';
// const databaseId = 'my-database';
// const projectId = 'my-project-id';

// Imports the Google Cloud client library
const {Spanner, protos} = require('@google-cloud/spanner');

// creates a client
const spanner = new Spanner({
  projectId: projectId,
});

const databaseAdminClient = spanner.getDatabaseAdminClient();

async function createPgDatabase() {
  // Creates a PostgreSQL database. PostgreSQL create requests may not contain any additional
  // DDL statements. We need to execute these separately after the database has been created.
  const [operationCreate] = await databaseAdminClient.createDatabase({
    createStatement: 'CREATE DATABASE "' + databaseId + '"',
    parent: databaseAdminClient.instancePath(projectId, instanceId),
    databaseDialect:
      protos.google.spanner.admin.database.v1.DatabaseDialect.POSTGRESQL,
  });

  console.log(`Waiting for operation on ${databaseId} to complete...`);
  await operationCreate.promise();
  const [metadata] = await databaseAdminClient.getDatabase({
    name: databaseAdminClient.databasePath(projectId, instanceId, databaseId),
  });
  console.log(
    `Created database ${databaseId} on instance ${instanceId} with dialect ${metadata.databaseDialect}.`,
  );

  // Create a couple of tables using a separate request. We must use PostgreSQL style DDL as the
  // database has been created with the PostgreSQL dialect.
  const statements = [
    `CREATE TABLE Singers 
      (SingerId   bigint NOT NULL,
      FirstName   varchar(1024),
      LastName    varchar(1024),
      SingerInfo  bytea,
      FullName    character varying(2048) GENERATED ALWAYS AS (FirstName || ' ' || LastName) STORED,
      PRIMARY KEY (SingerId)
      );
      CREATE TABLE Albums 
      (AlbumId    bigint NOT NULL,
      SingerId    bigint NOT NULL REFERENCES Singers (SingerId),
      AlbumTitle  text,
      PRIMARY KEY (AlbumId)
      );`,
  ];
  const [operationUpdateDDL] = await databaseAdminClient.updateDatabaseDdl({
    database: databaseAdminClient.databasePath(
      projectId,
      instanceId,
      databaseId,
    ),
    statements: [statements],
  });
  await operationUpdateDDL.promise();
  console.log('Updated schema');
}
createPgDatabase();

PHP

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

use Google\Cloud\Spanner\Admin\Database\V1\Client\DatabaseAdminClient;
use Google\Cloud\Spanner\Admin\Database\V1\CreateDatabaseRequest;
use Google\Cloud\Spanner\Admin\Database\V1\DatabaseDialect;
use Google\Cloud\Spanner\Admin\Database\V1\GetDatabaseRequest;
use Google\Cloud\Spanner\Admin\Database\V1\UpdateDatabaseDdlRequest;

/**
 * Creates a database that uses Postgres dialect
 *
 * @param string $projectId The Google Cloud project ID.
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function pg_create_database(string $projectId, string $instanceId, string $databaseId): void
{
    $databaseAdminClient = new DatabaseAdminClient();
    $instance = $databaseAdminClient->instanceName($projectId, $instanceId);
    $databaseName = $databaseAdminClient->databaseName($projectId, $instanceId, $databaseId);

    $table1Query = 'CREATE TABLE Singers (
        SingerId   bigint NOT NULL PRIMARY KEY,
        FirstName  varchar(1024),
        LastName   varchar(1024),
        SingerInfo bytea,
        FullName character varying(2048) GENERATED
        ALWAYS AS (FirstName || \' \' || LastName) STORED
    )';
    $table2Query = 'CREATE TABLE Albums (
        AlbumId      bigint NOT NULL,
        SingerId     bigint NOT NULL REFERENCES Singers (SingerId),
        AlbumTitle   text,
        PRIMARY KEY(SingerId, AlbumId)
    )';

    $operation = $databaseAdminClient->createDatabase(
        new CreateDatabaseRequest([
            'parent' => $instance,
            'create_statement' => sprintf('CREATE DATABASE "%s"', $databaseId),
            'extra_statements' => [],
            'database_dialect' => DatabaseDialect::POSTGRESQL
        ])
    );

    print('Waiting for operation to complete...' . PHP_EOL);
    $operation->pollUntilComplete();

    $request = new UpdateDatabaseDdlRequest([
        'database' => $databaseName,
        'statements' => [$table1Query, $table2Query]
    ]);

    $operation = $databaseAdminClient->updateDatabaseDdl($request);
    $operation->pollUntilComplete();

    $database = $databaseAdminClient->getDatabase(
        new GetDatabaseRequest(['name' => $databaseAdminClient->databaseName($projectId, $instanceId, $databaseId)])
    );
    $dialect = DatabaseDialect::name($database->getDatabaseDialect());

    printf('Created database %s with dialect %s on instance %s' . PHP_EOL,
        $databaseId, $dialect, $instanceId);
}

Python

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

def create_database(instance_id, database_id):
    """Creates a PostgreSql database and tables for sample data."""

    from google.cloud.spanner_admin_database_v1.types import spanner_database_admin

    spanner_client = spanner.Client()
    database_admin_api = spanner_client.database_admin_api

    request = spanner_database_admin.CreateDatabaseRequest(
        parent=database_admin_api.instance_path(spanner_client.project, instance_id),
        create_statement=f'CREATE DATABASE "{database_id}"',
        database_dialect=DatabaseDialect.POSTGRESQL,
    )

    operation = database_admin_api.create_database(request=request)

    print("Waiting for operation to complete...")
    database = operation.result(OPERATION_TIMEOUT_SECONDS)

    create_table_using_ddl(database.name)
    print("Created database {} on instance {}".format(database_id, instance_id))


def create_table_using_ddl(database_name):
    from google.cloud.spanner_admin_database_v1.types import spanner_database_admin

    spanner_client = spanner.Client()
    request = spanner_database_admin.UpdateDatabaseDdlRequest(
        database=database_name,
        statements=[
            """CREATE TABLE Singers (
  SingerId   bigint NOT NULL,
  FirstName  character varying(1024),
  LastName   character varying(1024),
  SingerInfo bytea,
  FullName   character varying(2048)
    GENERATED ALWAYS AS (FirstName || ' ' || LastName) STORED,
  PRIMARY KEY (SingerId)
  )""",
            """CREATE TABLE Albums (
  SingerId     bigint NOT NULL,
  AlbumId      bigint NOT NULL,
  AlbumTitle   character varying(1024),
  PRIMARY KEY (SingerId, AlbumId)
  ) INTERLEAVE IN PARENT Singers ON DELETE CASCADE""",
        ],
    )
    operation = spanner_client.database_admin_api.update_database_ddl(request)
    operation.result(OPERATION_TIMEOUT_SECONDS)

Ruby

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

Para autenticar no Spanner, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

require "google/cloud/spanner"
require "google/cloud/spanner/admin/database"

def postgresql_create_database project_id:, instance_id:, database_id:
  # project_id  = "Your Google Cloud project ID"
  # instance_id = "Your Spanner instance ID"
  # database_id = "Your Spanner database ID"

  database_admin_client = Google::Cloud::Spanner::Admin::Database.database_admin project: project_id

  instance_path = database_admin_client.instance_path project: project_id, instance: instance_id

  job = database_admin_client.create_database parent: instance_path,
                                              create_statement: "CREATE DATABASE \"#{database_id}\"",
                                              database_dialect: :POSTGRESQL

  puts "Waiting for create database operation to complete"

  job.wait_until_done!

  puts "Created database #{database_id} on instance #{instance_id}"
end

Importe seus próprios dados

É possível importar seus próprios dados para um banco de dados do Spanner usando um arquivo CSV, um arquivo dump do MySQL ou um arquivo dump do PostgreSQL. É possível fazer upload de um arquivo local usando o Cloud Storage ou diretamente de um bucket do Cloud Storage. O upload de um arquivo local usando o Cloud Storage pode gerar cobranças.

Se você optar por usar um arquivo CSV, também precisará fazer upload de um arquivo JSON separado que contenha o esquema do banco de dados.

Console do Google Cloud

1. No console do Google Cloud , acesse a página Instâncias do Spanner.

   Acessar as instâncias do Spanner

2. Selecione a instância em que o banco de dados será criado.

3. Clique em Importar meus dados.

4. Digite os seguintes valores:

   • Selecione o Tipo de arquivo.

   • Faça upload do arquivo do seu computador ou selecione um caminho de bucket do Cloud Storage para o arquivo.

   • (Opcional) Se você optar por usar um arquivo CSV, também será necessário fazer upload de um arquivo JSON separado que contenha o esquema do banco de dados. O arquivo JSON precisa usar a seguinte estrutura para definir o esquema:

     {
       "name": "COLUMN_NAME",
       "type": "TYPE",
       "notNull": NOT_NULL_VALUE,
       "primaryKeyOrder": PRIMARY_KEY_ORDER
     }

     Substitua:

     • COLUMN_NAME: o nome da coluna na tabela.

     • TYPE: o tipo de dados da coluna.

     • (Opcional) NOT_NULL_VALUE: se a coluna pode armazenar valores nulos ou não. As entradas válidas são true ou false. O padrão é false.

     • (Opcional): PRIMARY_KEY_ORDER: determina a ordem da chave primária. Defina o valor como 0 para uma coluna de chave não primária. Defina o valor como um número inteiro, por exemplo, 1 para uma coluna de chave primária. As colunas com números menores aparecem antes em uma chave primária composta.

     Por padrão, o arquivo CSV espera uma vírgula para o delimitador de campo e uma nova linha para o delimitador de linha. Para mais informações sobre como usar delimitadores personalizados, consulte a referência gcloud alpha spanner databases import.

   • Selecione um banco de dados novo ou atual como destino.

5. Clique em Importar.

6. O Spanner abre o Cloud Shell e preenche um comando que instala a ferramenta de migração do Spanner e executa o comando gcloud alpha spanner databases import. Pressione a tecla ENTER para importar dados para o banco de dados.x

Importar um banco de dados do Cloud SQL

Se você usa o Cloud SQL para MySQL e quer avaliar o Spanner, pode importar dados da instância do Cloud SQL para MySQL para o Spanner. Esse recurso converte o esquema do MySQL e gera um esquema correspondente do Spanner. Em seguida, ele carrega dados do banco de dados do Cloud SQL para MySQL no Spanner.

Essa funcionalidade realiza apenas um carregamento de dados em massa único. Ele não é compatível com a captura de mudanças de dados em tempo real ou o fallback do Spanner para o banco de dados de origem.

Para mais informações, consulte Importar do Cloud SQL para o Spanner.

Usar um conjunto de dados de amostra

Para conhecer o Spanner Graph, a pesquisa vetorial ou o modelo relacional, crie um novo banco de dados pré-preenchido com um conjunto de dados de amostra. Os conjuntos de dados de amostra disponíveis dependem do dialeto do banco de dados selecionado (GoogleSQL ou PostgreSQL).

1. No console do Google Cloud , acesse a página Instâncias do Spanner.

   Acessar as instâncias do Spanner

2. Selecione a instância em que o banco de dados será criado.

3. Clique em Analisar conjuntos de dados.

4. Selecione um conjunto de dados, dependendo do dialeto do banco de dados:

   GoogleSQL

   • Gráfico de finanças: use esse conjunto de dados para conhecer os recursos de gráfico e banco de dados relacional do Spanner.
   • Internet banking: use esse conjunto de dados para conhecer os recursos de pesquisa de texto completo e pesquisa vetorial do Spanner.
   • Jogos on-line: use esse conjunto de dados para conhecer os recursos de banco de dados relacional do Spanner.
   • Varejo: use esse conjunto de dados para conhecer os recursos de gráfico, pesquisa de texto completo e busca vetorial do Spanner.

   PostgreSQL

   • Internet banking: use esse conjunto de dados para conhecer os recursos de pesquisa de texto completo do Spanner.
   • Jogos on-line: use esse conjunto de dados para conhecer os recursos de banco de dados relacional do Spanner.
   • Varejo: use esse conjunto de dados para conhecer os recursos de pesquisa de texto completo e pesquisa vetorial do Spanner.

5. Clique em Criar banco de dados.

Atualizar o esquema ou as opções do banco de dados

É possível atualizar o esquema e as opções do banco de dados usando instruções DDL.

Por exemplo, para adicionar uma coluna a uma tabela, use a seguinte instrução DDL:

GoogleSQL

ALTER TABLE Songwriters ADD COLUMN Publisher STRING(10);

PostgreSQL

ALTER TABLE Songwriters ADD COLUMN Publisher VARCHAR(10);

Para atualizar a versão do otimizador de consultas, use a seguinte instrução DDL:

GoogleSQL

ALTER DATABASE Music SET OPTIONS(optimizer_version=null);

PostgreSQL

ALTER DATABASE DB-NAME SET spanner.optimizer_version TO DEFAULT;

Para mais informações sobre as opções compatíveis, consulte a referência de DDL ALTER DATABASE para GoogleSQL ou PostgreSQL.

Para informações sobre atualizações de esquema, consulte Fazer atualizações de esquema.

Console do Google Cloud

1. No console do Google Cloud , acesse a página Instâncias do Spanner.

   Acessar as instâncias do Spanner

2. Selecione a instância que contém o banco de dados a ser alterado.

3. Selecione o banco de dados.

4. Clique em Spanner Studio.

5. Clique em Nova guia ou use a guia vazia do editor. Em seguida, insira as instruções DDL a serem aplicadas.

6. Clique em Executar para aplicar as atualizações. Se houver erros na DDL, o console do Google Cloud retornará um erro, e o banco de dados não será alterado.

gcloud

Para alterar um banco de dados com a ferramenta de linha de comando gcloud, use gcloud spanner databases ddl update.

gcloud spanner databases ddl update \
(DATABASE : --instance=INSTANCE) \
[--async] \
[--ddl=DDL] \
[--ddl-file=DDL_FILE] \

Consulte a referência de gcloud para detalhes sobre as opções disponíveis.

Transmita as atualizações do banco de dados para o comando com a flag --ddl ou --ddl-file. Se um arquivo DDL for especificado, a flag --ddl será ignorada.

Consulte a referência de DDL do ALTER DATABASE para GoogleSQL ou PostgreSQL para as instruções DDL a serem incluídas.

DDL

Consulte a referência de DDL do ALTER DATABASE para GoogleSQL ou PostgreSQL para mais detalhes.

Verificar o progresso das operações de atualização de esquema

Para verificar o progresso das operações de atualização de esquema, selecione um dos seguintes métodos:

Console do Google Cloud

1. No menu de navegação do Spanner, selecione a guia Operações. A página Operações mostra uma lista de operações ativas em execução.

2. Encontre a operação de esquema na lista. Se ela ainda estiver em execução, a barra de progresso na coluna Horário de término vai mostrar a porcentagem da operação que foi concluída, conforme mostrado na imagem a seguir:

gcloud

Use gcloud spanner operations describe para verificar o progresso de uma operação.

1. Consiga o ID da operação:

   gcloud spanner operations list --instance=INSTANCE-NAME \
   --database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

   Substitua:

   • INSTANCE-NAME pelo nome da instância do Spanner.
   • DATABASE-NAME pelo nome do banco de dados.

2. Execute gcloud spanner operations describe:

   gcloud spanner operations describe OPERATION_ID\
   --instance=INSTANCE-NAME \
   --database=DATABASE-NAME

   Substitua:

   • OPERATION-ID: o ID da operação que você quer verificar.
   • INSTANCE-NAME: o nome da instância do Spanner.
   • DATABASE-NAME: o nome do banco de dados do Spanner.

   A seção progress na saída mostra a porcentagem da operação que foi concluída. A saída será assim:

   done: true
   metadata:
   ...
     progress:
     - endTime: '2022-03-01T00:28:06.691403Z'
       progressPercent: 100
       startTime: '2022-03-01T00:28:04.221401Z'
     - endTime: '2022-03-01T00:28:17.624588Z'
       startTime: '2022-03-01T00:28:06.691403Z'
       progressPercent: 100
   ...

REST v1

1. Consiga o ID da operação:

   gcloud spanner operations list --instance=INSTANCE-NAME \
   --database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

   Substitua:

   • INSTANCE-NAME pelo nome da instância do Spanner.
   • DATABASE-NAME pelo nome do banco de dados.

2. Verifique o progresso da operação.

   Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

   • PROJECT-ID: o ID do projeto.
   • INSTANCE-ID: o ID da instância
   • DATABASE-ID: o ID do banco de dados.
   • OPERATION-ID: o ID da operação.

   Método HTTP e URL:

   GET https://spanner.googleapis.com/v1/projects/PROJECT-ID/instances/INSTANCE-ID/databases/DATABASE-ID/operations/OPERATION-ID

   Para enviar a solicitação, expanda uma destas opções:

   curl (Linux, macOS ou Cloud Shell)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://spanner.googleapis.com/v1/projects/PROJECT-ID/instances/INSTANCE-ID/databases/DATABASE-ID/operations/OPERATION-ID"

   PowerShell (Windows)

   Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

   Execute o seguinte comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://spanner.googleapis.com/v1/projects/PROJECT-ID/instances/INSTANCE-ID/databases/DATABASE-ID/operations/OPERATION-ID" | Select-Object -Expand Content

   Você receberá uma resposta JSON semelhante a esta:

   {
   ...
       "progress": [
         {
           "progressPercent": 100,
           "startTime": "2023-05-27T00:52:27.366688Z",
           "endTime": "2023-05-27T00:52:30.184845Z"
         },
         {
           "progressPercent": 100,
           "startTime": "2023-05-27T00:52:30.184845Z",
           "endTime": "2023-05-27T00:52:40.750959Z"
         }
       ],
   ...
     "done": true,
     "response": {
       "@type": "type.googleapis.com/google.protobuf.Empty"
     }
   }
   
   

Se a operação demorar muito, você poderá cancelá-la. Para mais informações, consulte Cancelar uma operação de banco de dados de longa duração.

O Spanner também detecta automaticamente oportunidades para aplicar as práticas recomendadas de design de esquema. Se houver recomendações disponíveis para um banco de dados, elas vão aparecer na página do Spanner Studio desse banco de dados. Para mais informações, consulte Ver recomendações de práticas recomendadas de design de esquema.

Excluir um banco de dados

A exclusão de um banco de dados remove permanentemente o banco de dados e todos os respectivos dados. A exclusão do banco de dados não pode ser desfeita. Se a proteção contra exclusão de banco de dados estiver ativada em um banco de dados, não será possível excluí-lo até que você desative a proteção contra exclusão.

Os backups atuais não são excluídos quando um banco de dados é excluído. Para mais informações, consulte Backup e restauração.

Console do Google Cloud

1. No console do Google Cloud , acesse a página Instâncias do Spanner.

   Acessar as instâncias do Spanner

2. Selecione a instância que contém o banco de dados a ser excluído.

3. Selecione o banco de dados.

4. Clique em Excluir banco de dados. Uma confirmação vai aparecer.

5. Digite o nome do banco de dados e clique em Excluir.

gcloud

Para excluir um banco de dados com a ferramenta de linha de comando gcloud, use gcloud spanner databases delete.

gcloud spanner databases delete \
  (DATABASE : --instance=INSTANCE)

As seguintes opções são obrigatórias:

DATABASE

ID do banco de dados ou identificador totalmente qualificado do banco de dados. Se o identificador totalmente qualificado for fornecido, a flag --instance precisará ser omitida.

--instance=INSTANCE

A instância do Spanner para o banco de dados.

Para mais detalhes, consulte a referência de gcloud.

DDL

A DDL não é compatível com a sintaxe de exclusão de banco de dados.

A seguir

• Criar um banco de dados e carregá-lo com dados de amostra.
• Saiba mais sobre a referência de DDL do GoogleSQL.
• Saiba mais sobre a referência de DDL do PostgreSQL.
• Saiba como fazer backup e restaurar um banco de dados.
• Saiba como evitar a exclusão acidental de bancos de dados.
• Saiba como fazer atualizações de esquema.