feat(spanner): add samples and sample tests

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

samples/proto-update-data-dml.js

@@ -0,0 +1,128 @@
+// 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_update_data_with_proto_types_with_dml]
+  /**
+   * 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 updateDataUsingDmlWithProtoTypes() {
+    /*
+    Updates Singers tables in the database with the ProtoMessage
+    and ProtoEnum column.
+    This updates the `SingerInfo`, `SingerInfoArray`, `SingerGenre` and
+    SingerGenreArray` columns which must be created before running this sample.
+    You can add the column by running the `add_proto_type_columns` sample or
+    by running this DDL statement against your database:
+
+    ALTER TABLE Singers ADD COLUMN SingerInfo examples.spanner.music.SingerInfo\n
+    ALTER TABLE Singers ADD COLUMN SingerInfoArray ARRAY<examples.spanner.music.SingerInfo>\n
+    ALTER TABLE Singers ADD COLUMN SingerGenre examples.spanner.music.Genre\n
+    ALTER TABLE Singers ADD COLUMN SingerGenreArray ARRAY<examples.spanner.music.Genre>\n
+    */
+
+    // Gets a reference to a Cloud Spanner instance and database.
+    const instance = spanner.instance(instanceId);
+    const database = instance.database(databaseId);
+
+    const genre = music.Genre.ROCK;
+    const singerInfo = music.SingerInfo.create({
+      singerId: 1,
+      genre: genre,
+      birthDate: 'January',
+      nationality: 'Country1',
+    });
+
+    const protoMessage = Spanner.protoMessage({
+      value: singerInfo,
+      messageFunction: music.SingerInfo,
+      fullName: 'examples.spanner.music.SingerInfo',
+    });
+
+    const protoEnum = Spanner.protoEnum({
+      value: genre,
+      enumObject: music.Genre,
+      fullName: 'examples.spanner.music.Genre',
+    });
+
+    database.runTransaction(async (err, transaction) => {
+      if (err) {
+        console.error(err);
+        return;
+      }
+      try {
+        const [, stats] = await transaction.run({
+          sql: `UPDATE Singers SET SingerInfo=@singerInfo, SingerInfoArray=@singerInfoArray, 
+          SingerGenre=@singerGenre, SingerGenreArray=@singerGenreArray WHERE SingerId = 1`,
+          params: {
+            singerInfo: protoMessage,
+            singerInfoArray: [protoMessage, null],
+            singerGenre: genre,
+            singerGenreArray: [protoEnum, null],
+          },
+        });
+
+        const rowCount = stats[stats.rowCount];
+        console.log(`${rowCount} record updated.`);
+
+        const [, stats1] = await transaction.run({
+          sql: 'UPDATE Singers SET SingerInfo.nationality=@singerNationality WHERE SingerId = 1',
+          params: {
+            singerNationality: 'Country2',
+          },
+        });
+        const rowCount1 = stats1[stats1.rowCount];
+        console.log(`${rowCount1} record updated.`);
+
+        await transaction.commit();
+      } catch (err) {
+        console.error('ERROR:', err);
+      } finally {
+        // Close the database when finished.
+        database.close();
+      }
+    });
+  }
+
+  updateDataUsingDmlWithProtoTypes();
+  // [END spanner_update_data_with_proto_types_with_dml]
+}
+
+process.on('unhandledRejection', err => {
+  console.error(err.message);
+  process.exitCode = 1;
+});
+main(...process.argv.slice(2));