Google Cloud Spanner C++ Client  2.1.0
A C++ Client Library for Google Cloud Spanner
connection.h
Go to the documentation of this file.
1 // Copyright 2019 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_CONNECTION_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_CONNECTION_H
17 
18 #include "google/cloud/spanner/batch_dml_result.h"
19 #include "google/cloud/spanner/commit_options.h"
20 #include "google/cloud/spanner/commit_result.h"
21 #include "google/cloud/spanner/keys.h"
22 #include "google/cloud/spanner/mutations.h"
23 #include "google/cloud/spanner/partition_options.h"
24 #include "google/cloud/spanner/partitioned_dml_result.h"
25 #include "google/cloud/spanner/query_options.h"
26 #include "google/cloud/spanner/read_options.h"
27 #include "google/cloud/spanner/results.h"
28 #include "google/cloud/spanner/sql_statement.h"
29 #include "google/cloud/spanner/transaction.h"
30 #include "google/cloud/spanner/version.h"
31 #include "google/cloud/optional.h"
32 #include "google/cloud/options.h"
33 #include "google/cloud/status_or.h"
34 #include "absl/types/optional.h"
35 #include <string>
36 #include <vector>
37 
38 namespace google {
39 namespace cloud {
40 namespace spanner {
42 
43 class ReadPartition;
44 class QueryPartition;
45 
46 /**
47  * A connection to a Spanner database instance.
48  *
49  * This interface defines pure-virtual methods for each of the user-facing
50  * overload sets in `Client`. That is, all of `Client`'s `Read()` overloads
51  * will forward to the one pure-virtual `Read()` method declared in this
52  * interface, and similar for `Client`'s other methods. This allows users to
53  * inject custom behavior (e.g., with a Google Mock object) in a `Client`
54  * object for use in their own tests.
55  *
56  * To create a concrete instance that connects you to a real Spanner database,
57  * see `MakeConnection()`.
58  */
59 class Connection {
60  public:
61  virtual ~Connection() = default;
62 
63  //@{
64  /**
65  * @name Defines the arguments for each member function.
66  *
67  * Applications may define classes derived from `Connection`, for example,
68  * because they want to mock the class. To avoid breaking all such derived
69  * classes when we change the number or type of the arguments to the member
70  * functions we define light weight structures to pass the arguments.
71  */
72 
73  /// Wrap the arguments to `Read()`.
74  struct ReadParams {
76  std::string table;
78  std::vector<std::string> columns;
80  absl::optional<std::string> partition_token;
81  };
82 
83  /// Wrap the arguments to `PartitionRead()`.
87  };
88 
89  /// Wrap the arguments to `ExecuteQuery()`, `ExecuteDml()`, `ProfileQuery()`,
90  /// `ProfileDml()`, and `AnalyzeSql()`.
91  struct SqlParams {
95  absl::optional<std::string> partition_token;
96  };
97 
98  /// Wrap the arguments to `ExecutePartitionedDml()`.
102  };
103 
104  /// Wrap the arguments to `PartitionQuery()`.
109  };
110 
111  /// Wrap the arguments to `ExecuteBatchDml()`.
114  std::vector<SqlStatement> statements;
116  };
117 
118  /// Wrap the arguments to `Commit()`.
119  struct CommitParams {
121  Mutations mutations;
123  };
124 
125  /// Wrap the arguments to `Rollback()`.
126  struct RollbackParams {
128  };
129  //@}
130 
131  /// Returns the options used by the Connection.
132  virtual Options options() { return Options{}; }
133 
134  /// Defines the interface for `Client::Read()`
136 
137  /// Defines the interface for `Client::PartitionRead()`
138  virtual StatusOr<std::vector<ReadPartition>> PartitionRead(
140 
141  /// Defines the interface for `Client::ExecuteQuery()`
143 
144  /// Defines the interface for `Client::ExecuteDml()`
145  virtual StatusOr<DmlResult> ExecuteDml(SqlParams);
146 
147  /// Defines the interface for `Client::ProfileQuery()`
149 
150  /// Defines the interface for `Client::ProfileDml()`
152 
153  /// Defines the interface for `Client::AnalyzeSql()`
154  virtual StatusOr<ExecutionPlan> AnalyzeSql(SqlParams);
155 
156  /// Defines the interface for `Client::ExecutePartitionedDml()`
159 
160  /// Defines the interface for `Client::PartitionQuery()`
161  virtual StatusOr<std::vector<QueryPartition>> PartitionQuery(
163 
164  /// Defines the interface for `Client::ExecuteBatchDml()`
166 
167  /// Defines the interface for `Client::Commit()`
168  virtual StatusOr<CommitResult> Commit(CommitParams);
169 
170  /// Defines the interface for `Client::Rollback()`
172 };
173 
175 } // namespace spanner
176 } // namespace cloud
177 } // namespace google
178 
179 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_CONNECTION_H