Method: projects.instances.databases.updateDdl

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

HTTP request


PATCH https://spanner.googleapis.com/v1/{database=projects/*/instances/*/databases/*}/ddl

The URLs usegRPC Transcoding syntax.

Path parameters

Parameters
database

string

Required. The database to update.

Authorization requires the followingIAM permission on the specified resourcedatabase:

  • spanner.databases.updateDdl

Request body

The request body contains data with the following structure:

JSON representation
{"statements":[string],"operationId":string,"protoDescriptors":string}
Fields
statements[]

string

Required. DDL statements to be applied to the database.

operationId

string

If empty, the new update request is assigned an automatically-generated operation ID. Otherwise,operationId is used to construct the name of the resulting Operation.

Specifying an explicit operation ID simplifies determining whether the statements were executed in the event that thedatabases.updateDdl call is replayed, or the return value is otherwise lost: thedatabase andoperationId fields can be combined to form thename of the resulting longrunning.Operation:<database>/operations/<operationId>.

operationId should be unique within the database, and must be a valid identifier:[a-z][a-z0-9_]*. Note that automatically-generated operation IDs always begin with an underscore. If the named operation already exists,databases.updateDdl returnsALREADY_EXISTS.

protoDescriptors

string (bytes format)

Optional. Proto descriptors used by CREATE/ALTER PROTO BUNDLE statements. Contains a protobuf-serializedgoogle.protobuf.FileDescriptorSet. To generate it,install and runprotoc with --include_imports and --descriptor_set_out. For example, to generate for moon/shot/app.proto, run

$protoc  --proto_path=/app_path --proto_path=/lib_path \         --include_imports \         --descriptor_set_out=descriptors.data \         moon/shot/app.proto

For more details, see protobufferself description.

A base64-encoded string.

Response body

If successful, the response body contains an instance ofOperation.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/spanner.admin
  • https://www.googleapis.com/auth/cloud-platform

For more information, see theAuthentication Overview.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-12 UTC.