feat: [Spanner] Add query options support

apis/Google.Cloud.Spanner.Data/Google.Cloud.Spanner.Data.Tests/QueryOptionsTests.cs

@@ -0,0 +1,45 @@
+// Copyright 2020 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
+//
+//     https://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.
+
+using Google.Cloud.Spanner.V1;
+using System;
+using Xunit;
+
+namespace Google.Cloud.Spanner.Data.Tests
+{
+    public class QueryOptionsTests
+    {
+        [Fact]
+        public void FromProtoFromEmptyProto()
+        {
+            var proto = new V1.ExecuteSqlRequest.Types.QueryOptions();
+            var queryOptions = QueryOptions.FromProto(proto);
+            Assert.Equal("", queryOptions.OptimizerVersion);
+        }
+
+        [Fact]
+        public void NoOptionsSet()
+        {
+            var queryOptions = new QueryOptions();
+            Assert.Equal("", queryOptions.OptimizerVersion);
+        }
+
+        [Fact]
+        public void SetAndGetOptimizerVersion()
+        {
+            var queryOptions = new QueryOptions().WithOptimizerVersion("latest");
+            Assert.Equal("latest", queryOptions.OptimizerVersion);
+        }
+    }
+}

apis/Google.Cloud.Spanner.Data/Google.Cloud.Spanner.Data.Tests/SpannerCommandTests.cs

@@ -12,9 +12,15 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+using Google.Api.Gax.Grpc;
+using Google.Cloud.Spanner.V1;
+using Google.Cloud.Spanner.V1.Tests;
+using Google.Cloud.Spanner.V1.Internal.Logging;
+using Moq;
 using System;
 using System.Data;
 using System.Linq;
+using System.Threading.Tasks;
 using Xunit;
 
 namespace Google.Cloud.Spanner.Data.Tests
@@ -85,5 +91,100 @@ public void CloneUpdateWithParameters()
             Assert.True(command.Parameters.SequenceEqual(command2.Parameters));
         }
 
+        /*
+        [Fact]
+        public void CommandHasConnectionQueryOptions()
+        {
+            const string optimzerVersion = "1";
+            var spannerClientMock = SpannerClientHelpers
+                .CreateMockClient(Logger.DefaultLogger, MockBehavior.Strict)
+                .Setup(client => client.ExecuteSqlAsync(It.IsNotNull<ExecuteSqlRequest>(), It.Is<ExecuteSqlRequest>(request => request.QueryOptions.OptimzerVersion == optimizerVersion)))
+                .Returns<ExecuteSqlRequest, CallSettings>((request, _) =>
+                {
+                    ResultSet response = new ResultSet();
+
+                    return Task.FromResult(response);
+                });
+
+            SpannerConnection connection = BuildSpannerConnection(spannerClientMock);
+            var queryOptions = new QueryOptions().WithOptimizerVersion(optimizerVersion);
+            connection.QueryOptions = queryOptions;
+
+            var command = connection.CreateSelectCommand("SELECT * FROM FOO");
+            using (var reader = await command.ExecuteReaderAsync())
+            {
+                while (await reader.ReadAsync())
+                {
+                    // Do nothing.
+                }
+            }
+        }
+
+        [Fact]
+        public void CommandHasOptimizerVersionFromEnvironment()
+        {
+            // Save existing value of environment variable.
+            const string optimizerVersionVariable = "SPANNER_OPTIMIZER_VERSION";
+            string savedOptimizerVersion = Environment.GetEnvironmentVariable(optimizerVersionVariable);
+            const string envOptimizerVersion = "2";
+            Environment.SetEnvironmentVariable(optimizerVersionVariable, envOptimizerVersion);
+
+            var connection = new SpannerConnection("Data Source=projects/p/instances/i/databases/d");
+            connection.QueryOptions = new QueryOptions().WithOptimizerVersion("1");
+
+            var command = connection.CreateSelectCommand("SELECT * FROM FOO");
+            // Optimizer version set through environment variable has higher
+            // precedence than version set through connection.
+            Assert.Equal(envOptimizerVersion, command.QueryOptions.OptimizerVersion);
+
+            // Set the environment back.
+            Environment.SetEnvironmentVariable(optimizerVersionVariable, savedOptimizerVersion);
+        }
+
+        [Fact]
+        public void CommandHasOptimizerVersionSetOnCommand()
+        {
+            // Save existing value of environment variable.
+            const string optimizerVersionVariable = "SPANNER_OPTIMIZER_VERSION";
+            string savedOptimizerVersion = Environment.GetEnvironmentVariable(optimizerVersionVariable);
+            const string envOptimizerVersion = "2";
+            Environment.SetEnvironmentVariable(optimizerVersionVariable, envOptimizerVersion);
+
+            var connection = new SpannerConnection("Data Source=projects/p/instances/i/databases/d");
+            connection.QueryOptions = new QueryOptions().WithOptimizerVersion("1");
+
+            var command = connection.CreateSelectCommand("SELECT * FROM FOO");
+            var commandOptimizerVersion = "3";
+            command.QueryOptions = new QueryOptions().WithOptimizerVersion("3");
+            // Optimizer version set at a command level has higher precedence
+            // than version set through the connection or the environment
+            // variable.
+            Assert.Equal(commandOptimizerVersion, command.QueryOptions.OptimizerVersion);
+
+            // Set the environment back.
+            Environment.SetEnvironmentVariable(optimizerVersionVariable, savedOptimizerVersion);
+        }
+
+        private SpannerConnection BuildSpannerConnection(Mock<SpannerClient> spannerClientMock)
+        {
+            var spannerClient = spannerClientMock.Object;
+            var sessionPoolOptions = new SessionPoolOptions
+            {
+                MaintenanceLoopDelay = TimeSpan.Zero
+            };
+
+            var sessionPoolManager = new SessionPoolManager(sessionPoolOptions, spannerClient.Settings.Logger, (_o, _s, _l) => Task.FromResult(spannerClient));
+            sessionPoolManager.SpannerSettings.Scheduler = spannerClient.Settings.Scheduler;
+            sessionPoolManager.SpannerSettings.Clock = spannerClient.Settings.Clock;
+
+            SpannerConnectionStringBuilder builder = new SpannerConnectionStringBuilder
+            {
+                DataSource = DatabaseName.Format(SpannerClientHelpers.ProjectId, SpannerClientHelpers.Instance, SpannerClientHelpers.Database),
+                SessionPoolManager = sessionPoolManager
+            };
+
+            return new SpannerConnection(builder);
+        }
+        */
     }
 }

apis/Google.Cloud.Spanner.Data/Google.Cloud.Spanner.Data/QueryOptions.cs

@@ -0,0 +1,103 @@
+// Copyright 2020 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
+//
+//     https://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.
+
+using Google.Api.Gax;
+using Google.Cloud.Spanner.V1;
+using System;
+
+namespace Google.Cloud.Spanner.Data
+{
+    /// <summary>
+    /// Immutable class representing query options.
+    /// </summary>
+    public sealed class QueryOptions : IEquatable<QueryOptions>
+    {
+        /// <summary>
+        /// The query optimizer version configured in the options.
+        /// </summary>
+        public string OptimizerVersion
+        {
+            get => Proto.OptimizerVersion;
+        }
+
+        /// <summary>
+        /// Clones the options and sets the optimizer version to the given value.
+        /// </summary>
+        /// <returns>
+        /// A clone of the options with the updated optimizer version.
+        /// </returns>
+        /// <remarks>
+        /// <para>The parameter allows individual queries to pick different query
+        /// optimizer versions.</para>
+        /// <para>Specifying "latest" as a value instructs Cloud Spanner to use the
+        /// latest supported query optimizer version. If not specified, Cloud Spanner
+        /// uses optimizer version set at the database level options. Any other
+        /// positive integer (from the list of supported optimizer versions)
+        /// overrides the default optimizer version for query execution.</para>
+        /// </remarks>
+        /// <param name="optimizerVersion">Optimizer version to set.</param>
+        public QueryOptions WithOptimizerVersion(string optimizerVersion)
+        {
+           var protoCopy = Proto.Clone();
+           protoCopy.OptimizerVersion = optimizerVersion;
+           return new QueryOptions(protoCopy);
+        }
+
+
+        /// <summary>
+        /// The proto representation of the query options. Must not be mutated
+        /// or exposed publicly.
+        /// </summary>
+        internal V1.ExecuteSqlRequest.Types.QueryOptions Proto { get; }
+
+        private QueryOptions(V1.ExecuteSqlRequest.Types.QueryOptions proto) => Proto = proto;
+
+        /// <summary>
+        /// Creates query options without specifying any options.
+        /// </summary>
+        public QueryOptions() : this(new V1.ExecuteSqlRequest.Types.QueryOptions())
+        {
+        }
+
+        /// <summary>
+        /// Set query options from the given proto.
+        /// </summary>
+        /// <remarks>
+        /// The given proto should not be null. The given proto is cloned.
+        /// </remarks>
+        /// <param name="proto">The proto to construct <see cref="QueryOptions"/> from.</param>
+        public static QueryOptions FromProto(
+            V1.ExecuteSqlRequest.Types.QueryOptions proto)
+        {
+            GaxPreconditions.CheckNotNull(proto, nameof(proto));
+            return new QueryOptions(proto.Clone());
+        }
+
+        /// <inheritdoc />
+        public bool Equals(QueryOptions other)
+        {
+            if (other is null)
+            {
+                return false;
+            }
+            return OptimizerVersion == other.OptimizerVersion;
+        }
+
+        /// <inheritdoc />
+        public override bool Equals(object obj) => Equals(obj as QueryOptions);
+
+        /// <inheritdoc />
+        public override int GetHashCode() => Proto.GetHashCode();
+    }
+}

apis/Google.Cloud.Spanner.Data/Google.Cloud.Spanner.Data/SpannerCommand.ExecutableCommand.cs

@@ -53,12 +53,15 @@ private static DatabaseAdminSettings CreateDatabaseAdminSettings()
                 return settings;
             }
 
+            private const string SpannerOptimizerVersionVariable = "SPANNER_OPTIMIZER_VERSION";
+
             internal SpannerConnection Connection { get; }
             internal SpannerCommandTextBuilder CommandTextBuilder { get; }
             internal int CommandTimeout { get; }
             internal SpannerTransaction Transaction { get; }
             internal CommandPartition Partition { get; }
             internal SpannerParameterCollection Parameters { get; }
+            internal QueryOptions QueryOptions { get; }
 
             public ExecutableCommand(SpannerCommand command)
             {
@@ -68,6 +71,7 @@ public ExecutableCommand(SpannerCommand command)
                 Partition = command.Partition;
                 Parameters = command.Parameters;
                 Transaction = command._transaction;
+                QueryOptions = command.QueryOptions;
             }
 
             // ExecuteScalar is simply implemented in terms of ExecuteReader.
@@ -335,6 +339,43 @@ private List<Mutation> GetMutations()
                 }
             }
 
+            // Based on the QueryOptions set at various levels (connection, environment and command),
+            // constructs the QueryOptions proto to set in the ExecuteSqlRequest.
+            // Options set at the SpannerCommand-level has the highest precedence.
+            // Options set at the environment variable level has the next highest precedence.
+            // Options set at the connection level has the lowest precedence.
+            private V1.ExecuteSqlRequest.Types.QueryOptions GetEffectiveQueryOptions()
+            {
+                string optimizerVersion = "";
+
+                // Query options set at the command level have the highest precedence.
+                if (QueryOptions != null)
+                {
+                    optimizerVersion = QueryOptions.OptimizerVersion;
+                }
+
+                // Query options set through an environment variable have the next highest precedence.
+                if (string.IsNullOrEmpty(optimizerVersion))
+                {
+                    optimizerVersion = Environment.GetEnvironmentVariable(SpannerOptimizerVersionVariable)?.Trim() ?? "";
+                }
+
+                // Query options set through the connection have the lowest highest precedence.
+                if (string.IsNullOrEmpty(optimizerVersion) && Connection.QueryOptions != null)
+                {
+                    optimizerVersion = Connection.QueryOptions.OptimizerVersion;
+                }
+
+                if (string.IsNullOrEmpty(optimizerVersion))
+                {
+                    return null;
+                }
+
+                var queryOptionsProto = new V1.ExecuteSqlRequest.Types.QueryOptions();
+                queryOptionsProto.OptimizerVersion = optimizerVersion;
+                return queryOptionsProto;
+            }
+
             private ExecuteSqlRequest GetExecuteSqlRequest()
             {
                 if (Partition != null)
@@ -347,6 +388,8 @@ private ExecuteSqlRequest GetExecuteSqlRequest()
                     Sql = CommandTextBuilder.ToString()
                 };
 
+                request.QueryOptions = GetEffectiveQueryOptions();
+
                 // See comment at the start of GetMutations.
                 SpannerConversionOptions options = null;
                 Parameters.FillSpannerCommandParams(out var parameters, request.ParamTypes, options);

apis/Google.Cloud.Spanner.Data/Google.Cloud.Spanner.Data/SpannerCommand.cs

@@ -41,6 +41,7 @@ public sealed partial class SpannerCommand : DbCommand, ICloneable
         private readonly CancellationTokenSource _synchronousCancellationTokenSource = new CancellationTokenSource();
         private int _commandTimeout;
         private SpannerTransaction _transaction;
+        private QueryOptions _queryOptions = null;
 
         /// <summary>
         /// Initializes a new instance of <see cref="SpannerCommand"/>, using a default command timeout.
@@ -219,6 +220,15 @@ public override UpdateRowSource UpdatedRowSource
             }
         }
 
+        /// <summary>
+        /// Query options to use when running SQL and streaming SQL commands.
+        /// </summary>
+        public QueryOptions QueryOptions
+        {
+            get => _queryOptions;
+            set => _queryOptions = (QueryOptions) value;
+        }
+
         /// <inheritdoc />
         protected override DbConnection DbConnection
         {

apis/Google.Cloud.Spanner.Data/Google.Cloud.Spanner.Data/SpannerConnection.cs

@@ -110,6 +110,18 @@ public override ConnectionState State
 
         internal bool IsOpen => (State & ConnectionState.Open) == ConnectionState.Open;
 
+        private QueryOptions _queryOptions = null;
+
+        /// <summary>
+        /// Query options to use throughout the lifetime of the connection when
+        /// running SQL and streaming SQL requests.
+        /// </summary>
+        public QueryOptions QueryOptions
+        {
+            get => _queryOptions;
+            set => _queryOptions = (QueryOptions) value;
+        }
+
         /// <summary>
         /// Creates a SpannerConnection with no datasource or credential specified.
         /// </summary>