feat: support batch create sessions

README.md

@@ -133,12 +133,10 @@ Apache Version 2.0
 
 See [LICENSE](https://github.com/googleapis/nodejs-spanner/blob/master/LICENSE)
 
-[client-docs]: https://googleapis.dev/nodejs/spanner/latest#reference
+[client-docs]: https://googleapis.dev/nodejs/spanner/latest
 [product-docs]: https://cloud.google.com/spanner/docs/
 [shell_img]: https://gstatic.com/cloudssh/images/open-btn.png
 [projects]: https://console.cloud.google.com/project
 [billing]: https://support.google.com/cloud/answer/6293499#enable-billing
 [enable_api]: https://console.cloud.google.com/flows/enableapi?apiid=spanner.googleapis.com
 [auth]: https://cloud.google.com/docs/authentication/getting-started
-
-<a name="reference"></a>

protos/google/spanner/v1/spanner.proto

@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC.
+// Copyright 2019 Google LLC.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -66,6 +66,18 @@ service Spanner {
     };
   }
 
+  // Creates multiple new sessions.
+  //
+  // This API can be used to initialize a session cache on the clients.
+  // See https://goo.gl/TgSFN2 for best practices on session cache management.
+  rpc BatchCreateSessions(BatchCreateSessionsRequest)
+      returns (BatchCreateSessionsResponse) {
+    option (google.api.http) = {
+      post: "/v1/{database=projects/*/instances/*/databases/*}/sessions:batchCreate"
+      body: "*"
+    };
+  }
+
   // Gets a session. Returns `NOT_FOUND` if the session does not exist.
   // This is mainly useful for determining whether a session is still
   // alive.
@@ -129,8 +141,9 @@ service Spanner {
   //
   // Statements are executed in order, sequentially.
   // [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse] will contain a
-  // [ResultSet][google.spanner.v1.ResultSet] for each DML statement that has successfully executed. If a
-  // statement fails, its error status will be returned as part of the
+  // [ResultSet][google.spanner.v1.ResultSet] for each DML statement that has
+  // successfully executed. If a statement fails, its error status will be
+  // returned as part of the
   // [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse]. Execution will
   // stop at the first failed statement; the remaining statements will not run.
   //
@@ -142,7 +155,8 @@ service Spanner {
   // See more details in
   // [ExecuteBatchDmlRequest][Spanner.ExecuteBatchDmlRequest] and
   // [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse].
-  rpc ExecuteBatchDml(ExecuteBatchDmlRequest) returns (ExecuteBatchDmlResponse) {
+  rpc ExecuteBatchDml(ExecuteBatchDmlRequest)
+      returns (ExecuteBatchDmlResponse) {
     option (google.api.http) = {
       post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeBatchDml"
       body: "*"
@@ -275,6 +289,31 @@ message CreateSessionRequest {
   Session session = 2;
 }
 
+// The request for
+// [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions].
+message BatchCreateSessionsRequest {
+  // Required. The database in which the new sessions are created.
+  string database = 1;
+
+  // Parameters to be applied to each created session.
+  Session session_template = 2;
+
+  // Required. The number of sessions to be created in this batch call.
+  // The API may return fewer than the requested number of sessions. If a
+  // specific number of sessions are desired, the client can make additional
+  // calls to BatchCreateSessions (adjusting
+  // [session_count][google.spanner.v1.BatchCreateSessionsRequest.session_count]
+  // as necessary).
+  int32 session_count = 3;
+}
+
+// The response for
+// [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions].
+message BatchCreateSessionsResponse {
+  // The freshly created sessions.
+  repeated Session session = 1;
+}
+
 // A session in the Cloud Spanner API.
 message Session {
   // The name of the session. This is always system-assigned; values provided
@@ -371,9 +410,6 @@ message ExecuteSqlRequest {
   // Required. The session in which the SQL query should be performed.
   string session = 1;
 
-  // The transaction to use. If none is provided, the default is a
-  // temporary read-only transaction with strong concurrency.
-  //
   // The transaction to use.
   //
   // For queries, if none is provided, the default is a temporary read-only
@@ -476,7 +512,9 @@ message ExecuteBatchDmlRequest {
 
     // It is not always possible for Cloud Spanner to infer the right SQL type
     // from a JSON value.  For example, values of type `BYTES` and values
-    // of type `STRING` both appear in [params][google.spanner.v1.ExecuteBatchDmlRequest.Statement.params] as JSON strings.
+    // of type `STRING` both appear in
+    // [params][google.spanner.v1.ExecuteBatchDmlRequest.Statement.params] as
+    // JSON strings.
     //
     // In these cases, `param_types` can be used to specify the exact
     // SQL type for some or all of the SQL statement parameters. See the
@@ -508,11 +546,13 @@ message ExecuteBatchDmlRequest {
   int64 seqno = 4;
 }
 
-// The response for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Contains a list
-// of [ResultSet][google.spanner.v1.ResultSet], one for each DML statement that has successfully executed.
-// If a statement fails, the error is returned as part of the response payload.
-// Clients can determine whether all DML statements have run successfully, or if
-// a statement failed, using one of the following approaches:
+// The response for
+// [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Contains a list
+// of [ResultSet][google.spanner.v1.ResultSet], one for each DML statement that
+// has successfully executed. If a statement fails, the error is returned as
+// part of the response payload. Clients can determine whether all DML
+// statements have run successfully, or if a statement failed, using one of the
+// following approaches:
 //
 //   1. Check if 'status' field is OkStatus.
 //   2. Check if result_sets_size() equals the number of statements in
@@ -529,9 +569,11 @@ message ExecuteBatchDmlRequest {
 // result_set_size() client can determine that the 3rd statement has failed.
 message ExecuteBatchDmlResponse {
   // ResultSets, one for each statement in the request that ran successfully, in
-  // the same order as the statements in the request. Each [ResultSet][google.spanner.v1.ResultSet] will
-  // not contain any rows. The [ResultSetStats][google.spanner.v1.ResultSetStats] in each [ResultSet][google.spanner.v1.ResultSet] will
-  // contain the number of rows modified by the statement.
+  // the same order as the statements in the request. Each
+  // [ResultSet][google.spanner.v1.ResultSet] will not contain any rows. The
+  // [ResultSetStats][google.spanner.v1.ResultSetStats] in each
+  // [ResultSet][google.spanner.v1.ResultSet] will contain the number of rows
+  // modified by the statement.
   //
   // Only the first ResultSet in the response contains a valid
   // [ResultSetMetadata][google.spanner.v1.ResultSetMetadata].

src/v1/doc/google/iam/v1/doc_options.js

@@ -20,9 +20,13 @@
  *
  * @property {number} requestedPolicyVersion
  *   Optional. The policy format version to be returned.
- *   Acceptable values are 0 and 1.
- *   If the value is 0, or the field is omitted, policy format version 1 will be
- *   returned.
+ *
+ *   Valid values are 0, 1, and 3. Requests specifying an invalid value will be
+ *   rejected.
+ *
+ *   Requests for policies with any conditional bindings must specify version 3.
+ *   Policies without any conditional bindings may specify any valid value or
+ *   leave the field unset.
  *
  * @typedef GetPolicyOptions
  * @memberof google.iam.v1

src/v1/doc/google/iam/v1/doc_policy.js

@@ -63,7 +63,14 @@
  * [IAM developer's guide](https://cloud.google.com/iam/docs).
  *
  * @property {number} version
- *   Deprecated.
+ *   Specifies the format of the policy.
+ *
+ *   Valid values are 0, 1, and 3. Requests specifying an invalid value will be
+ *   rejected.
+ *
+ *   Policies with any conditional bindings must specify version 3. Policies
+ *   without any conditional bindings may specify any valid value or leave the
+ *   field unset.
  *
  * @property {Object[]} bindings
  *   Associates a list of `members` to a `role`.

src/v1/doc/google/protobuf/doc_timestamp.js

@@ -89,11 +89,13 @@
  * 01:30 UTC on January 15, 2017.
  *
  * In JavaScript, one can convert a Date object to this format using the
- * standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
+ * standard
+ * [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
  * method. In Python, a standard `datetime.datetime` object can be converted
- * to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime)
- * with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one
- * can use the Joda Time's [`ISODateTimeFormat.dateTime()`](https://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime%2D%2D) to obtain a formatter capable of generating timestamps in this format.
+ * to this format using
+ * [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with
+ * the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use
+ * the Joda Time's [`ISODateTimeFormat.dateTime()`](https://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime%2D%2D) to obtain a formatter capable of generating timestamps in this format.
  *
  * @property {number} seconds
  *   Represents seconds of UTC time since Unix epoch

src/v1/doc/google/spanner/v1/doc_spanner.js

@@ -34,6 +34,51 @@ const CreateSessionRequest = {
   // This is for documentation. Actual contents will be loaded by gRPC.
 };
 
+/**
+ * The request for
+ * BatchCreateSessions.
+ *
+ * @property {string} database
+ *   Required. The database in which the new sessions are created.
+ *
+ * @property {Object} sessionTemplate
+ *   Parameters to be applied to each created session.
+ *
+ *   This object should have the same structure as [Session]{@link google.spanner.v1.Session}
+ *
+ * @property {number} sessionCount
+ *   Required. The number of sessions to be created in this batch call.
+ *   The API may return fewer than the requested number of sessions. If a
+ *   specific number of sessions are desired, the client can make additional
+ *   calls to BatchCreateSessions (adjusting
+ *   session_count
+ *   as necessary).
+ *
+ * @typedef BatchCreateSessionsRequest
+ * @memberof google.spanner.v1
+ * @see [google.spanner.v1.BatchCreateSessionsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto}
+ */
+const BatchCreateSessionsRequest = {
+  // This is for documentation. Actual contents will be loaded by gRPC.
+};
+
+/**
+ * The response for
+ * BatchCreateSessions.
+ *
+ * @property {Object[]} session
+ *   The freshly created sessions.
+ *
+ *   This object should have the same structure as [Session]{@link google.spanner.v1.Session}
+ *
+ * @typedef BatchCreateSessionsResponse
+ * @memberof google.spanner.v1
+ * @see [google.spanner.v1.BatchCreateSessionsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/spanner.proto}
+ */
+const BatchCreateSessionsResponse = {
+  // This is for documentation. Actual contents will be loaded by gRPC.
+};
+
 /**
  * A session in the Cloud Spanner API.
  *
@@ -164,9 +209,6 @@ const DeleteSessionRequest = {
  *   Required. The session in which the SQL query should be performed.
  *
  * @property {Object} transaction
- *   The transaction to use. If none is provided, the default is a
- *   temporary read-only transaction with strong concurrency.
- *
  *   The transaction to use.
  *
  *   For queries, if none is provided, the default is a temporary read-only
@@ -345,7 +387,9 @@ const ExecuteBatchDmlRequest = {
    * @property {Object.<string, Object>} paramTypes
    *   It is not always possible for Cloud Spanner to infer the right SQL type
    *   from a JSON value.  For example, values of type `BYTES` and values
-   *   of type `STRING` both appear in params as JSON strings.
+   *   of type `STRING` both appear in
+   *   params as
+   *   JSON strings.
    *
    *   In these cases, `param_types` can be used to specify the exact
    *   SQL type for some or all of the SQL statement parameters. See the
@@ -362,11 +406,13 @@ const ExecuteBatchDmlRequest = {
 };
 
 /**
- * The response for ExecuteBatchDml. Contains a list
- * of ResultSet, one for each DML statement that has successfully executed.
- * If a statement fails, the error is returned as part of the response payload.
- * Clients can determine whether all DML statements have run successfully, or if
- * a statement failed, using one of the following approaches:
+ * The response for
+ * ExecuteBatchDml. Contains a list
+ * of ResultSet, one for each DML statement that
+ * has successfully executed. If a statement fails, the error is returned as
+ * part of the response payload. Clients can determine whether all DML
+ * statements have run successfully, or if a statement failed, using one of the
+ * following approaches:
  *
  *   1. Check if 'status' field is OkStatus.
  *   2. Check if result_sets_size() equals the number of statements in
@@ -384,9 +430,11 @@ const ExecuteBatchDmlRequest = {
  *
  * @property {Object[]} resultSets
  *   ResultSets, one for each statement in the request that ran successfully, in
- *   the same order as the statements in the request. Each ResultSet will
- *   not contain any rows. The ResultSetStats in each ResultSet will
- *   contain the number of rows modified by the statement.
+ *   the same order as the statements in the request. Each
+ *   ResultSet will not contain any rows. The
+ *   ResultSetStats in each
+ *   ResultSet will contain the number of rows
+ *   modified by the statement.
  *
  *   Only the first ResultSet in the response contains a valid
  *   ResultSetMetadata.