feat: add support for Proto columns

README.md

@@ -167,6 +167,10 @@ Samples are in the [`samples/`](https://github.com/googleapis/nodejs-spanner/tre
 | Alters a sequence in a PostgreSQL database. | [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/pg-sequence-alter.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/pg-sequence-alter.js,samples/README.md) |
 | Creates sequence in PostgreSQL database. | [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/pg-sequence-create.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/pg-sequence-create.js,samples/README.md) |
 | Drops a sequence in PostgreSQL database. | [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/pg-sequence-drop.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/pg-sequence-drop.js,samples/README.md) |
+| Proto-query-data | [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/proto-query-data.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/proto-query-data.js,samples/README.md) |
+| Creates a new database with a proto column and enum | [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/proto-type-add-column.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/proto-type-add-column.js,samples/README.md) |
+| Proto-update-data-dml | [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/proto-update-data-dml.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/proto-update-data-dml.js,samples/README.md) |
+| Proto-update-data | [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/proto-update-data.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/proto-update-data.js,samples/README.md) |
 | Queryoptions | [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/queryoptions.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/queryoptions.js,samples/README.md) |
 | Quickstart | [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/quickstart.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/quickstart.js,samples/README.md) |
 | Read data with database role | [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/read-data-with-database-role.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/read-data-with-database-role.js,samples/README.md) |

package.json

@@ -38,7 +38,7 @@
     "ycsb": "node ./benchmark/ycsb.js  run -P ./benchmark/workloada -p table=usertable -p cloudspanner.instance=ycsb-instance -p operationcount=100 -p cloudspanner.database=ycsb",
     "fix": "gts fix",
     "clean": "gts clean",
-    "compile": "tsc -p . && cp -r protos build",
+    "compile": "tsc -p . && cp -r protos build && cp -r test/data build/test",
     "prepare": "npm run compile-protos && npm run compile",
     "pretest": "npm run compile",
     "presystem-test": "npm run compile",

samples/README.md

@@ -92,6 +92,10 @@ and automatic, synchronous replication for high availability.
   * [Alters a sequence in a PostgreSQL database.](#alters-a-sequence-in-a-postgresql-database.)
   * [Creates sequence in PostgreSQL database.](#creates-sequence-in-postgresql-database.)
   * [Drops a sequence in PostgreSQL database.](#drops-a-sequence-in-postgresql-database.)
+  * [Proto-query-data](#proto-query-data)
+  * [Creates a new database with a proto column and enum](#creates-a-new-database-with-a-proto-column-and-enum)
+  * [Proto-update-data-dml](#proto-update-data-dml)
+  * [Proto-update-data](#proto-update-data)
   * [Queryoptions](#queryoptions)
   * [Quickstart](#quickstart)
   * [Read data with database role](#read-data-with-database-role)
@@ -1455,6 +1459,74 @@ __Usage:__
 
 
 
+### Proto-query-data
+
+View the [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/proto-query-data.js).
+
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/proto-query-data.js,samples/README.md)
+
+__Usage:__
+
+
+`node samples/proto-query-data.js`
+
+
+-----
+
+
+
+
+### Creates a new database with a proto column and enum
+
+View the [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/proto-type-add-column.js).
+
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/proto-type-add-column.js,samples/README.md)
+
+__Usage:__
+
+
+`node proto-type-add-column.js <INSTANCE_ID> <DATABASE_ID> <PROJECT_ID>`
+
+
+-----
+
+
+
+
+### Proto-update-data-dml
+
+View the [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/proto-update-data-dml.js).
+
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/proto-update-data-dml.js,samples/README.md)
+
+__Usage:__
+
+
+`node samples/proto-update-data-dml.js`
+
+
+-----
+
+
+
+
+### Proto-update-data
+
+View the [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/proto-update-data.js).
+
+[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-spanner&page=editor&open_in_editor=samples/proto-update-data.js,samples/README.md)
+
+__Usage:__
+
+
+`node samples/proto-update-data.js`
+
+
+-----
+
+
+
+
 ### Queryoptions
 
 View the [source code](https://github.com/googleapis/nodejs-spanner/blob/main/samples/queryoptions.js).

samples/database-get-ddl.js

@@ -40,7 +40,7 @@ function main(instanceId, databaseId, projectId) {
 
   async function getDatabaseDdl() {
     // Get the schema definition of the database.
-    const [ddlStatements] = await databaseAdminClient.getDatabaseDdl({
+    const [getDatabaseDdlResponse] = await databaseAdminClient.getDatabaseDdl({
       database: databaseAdminClient.databasePath(
         projectId,
         instanceId,
@@ -55,7 +55,10 @@ function main(instanceId, databaseId, projectId) {
         databaseId
       )}:`
     );
-    ddlStatements.statements.forEach(element => {
+    console.log(
+      `Proto Descriptors: ${getDatabaseDdlResponse.protoDescriptors}`
+    );
+    getDatabaseDdlResponse.statements.forEach(element => {
       console.log(element);
     });
   }

samples/package.json

@@ -18,7 +18,8 @@
     "@google-cloud/kms": "^4.0.0",
     "@google-cloud/precise-date": "^4.0.0",
     "@google-cloud/spanner": "^7.7.0",
-    "yargs": "^17.0.0"
+    "yargs": "^17.0.0",
+    "protobufjs": "^7.0.0"
   },
   "devDependencies": {
     "chai": "^4.2.0",

samples/proto-query-data.js

@@ -0,0 +1,100 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+// eslint-disable-next-line node/no-unpublished-require
+const singer = require('./resource/singer.js');
+const music = singer.examples.spanner.music;
+
+function main(
+  instanceId = 'my-instance',
+  databaseId = 'my-database',
+  projectId = 'my-project-id'
+) {
+  // [START spanner_query_with_proto_types_parameter]
+  /**
+   * 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 Spanner client library
+  const {Spanner} = require('@google-cloud/spanner');
+
+  // Instantiates a client
+  const spanner = new Spanner({
+    projectId: projectId,
+  });
+
+  async function queryDataWithProtoTypes() {
+    // Gets a reference to a Cloud Spanner instance and database.
+    const instance = spanner.instance(instanceId);
+    const database = instance.database(databaseId);
+
+    const query = {
+      sql: `SELECT SingerId,
+                   SingerInfo,
+                   SingerInfo.nationality,
+                   SingerInfoArray,
+                   SingerGenre,
+                   SingerGenreArray
+            FROM Singers 
+            WHERE SingerInfo.nationality = @country 
+            and SingerGenre=@singerGenre`,
+      params: {
+        country: 'Country2',
+        singerGenre: music.Genre.FOLK,
+      },
+      /* `columnsMetadata` is an optional parameter and is used to deserialize the
+      proto message and enum object back from bytearray and int respectively.
+      If columnsMetadata is not passed for proto messages and enums, then the data
+      types for these columns will be bytes and int respectively. */
+      columnsMetadata: {
+        SingerInfo: music.SingerInfo,
+        SingerInfoArray: music.SingerInfo,
+        SingerGenre: music.Genre,
+        SingerGenreArray: music.Genre,
+      },
+    };
+
+    // Queries rows from the Singers table.
+    try {
+      const [rows] = await database.run(query);
+
+      rows.forEach(row => {
+        const json = row.toJSON();
+        console.log(
+          `SingerId: ${json.SingerId}, SingerInfo: ${json.SingerInfo}, SingerGenre: ${json.SingerGenre}, 
+          SingerInfoArray: ${json.SingerInfoArray}, SingerGenreArray: ${json.SingerGenreArray}`
+        );
+      });
+    } catch (err) {
+      console.error('ERROR:', err);
+    } finally {
+      // Close the database when finished.
+      database.close();
+    }
+  }
+
+  queryDataWithProtoTypes();
+  // [END spanner_query_with_proto_types_parameter]
+}
+
+process.on('unhandledRejection', err => {
+  console.error(err.message);
+  process.exitCode = 1;
+});
+main(...process.argv.slice(2));

samples/proto-type-add-column.js

@@ -0,0 +1,90 @@
+/**
+ * Copyright 2024 Google LLC
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// sample-metadata:
+//  title: Creates a new database with a proto column and enum
+//  usage: node proto-type-add-column.js <INSTANCE_ID> <DATABASE_ID> <PROJECT_ID>
+
+'use strict';
+
+const fs = require('fs');
+
+function main(
+  instanceId = 'my-instance',
+  databaseId = 'my-database',
+  projectId = 'my-project-id'
+) {
+  // [START spanner_add_proto_type_columns]
+  /**
+   * 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';
+
+  // Imports the Google Cloud client library
+  const {Spanner} = require('@google-cloud/spanner');
+
+  // Creates a client
+  const spanner = new Spanner({
+    projectId: projectId,
+  });
+
+  const databaseAdminClient = spanner.getDatabaseAdminClient();
+  async function protoTypeAddColumn() {
+    // Adds a new Proto Message column and Proto Enum column to the Singers table.
+
+    const request = [
+      `CREATE PROTO BUNDLE (
+            examples.spanner.music.SingerInfo,
+            examples.spanner.music.Genre,
+            )`,
+      'ALTER TABLE Singers ADD COLUMN SingerInfo examples.spanner.music.SingerInfo',
+      'ALTER TABLE Singers ADD COLUMN SingerInfoArray ARRAY<examples.spanner.music.SingerInfo>',
+      'ALTER TABLE Singers ADD COLUMN SingerGenre examples.spanner.music.Genre',
+      'ALTER TABLE Singers ADD COLUMN SingerGenreArray ARRAY<examples.spanner.music.Genre>',
+    ];
+
+    // Read a proto descriptor file and convert it to a base64 string
+    const protoDescriptor = fs
+      .readFileSync('./resource/descriptors.pb')
+      .toString('base64');
+
+    // Alter existing table to add a column.
+    const [operation] = await databaseAdminClient.updateDatabaseDdl({
+      database: databaseAdminClient.databasePath(
+        projectId,
+        instanceId,
+        databaseId
+      ),
+      statements: request,
+      protoDescriptors: protoDescriptor,
+    });
+
+    console.log(`Waiting for operation on ${databaseId} to complete...`);
+    await operation.promise();
+    console.log(
+      `Altered table "Singers" on database ${databaseId} on instance ${instanceId} with proto descriptors.`
+    );
+  }
+  protoTypeAddColumn();
+  // [END spanner_add_proto_type_columns]
+}
+
+process.on('unhandledRejection', err => {
+  console.error(err.message);
+  process.exitCode = 1;
+});
+main(...process.argv.slice(2));