Google Cloud Spanner C++ Client  1.32.1
A C++ Client Library for Google Cloud Spanner
client.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 // http://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_CLIENT_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_CLIENT_H
17 
18 #include "google/cloud/spanner/batch_dml_result.h"
19 #include "google/cloud/spanner/client_options.h"
20 #include "google/cloud/spanner/commit_options.h"
21 #include "google/cloud/spanner/commit_result.h"
22 #include "google/cloud/spanner/connection.h"
23 #include "google/cloud/spanner/connection_options.h"
24 #include "google/cloud/spanner/database.h"
25 #include "google/cloud/spanner/keys.h"
26 #include "google/cloud/spanner/mutations.h"
27 #include "google/cloud/spanner/partition_options.h"
28 #include "google/cloud/spanner/query_options.h"
29 #include "google/cloud/spanner/query_partition.h"
30 #include "google/cloud/spanner/read_options.h"
31 #include "google/cloud/spanner/read_partition.h"
32 #include "google/cloud/spanner/results.h"
33 #include "google/cloud/spanner/retry_policy.h"
34 #include "google/cloud/spanner/session_pool_options.h"
35 #include "google/cloud/spanner/sql_statement.h"
36 #include "google/cloud/spanner/transaction.h"
37 #include "google/cloud/spanner/version.h"
38 #include "google/cloud/backoff_policy.h"
39 #include "google/cloud/optional.h"
40 #include "google/cloud/options.h"
41 #include "google/cloud/status.h"
42 #include "google/cloud/status_or.h"
43 #include <google/spanner/v1/spanner.pb.h>
44 #include <grpcpp/grpcpp.h>
45 #include <functional>
46 #include <memory>
47 #include <string>
48 #include <vector>
49 
50 namespace google {
51 namespace cloud {
52 namespace spanner {
53 inline namespace SPANNER_CLIENT_NS {
54 
55 // clang-format off
56 /**
57  * Performs database client operations on Spanner.
58  *
59  * Applications use this class to perform operations on
60  * [Spanner Databases][spanner-doc-link].
61  *
62  * @par Performance
63  *
64  * `Client` objects are relatively cheap to create, copy, and move. However,
65  * each `Client` object must be created with a `std::shared_ptr<Connection>`,
66  * which itself is relatively expensive to create. Therefore, connection
67  * instances should be shared when possible. See the `MakeConnection()` method
68  * and the `Connection` interface for more details.
69  *
70  * @par Thread Safety
71  *
72  * Instances of this class created via copy-construction or copy-assignment
73  * share the underlying pool of connections. Access to these copies via multiple
74  * threads is guaranteed to work. Two threads operating on the same instance of
75  * this class is not guaranteed to work.
76  *
77  * @par Error Handling
78  *
79  * This class uses `StatusOr<T>` to report errors. When an operation fails to
80  * perform its work the returned `StatusOr<T>` contains the error details. If
81  * the `ok()` member function in the `StatusOr<T>` returns `true` then it
82  * contains the expected result. Please consult the
83  * [`StatusOr<T>` documentation](#google::cloud::v0::StatusOr) for more details.
84  *
85  * @code
86  * namespace spanner = ::google::cloud::spanner;
87  *
88  * auto db = spanner::Database("my_project", "my_instance", "my_db_id"));
89  * auto conn = spanner::MakeConnection(db);
90  * auto client = spanner::Client(conn);
91  *
92  * auto rows = client.Read(...);
93  * using RowType = std::tuple<std::int64_t, std::string>;
94  * for (auto const& row : spanner::StreamOf<RowType>(rows)) {
95  * // ...
96  * }
97  * @endcode
98  *
99  * @par Query Options
100  *
101  * Most operations that take an `SqlStatement` may also be modified with
102  * `QueryOptions`. These options can be set at various levels, with more
103  * specific levels taking precedence over broader ones. For example,
104  * `QueryOptions` that are passed directly to `Client::ExecuteQuery()` will
105  * take precedence over the `Client`-level defaults (if any), which will
106  * themselves take precedence over any environment variables. The following
107  * table shows the environment variables that may optionally be set and the
108  * `QueryOptions` setting that they affect.
109  *
110  * Environment Variable | QueryOptions setting
111  * -------------------------------------- | --------------------
112  * `SPANNER_OPTIMIZER_VERSION` | `QueryOptions::optimizer_version()`
113  * `SPANNER_OPTIMIZER_STATISTICS_PACKAGE` | `QueryOptions::optimizer_statistics_package()`
114  *
115  * @see https://cloud.google.com/spanner/docs/reference/rest/v1/QueryOptions
116  * @see http://cloud/spanner/docs/query-optimizer/manage-query-optimizer
117  *
118  * [spanner-doc-link]:
119  * https://cloud.google.com/spanner/docs/api-libraries-overview
120  */
121 // clang-format on
122 class Client {
123  public:
124  /**
125  * Constructs a `Client` object using the specified @p conn and @p opts.
126  *
127  * See `MakeConnection()` for how to create a connection to Spanner. To help
128  * with unit testing, callers may create fake/mock `Connection` objects that
129  * are injected into the `Client`.
130  */
131  explicit Client(std::shared_ptr<Connection> conn, ClientOptions opts = {})
132  : conn_(std::move(conn)), opts_(std::move(opts)) {}
133 
134  /// No default construction. Use `Client(std::shared_ptr<Connection>)`
135  Client() = delete;
136 
137  //@{
138  // @name Copy and move support
139  Client(Client const&) = default;
140  Client& operator=(Client const&) = default;
141  Client(Client&&) = default;
142  Client& operator=(Client&&) = default;
143  //@}
144 
145  //@{
146  // @name Equality
147  friend bool operator==(Client const& a, Client const& b) {
148  return a.conn_ == b.conn_;
149  }
150  friend bool operator!=(Client const& a, Client const& b) { return !(a == b); }
151  //@}
152 
153  //@{
154  /**
155  * Reads rows from the database using key lookups and scans, as a simple
156  * key/value style alternative to `ExecuteQuery()`.
157  *
158  * Callers can optionally supply a `Transaction` or
159  * `Transaction::SingleUseOptions` used to create a single-use transaction -
160  * or neither, in which case a single-use transaction with default options
161  * is used.
162  *
163  * @param table The name of the table in the database to be read.
164  * @param keys Identifies the rows to be yielded. If `read_options.index_name`
165  * is set, names keys in that index; otherwise names keys in the primary
166  * index of `table`. It is not an error for `keys` to name rows that do
167  * not exist in the database; `Read` yields nothing for nonexistent rows.
168  * @param columns The columns of `table` to be returned for each row matching
169  * this request.
170  * @param read_options `ReadOptions` used for this request.
171  *
172  * @par Example
173  * @snippet samples.cc read-data
174  *
175  * @note No individual row in the `ReadResult` can exceed 100 MiB, and no
176  * column value can exceed 10 MiB.
177  */
178  RowStream Read(std::string table, KeySet keys,
179  std::vector<std::string> columns,
180  ReadOptions read_options = {});
181 
182  /**
183  * @copydoc Read
184  *
185  * @param transaction_options Execute this read in a single-use transaction
186  * with these options.
187  */
188  RowStream Read(Transaction::SingleUseOptions transaction_options,
189  std::string table, KeySet keys,
190  std::vector<std::string> columns,
191  ReadOptions read_options = {});
192 
193  /**
194  * @copydoc Read
195  *
196  * @param transaction Execute this read as part of an existing transaction.
197  */
198  RowStream Read(Transaction transaction, std::string table, KeySet keys,
199  std::vector<std::string> columns,
200  ReadOptions read_options = {});
201  //@}
202 
203  /**
204  * Reads rows from a subset of rows in a database. Requires a prior call
205  * to `PartitionRead` to obtain the partition information; see the
206  * documentation of that method for full details.
207  *
208  * @param partition A `ReadPartition`, obtained by calling `PartitionRead`.
209  *
210  * @note No individual row in the `ReadResult` can exceed 100 MiB, and no
211  * column value can exceed 10 MiB.
212  *
213  * @par Example
214  * @snippet samples.cc read-read-partition
215  */
216  RowStream Read(ReadPartition const& partition);
217 
218  /**
219  * Creates a set of partitions that can be used to execute a read
220  * operation in parallel. Each of the returned partitions can be passed
221  * to `Read` to specify a subset of the read result to read.
222  *
223  * There are no ordering guarantees on rows returned among the returned
224  * partition, or even within each individual `Read` call issued with a given
225  * partition.
226  *
227  * Partitions become invalid when the session used to create them is deleted,
228  * is idle for too long, begins a new transaction, or becomes too old. When
229  * any of these happen, it is not possible to resume the read, and the whole
230  * operation must be restarted from the beginning.
231  *
232  * @param transaction The transaction to execute the operation in.
233  * **Must** be a read-only snapshot transaction.
234  * @param table The name of the table in the database to be read.
235  * @param keys Identifies the rows to be yielded. If `read_options.index_name`
236  * is set, names keys in that index; otherwise names keys in the primary
237  * index of `table`. It is not an error for `keys` to name rows that do
238  * not exist in the database; `Read` yields nothing for nonexistent rows.
239  * @param columns The columns of `table` to be returned for each row matching
240  * this request.
241  * @param read_options `ReadOptions` used for this request.
242  * @param partition_options `PartitionOptions` used for this request.
243  *
244  * @return A `StatusOr` containing a vector of `ReadPartition` or error
245  * status on failure.
246  *
247  * @par Example
248  * @snippet samples.cc partition-read
249  */
250  StatusOr<std::vector<ReadPartition>> PartitionRead(
251  Transaction transaction, std::string table, KeySet keys,
252  std::vector<std::string> columns, ReadOptions read_options = {},
253  PartitionOptions const& partition_options = PartitionOptions{});
254 
255  //@{
256  /**
257  * Executes a SQL query.
258  *
259  * Operations inside read-write transactions might return `ABORTED`. If this
260  * occurs, the application should restart the transaction from the beginning.
261  *
262  * Callers can optionally supply a `Transaction` or
263  * `Transaction::SingleUseOptions` used to create a single-use transaction -
264  * or neither, in which case a single-use transaction with default options
265  * is used.
266  *
267  * `SELECT * ...` queries are supported, but there's no guarantee about the
268  * order, nor number, of returned columns. Therefore, the caller must look up
269  * the wanted values in each row by column name. When the desired column
270  * names are known in advance, it is better to list them explicitly in the
271  * query's SELECT statement, so that unnecessary values are not
272  * returned/ignored, and the column order is known. This enables more
273  * efficient and simpler code.
274  *
275  * @par Example with explicitly selected columns.
276  * @snippet samples.cc spanner-query-data
277  *
278  * @par Example using SELECT *
279  * @snippet samples.cc spanner-query-data-select-star
280  *
281  * @param statement The SQL statement to execute.
282  * @param opts The `QueryOptions` to use for this call. If given, these will
283  * take precedence over the options set at the client and environment
284  * levels.
285  *
286  * @note No individual row in the `RowStream` can exceed 100 MiB, and no
287  * column value can exceed 10 MiB.
288  */
289  RowStream ExecuteQuery(SqlStatement statement, QueryOptions const& opts = {});
290 
291  /**
292  * @copydoc ExecuteQuery(SqlStatement, QueryOptions const&)
293  *
294  * @param transaction_options Execute this query in a single-use transaction
295  * with these options.
296  */
297  RowStream ExecuteQuery(Transaction::SingleUseOptions transaction_options,
298  SqlStatement statement, QueryOptions const& opts = {});
299 
300  /**
301  * @copydoc ExecuteQuery(SqlStatement, QueryOptions const&)
302  *
303  * @param transaction Execute this query as part of an existing transaction.
304  */
305  RowStream ExecuteQuery(Transaction transaction, SqlStatement statement,
306  QueryOptions const& opts = {});
307 
308  /**
309  * Executes a SQL query on a subset of rows in a database. Requires a prior
310  * call to `PartitionQuery` to obtain the partition information; see the
311  * documentation of that method for full details.
312  *
313  * @param partition A `QueryPartition`, obtained by calling `PartitionQuery`.
314  * @param opts The `QueryOptions` to use for this call. If given, these will
315  * take precedence over the options set at the client and environment
316  * levels.
317  *
318  * @note No individual row in the `RowStream` can exceed 100 MiB, and no
319  * column value can exceed 10 MiB.
320  *
321  * @par Example
322  * @snippet samples.cc execute-sql-query-partition
323  */
324  RowStream ExecuteQuery(QueryPartition const& partition,
325  QueryOptions const& opts = {});
326  //@}
327 
328  //@{
329  /**
330  * Profiles a SQL query.
331  *
332  * Profiling executes the query, provides the resulting rows, `ExecutionPlan`,
333  * and execution statistics.
334  *
335  * Operations inside read-write transactions might return `kAborted`. If this
336  * occurs, the application should restart the transaction from the beginning.
337  *
338  * Callers can optionally supply a `Transaction` or
339  * `Transaction::SingleUseOptions` used to create a single-use transaction -
340  * or neither, in which case a single-use transaction with default options
341  * is used.
342  *
343  * @note Callers must consume all rows from the result before execution
344  * statistics and `ExecutionPlan` are available.
345  *
346  * @param statement The SQL statement to execute.
347  * @param opts The `QueryOptions` to use for this call. If given, these will
348  * take precedence over the options set at the client and environment
349  * levels.
350  *
351  * @note No individual row in the `ProfileQueryResult` can exceed 100 MiB, and
352  * no column value can exceed 10 MiB.
353  *
354  * @par Example
355  * @snippet samples.cc profile-query
356  */
358  QueryOptions const& opts = {});
359 
360  /**
361  * @copydoc ProfileQuery(SqlStatement, QueryOptions const&)
362  *
363  * @param transaction_options Execute this query in a single-use transaction
364  * with these options.
365  */
367  Transaction::SingleUseOptions transaction_options, SqlStatement statement,
368  QueryOptions const& opts = {});
369 
370  /**
371  * @copydoc ProfileQuery(SqlStatement, QueryOptions const&)
372  *
373  * @param transaction Execute this query as part of an existing transaction.
374  */
376  SqlStatement statement,
377  QueryOptions const& opts = {});
378  //@}
379 
380  /**
381  * Creates a set of partitions that can be used to execute a query
382  * operation in parallel. Each of the returned partitions can be passed
383  * to `ExecuteQuery` to specify a subset of the query result to read.
384  *
385  * Partitions become invalid when the session used to create them is deleted,
386  * is idle for too long, begins a new transaction, or becomes too old. When
387  * any of these happen, it is not possible to resume the query, and the whole
388  * operation must be restarted from the beginning.
389  *
390  * @param transaction The transaction to execute the operation in.
391  * **Must** be a read-only snapshot transaction.
392  * @param statement The SQL statement to execute.
393  * @param partition_options `PartitionOptions` used for this request.
394  *
395  * @return A `StatusOr` containing a vector of `QueryPartition`s or error
396  * status on failure.
397  *
398  * @par Example
399  * @snippet samples.cc partition-query
400  */
401  StatusOr<std::vector<QueryPartition>> PartitionQuery(
402  Transaction transaction, SqlStatement statement,
403  PartitionOptions const& partition_options = PartitionOptions{});
404 
405  /**
406  * Executes a SQL DML statement.
407  *
408  * Operations inside read-write transactions might return `ABORTED`. If this
409  * occurs, the application should restart the transaction from the beginning.
410  *
411  * @note Single-use transactions are not supported with DML statements.
412  *
413  * @param transaction Execute this query as part of an existing transaction.
414  * @param statement The SQL statement to execute.
415  * @param opts The `QueryOptions` to use for this call. If given, these will
416  * take precedence over the options set at the client and environment
417  * levels.
418  *
419  * @par Example
420  * @snippet samples.cc execute-dml
421  */
422  StatusOr<DmlResult> ExecuteDml(Transaction transaction,
423  SqlStatement statement,
424  QueryOptions const& opts = {});
425 
426  /**
427  * Profiles a SQL DML statement.
428  *
429  * Profiling executes the DML statement, provides the modified row count,
430  * `ExecutionPlan`, and execution statistics.
431  *
432  * Operations inside read-write transactions might return `ABORTED`. If this
433  * occurs, the application should restart the transaction from the beginning.
434  *
435  * @note Single-use transactions are not supported with DML statements.
436  *
437  * @param transaction Execute this query as part of an existing transaction.
438  * @param statement The SQL statement to execute.
439  * @param opts The `QueryOptions` to use for this call. If given, these will
440  * take precedence over the options set at the client and environment
441  * levels.
442  *
443  * @par Example:
444  * @snippet samples.cc profile-dml
445  */
446  StatusOr<ProfileDmlResult> ProfileDml(Transaction transaction,
447  SqlStatement statement,
448  QueryOptions const& opts = {});
449 
450  /**
451  * Analyzes the execution plan of a SQL statement.
452  *
453  * Analyzing provides the `ExecutionPlan`, but does not execute the SQL
454  * statement.
455  *
456  * Operations inside read-write transactions might return `ABORTED`. If this
457  * occurs, the application should restart the transaction from the beginning.
458  *
459  * @note Single-use transactions are not supported with DML statements.
460  *
461  * @param transaction Execute this query as part of an existing transaction.
462  * @param statement The SQL statement to execute.
463  * @param opts The `QueryOptions` to use for this call. If given, these will
464  * take precedence over the options set at the client and environment
465  * levels.
466  *
467  * @par Example:
468  * @snippet samples.cc analyze-query
469  */
470  StatusOr<ExecutionPlan> AnalyzeSql(Transaction transaction,
471  SqlStatement statement,
472  QueryOptions const& opts = {});
473 
474  /**
475  * Executes a batch of SQL DML statements. This method allows many statements
476  * to be run with lower latency than submitting them sequentially with
477  * `ExecuteDml`.
478  *
479  * Statements are executed in order, sequentially. Execution will stop at the
480  * first failed statement; the remaining statements will not run.
481  *
482  * As with all read-write transactions, the results will not be visible
483  * outside of the transaction until it is committed. For that reason, it is
484  * advisable to run this method from a `Commit` mutator.
485  *
486  * @warning A returned status of OK from this function does not imply that
487  * all the statements were executed successfully. For that, you need to
488  * inspect the `BatchDmlResult::status` field.
489  *
490  * @param transaction The read-write transaction to execute the operation in.
491  * @param statements The list of statements to execute in this batch.
492  * Statements are executed serially, such that the effects of statement i
493  * are visible to statement i+1. Each statement must be a DML statement.
494  * Execution will stop at the first failed statement; the remaining
495  * statements will not run. Must not be empty.
496  * @param opts The options to use for this call. Expected options are any
497  * of the types in the following option lists.
498  * - `google::cloud::RequestOptionList`
499  *
500  * @par Example
501  * @snippet samples.cc execute-batch-dml
502  */
503  StatusOr<BatchDmlResult> ExecuteBatchDml(Transaction transaction,
504  std::vector<SqlStatement> statements,
505  Options opts = {});
506 
507  /**
508  * Commits a read-write transaction.
509  *
510  * Calls the @p mutator in the context of a new read-write transaction.
511  * The @p mutator can execute read/write operations using the transaction,
512  * and returns any additional `Mutations` to commit.
513  *
514  * If the @p mutator succeeds and the transaction commits, then `Commit()`
515  * returns the `CommitResult`.
516  *
517  * If the @p mutator returns a non-rerunnable status (according to the
518  * @p rerun_policy), the transaction is rolled back and that status is
519  * returned. Similarly, if the transaction fails to commit with a non-
520  * rerunnable status, that status is returned.
521  *
522  * Otherwise the whole process repeats (subject to @p rerun_policy and
523  * @p backoff_policy), by building a new transaction and re-running the
524  * @p mutator. The lock priority of the operation increases after each
525  * rerun, meaning that the next attempt has a slightly better chance of
526  * success.
527  *
528  * Note that the @p mutator should only return a rerunnable status when
529  * the transaction is no longer usable (e.g., it was aborted). Otherwise
530  * the transaction will be leaked.
531  *
532  * @param mutator the function called to create mutations
533  * @param rerun_policy controls for how long (or how many times) the mutator
534  * will be rerun after the transaction aborts.
535  * @param backoff_policy controls how long `Commit` waits between reruns.
536  * @param options to apply to the commit.
537  *
538  * @throw Rethrows any exception thrown by @p `mutator` (after rolling back
539  * the transaction). However, a `RuntimeStatusError` exception is
540  * instead consumed and converted into a `mutator` return value of the
541  * enclosed `Status`.
542  *
543  * @par Example
544  * @snippet samples.cc commit-with-policies
545  */
546  StatusOr<CommitResult> Commit(
547  std::function<StatusOr<Mutations>(Transaction)> const& mutator,
548  std::unique_ptr<TransactionRerunPolicy> rerun_policy,
549  std::unique_ptr<BackoffPolicy> backoff_policy,
550  CommitOptions const& options = {});
551 
552  /**
553  * Commits a read-write transaction.
554  *
555  * Same as above, but uses the default rerun and backoff policies.
556  *
557  * @param mutator the function called to create mutations
558  * @param options to apply to the commit.
559  *
560  * @par Example
561  * @snippet samples.cc commit-with-mutator
562  */
563  StatusOr<CommitResult> Commit(
564  std::function<StatusOr<Mutations>(Transaction)> const& mutator,
565  CommitOptions const& options = {});
566 
567  /**
568  * Commits the @p mutations, using the @p options, atomically in order.
569  *
570  * This function uses the re-run loop described above with the default
571  * policies.
572  *
573  * @par Example
574  * @snippet samples.cc commit-with-mutations
575  */
576  StatusOr<CommitResult> Commit(Mutations mutations,
577  CommitOptions const& options = {});
578 
579  /**
580  * Commits a read-write transaction.
581  *
582  * The commit might return a `kAborted` error. This can occur at any time.
583  * Commonly the cause is conflicts with concurrent transactions, however
584  * it can also happen for a variety of other reasons. If `Commit` returns
585  * `kAborted`, the caller may try to reapply the mutations within a new
586  * read-write transaction (which should share lock priority with the aborted
587  * transaction so that the new attempt has a slightly better chance of
588  * success).
589  *
590  * @note Prefer the previous `Commit` overloads if you want to simply reapply
591  * mutations after a `kAborted` error.
592  *
593  * @warning It is an error to call `Commit` with a read-only transaction.
594  *
595  * @param transaction The transaction to commit.
596  * @param mutations The mutations to be executed when this transaction
597  * commits. All mutations are applied atomically, in the order they appear
598  * in this list.
599  * @param options to apply to the commit.
600  *
601  * @return A `StatusOr` containing the result of the commit or error status
602  * on failure.
603  */
604  StatusOr<CommitResult> Commit(Transaction transaction, Mutations mutations,
605  CommitOptions const& options = {});
606 
607  /**
608  * Rolls back a read-write transaction, releasing any locks it holds.
609  *
610  * At any time before `Commit`, the client can call `Rollback` to abort the
611  * transaction. It is a good idea to call this for any read-write transaction
612  * that includes one or more `Read`, `ExecuteQuery`, or `ExecuteDml` requests
613  * and ultimately decides not to commit.
614  *
615  * @warning It is an error to call `Rollback` with a read-only transaction.
616  *
617  * @param transaction The transaction to roll back.
618  *
619  * @return The error status of the rollback.
620  */
621  Status Rollback(Transaction transaction);
622 
623  /**
624  * Executes a Partitioned DML SQL query.
625  *
626  * @param statement the SQL statement to execute. Please see the
627  * [spanner documentation][dml-partitioned] for the restrictions on the
628  * SQL statements supported by this function.
629  * @param opts The `QueryOptions` to use for this call. If given, these will
630  * take precedence over the options set at the client and environment
631  * levels.
632  *
633  * @par Example
634  * @snippet samples.cc execute-sql-partitioned
635  *
636  * @see [Partitioned DML Transactions][txn-partitioned] for an overview of
637  * Partitioned DML transactions.
638  * @see [Partitioned DML][dml-partitioned] for a description of which SQL
639  * statements are supported in Partitioned DML transactions.
640  * [txn-partitioned]:
641  * https://cloud.google.com/spanner/docs/transactions#partitioned_dml_transactions
642  * [dml-partitioned]: https://cloud.google.com/spanner/docs/dml-partitioned
643  */
645  SqlStatement statement, QueryOptions const& opts = {});
646 
647  private:
648  QueryOptions OverlayQueryOptions(QueryOptions const&);
649 
650  std::shared_ptr<Connection> conn_;
651  ClientOptions opts_;
652 };
653 
654 /**
655  * Returns a Connection object that can be used for interacting with Spanner.
656  *
657  * The returned connection object should not be used directly; instead it
658  * should be given to a `Client` instance, and methods should be invoked on
659  * `Client`.
660  *
661  * The optional @p opts argument may be used to configure aspects of the
662  * returned `Connection`. Expected options are any of the types in the
663  * following option lists.
664  *
665  * - `google::cloud::CommonOptionList`
666  * - `google::cloud::GrpcOptionList`
667  * - `google::cloud::spanner::SpannerPolicyOptionList`
668  * - `google::cloud::spanner::SessionPoolOptionList`
669  *
670  * @note Unrecognized options will be ignored. To debug issues with options set
671  * `GOOGLE_CLOUD_CPP_ENABLE_CLOG=yes` in the environment and unexpected
672  * options will be logged.
673  *
674  * @see `Connection`
675  *
676  * @param db See `Database`.
677  * @param opts (optional) configure the `Connection` created by
678  * this function.
679  */
680 std::shared_ptr<spanner::Connection> MakeConnection(spanner::Database const& db,
681  Options opts = {});
682 
683 /**
684  * Returns a Connection object that can be used for interacting with Spanner.
685  *
686  * The returned connection object should not be used directly, rather it should
687  * be given to a `Client` instance, and methods should be invoked on `Client`.
688  *
689  * @note Prefer using the `MakeConnection()` overload that accepts
690  * `google::cloud::Options`.
691  *
692  * @see `Connection`
693  *
694  * @param db See `Database`.
695  * @param connection_options configure the `Connection` created by this
696  * function.
697  * @param session_pool_options (optional) configure the `SessionPool` created
698  * by the `Connection`.
699  */
700 std::shared_ptr<Connection> MakeConnection(
701  Database const& db, ConnectionOptions const& connection_options,
702  SessionPoolOptions session_pool_options = SessionPoolOptions());
703 
704 /**
705  * @copydoc MakeConnection(Database const&, ConnectionOptions const&, SessionPoolOptions)
706  *
707  * @note Prefer using the `MakeConnection()` overload that accepts
708  * `google::cloud::Options`.
709  *
710  * @param retry_policy override the default `RetryPolicy`, controls how long
711  * the returned `Connection` object retries requests on transient
712  * failures.
713  * @param backoff_policy override the default `BackoffPolicy`, controls how
714  * long the `Connection` object waits before retrying a failed request.
715  *
716  * @par Example
717  * @snippet samples.cc custom-retry-policy
718  */
719 std::shared_ptr<Connection> MakeConnection(
720  Database const& db, ConnectionOptions const& connection_options,
721  SessionPoolOptions session_pool_options,
722  std::unique_ptr<RetryPolicy> retry_policy,
723  std::unique_ptr<BackoffPolicy> backoff_policy);
724 
725 } // namespace SPANNER_CLIENT_NS
726 } // namespace spanner
727 
728 namespace spanner_internal {
729 inline namespace SPANNER_CLIENT_NS {
730 
731 spanner::QueryOptions OverlayQueryOptions(
732  spanner::QueryOptions const& preferred,
733  spanner::QueryOptions const& fallback,
734  absl::optional<std::string> const& optimizer_version_env,
735  absl::optional<std::string> const& optimizer_statistics_package_env);
736 
737 } // namespace SPANNER_CLIENT_NS
738 } // namespace spanner_internal
739 } // namespace cloud
740 } // namespace google
741 
742 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_CLIENT_H