MySQL Connector/C++
MySQL connector library for C and C++ applications
xapi.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2016, 2020, Oracle and/or its affiliates.
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License, version 2.0, as
6 * published by the Free Software Foundation.
7 *
8 * This program is also distributed with certain software (including
9 * but not limited to OpenSSL) that is licensed under separate terms,
10 * as designated in a particular file or component or in included license
11 * documentation. The authors of MySQL hereby grant you an
12 * additional permission to link the program and your derivative works
13 * with the separately licensed software that they have included with
14 * MySQL.
15 *
16 * Without limiting anything contained in the foregoing, this file,
17 * which is part of MySQL Connector/C++, is also subject to the
18 * Universal FOSS Exception, version 1.0, a copy of which can be found at
19 * http://oss.oracle.com/licenses/universal-foss-exception.
20 *
21 * This program is distributed in the hope that it will be useful, but
22 * WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
24 * See the GNU General Public License, version 2.0, for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with this program; if not, write to the Free Software Foundation, Inc.,
28 * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
29 */
30
71#ifndef MYSQL_XAPI_H
72#define MYSQL_XAPI_H
73
74
75#ifdef __cplusplus
76extern "C" {
77#endif
78
79
80#include "common_constants.h"
81#include "common/api.h"
82
83#include <stdlib.h>
84#include <stdint.h>
85#include <stdbool.h>
86
93// FIXME
94#define STDCALL
95
97
98typedef char object_id[16];
99typedef object_id* MYSQLX_GUID;
100
103#define RESULT_OK 0
104
111#define RESULT_MORE_DATA 8
112
119#define RESULT_NULL 16
120
126#define RESULT_INFO 32
127
130#define RESULT_WARNING 64
131
134#define RESULT_ERROR 128
135
136
137#define MYSQLX_MAX_ERROR_LEN 255
138#define MYSQLX_NULL_TERMINATED 0xFFFFFFFF
139
140#define MYSQLX_ERR_UNKNOWN 0xFFFF
141
142#define MYSQLX_COLLATION_UNDEFINED 0
143
144
145/*
146 Error codes
147*/
148
149#define MYSQLX_ERROR_INDEX_OUT_OF_RANGE 1
150
151/*
152 Error messages
153*/
154
155#define MYSQLX_ERROR_INDEX_OUT_OF_RANGE_MSG "Index is out of range"
156#define MYSQLX_ERROR_MISSING_SCHEMA_NAME_MSG "Missing schema name"
157#define MYSQLX_ERROR_MISSING_TABLE_NAME_MSG "Missing table name"
158#define MYSQLX_ERROR_MISSING_VIEW_NAME_MSG "Missing view name"
159#define MYSQLX_ERROR_MISSING_COLLECTION_NAME_MSG "Missing collection name"
160#define MYSQLX_ERROR_MISSING_COLLECTION_OPT_MSG "Missing collection options"
161#define MYSQLX_ERROR_MISSING_VIEW_NAME_MSG "Missing view name"
162#define MYSQLX_ERROR_MISSING_KEY_NAME_MSG "Missing key name"
163#define MYSQLX_ERROR_MISSING_HOST_NAME "Missing host name"
164#define MYSQLX_ERROR_MISSING_SOCKET_NAME "Missing socket name"
165#define MYSQLX_ERROR_MISSING_CONN_INFO "Missing connecting information"
166#define MYSQLX_ERROR_HANDLE_NULL_MSG "Handle cannot be NULL"
167#define MYSQLX_ERROR_VIEW_INVALID_STMT_TYPE "Invalid statement type for View. Only SELECT type is supported"
168#define MYSQLX_ERROR_VIEW_TYPE_MSG "Statement must be of VIEW type"
169#define MYSQLX_ERROR_OUTPUT_BUFFER_NULL "The output buffer cannot be NULL"
170#define MYSQLX_ERROR_OUTPUT_BUFFER_ZERO "The output buffer cannot have zero length"
171#define MYSQLX_ERROR_OUTPUT_VARIABLE_NULL "The output variable cannot be NULL"
172#define MYSQLX_ERROR_OP_NOT_SUPPORTED "The operation is not supported by the function"
173#define MYSQLX_ERROR_WRONG_SSL_MODE "Wrong value for SSL Mode"
174#define MYSQLX_ERROR_NO_TLS_SUPPORT "Can not create TLS session - this connector is built without TLS support"
175#define MYSQLX_ERROR_MIX_PRIORITY "Mixing hosts with and without priority is not allowed"
176#define MYSQLX_ERROR_DUPLICATED_OPTION "Option already defined"
177#define MYSQLX_ERROR_MAX_PRIORITY "Priority should be a value between 0 and 100"
178#define MYSQLX_ERROR_AUTH_METHOD "Unknown authentication method"
179#define MYSQLX_ERROR_ROW_LOCKING "Row locking is supported only for SELECT and FIND"
180#define MYSQLX_ERROR_WRONG_LOCKING_MODE "Wrong value for the row locking mode"
181#define MYSQLX_ERROR_WRONG_EXPRESSION "Expression could not be parsed"
182#define MYSQLX_ERROR_EMPTY_JSON "Empty JSON document string"
183
184
185/* Opaque structures*/
186
196typedef struct mysqlx_error_struct mysqlx_error_t;
197
198
205typedef struct mysqlx_session_struct mysqlx_session_t;
206
213typedef struct mysqlx_client_struct mysqlx_client_t;
214
215
227typedef struct mysqlx_session_options_struct mysqlx_session_options_t;
228
236typedef struct mysqlx_collection_options_struct mysqlx_collection_options_t;
237
244typedef struct mysqlx_schema_struct mysqlx_schema_t;
245
246
253typedef struct mysqlx_collection_struct mysqlx_collection_t;
254
255
261typedef struct mysqlx_table_struct mysqlx_table_t;
262
263
277typedef struct mysqlx_stmt_struct mysqlx_stmt_t;
278
279typedef struct Mysqlx_diag_base mysqlx_object_t;
280
281
288typedef struct mysqlx_row_struct mysqlx_row_t;
289
290
301typedef struct mysqlx_result_struct mysqlx_result_t;
302
303
308typedef enum mysqlx_data_type_enum
309{
310 MYSQLX_TYPE_UNDEFINED = 0,
311
312 /* Column types as defined in protobuf (mysqlx_resultset.proto)*/
325 /* Column types from DevAPI (no number constants assigned, just names)*/
333 MYSQLX_TYPE_EXPR = 101
335
336#define PARAM_SINT(A) (void*)MYSQLX_TYPE_SINT, (int64_t)A
337#define PARAM_UINT(A) (void*)MYSQLX_TYPE_UINT, (uint64_t)A
338#define PARAM_FLOAT(A) (void*)MYSQLX_TYPE_FLOAT, (double)A
339#define PARAM_DOUBLE(A) (void*)MYSQLX_TYPE_DOUBLE, (double)A
340#define PARAM_BYTES(DATA, SIZE) (void*)MYSQLX_TYPE_BYTES, (void*)DATA, (size_t)SIZE
341#define PARAM_STRING(A) (void*)MYSQLX_TYPE_STRING, A
342#define PARAM_EXPR(A) (void*)MYSQLX_TYPE_EXPR, A
343#define PARAM_NULL() (void*)MYSQLX_TYPE_NULL
344
345#define PARAM_END (void*)0
346
347
352typedef enum mysqlx_sort_direction_enum
353{
355 SORT_ORDER_DESC = 2
357
358
359#define PARAM_SORT_ASC(A) A, SORT_ORDER_ASC
360#define PARAM_SORT_DESC(A) A, SORT_ORDER_DESC
361
368typedef enum mysqlx_client_opt_type_enum
369{
370
371#define XAPI_CLIENT_OPT_ENUM_str(X,N) MYSQLX_CLIENT_OPT_##X = -N,
372#define XAPI_CLIENT_OPT_ENUM_bool(X,N) MYSQLX_CLIENT_OPT_##X = -N,
373#define XAPI_CLIENT_OPT_ENUM_num(X,N) MYSQLX_CLIENT_OPT_##X = -N,
374#define XAPI_CLIENT_OPT_ENUM_any(X,N) MYSQLX_CLIENT_OPT_##X = -N,
375
376 CLIENT_OPTION_LIST(XAPI_CLIENT_OPT_ENUM)
377}
379
380#define OPT_POOLING(A) MYSQLX_CLIENT_OPT_POOLING, (int)(bool)(A)
381#define OPT_POOL_MAX_SIZE(A) MYSQLX_CLIENT_OPT_POOL_MAX_SIZE, (uint64_t)(A)
382#define OPT_POOL_QUEUE_TIMEOUT(A) MYSQLX_CLIENT_OPT_POOL_QUEUE_TIMEOUT, (uint64_t)(A)
383#define OPT_POOL_MAX_IDLE_TIME(A) MYSQLX_CLIENT_OPT_POOL_MAX_IDLE_TIME, (uint64_t)(A)
384
397typedef enum mysqlx_opt_type_enum
398{
399
400#define XAPI_OPT_ENUM_str(X,N) MYSQLX_OPT_##X = N,
401#define XAPI_OPT_ENUM_num(X,N) MYSQLX_OPT_##X = N,
402#define XAPI_OPT_ENUM_any(X,N) MYSQLX_OPT_##X = N,
403#define XAPI_OPT_ENUM_bool(X,N) MYSQLX_OPT_##X = N,
404
405 SESSION_OPTION_LIST(XAPI_OPT_ENUM)
406 MYSQLX_OPT_LAST
407}
409
410#define OPT_HOST(A) MYSQLX_OPT_HOST, (A)
411#define OPT_PORT(A) MYSQLX_OPT_PORT, (unsigned int)(A)
412#ifndef _WIN32
413#define OPT_SOCKET(A) MYSQLX_OPT_SOCKET, (A)
414#endif //_WIN32
415#define OPT_DNS_SRV(A) MYSQLX_OPT_DNS_SRV, (A)
416#define OPT_USER(A) MYSQLX_OPT_USER, (A)
417#define OPT_PWD(A) MYSQLX_OPT_PWD, (A)
418#define OPT_DB(A) MYSQLX_OPT_DB, (A)
419#define OPT_SSL_MODE(A) MYSQLX_OPT_SSL_MODE, (A)
420#define OPT_SSL_CA(A) MYSQLX_OPT_SSL_CA, (A)
421#define OPT_SSL_CAPATH(A) MYSQLX_OPT_SSL_CAPATH, (A)
422#define OPT_SSL_CRL(A) MYSQLX_OPT_SSL_CRL, (A)
423#define OPT_SSL_CRLPATH(A) MYSQLX_OPT_SSL_CRLPATH, (A)
424#define OPT_PRIORITY(A) MYSQLX_OPT_PRIORITY, (unsigned int)(A)
425#define OPT_AUTH(A) MYSQLX_OPT_AUTH, (unsigned int)(A)
426#define OPT_CONNECT_TIMEOUT(A) MYSQLX_OPT_CONNECT_TIMEOUT, (unsigned int)(A)
427#define OPT_CONNECTION_ATTRIBUTES(A) MYSQLX_OPT_CONNECTION_ATTRIBUTES, (A)
428#define OPT_TLS_VERSIONS(A) MYSQLX_OPT_TLS_VERSIONS, (A)
429#define OPT_TLS_CIPHERSUITES(A) MYSQLX_OPT_TLS_CIPHERSUITES, (A)
430#define OPT_COMPRESSION(A) MYSQLX_OPT_COMPRESSION, (unsigned int)(A)
431#define OPT_COMPRESSION_ALGORITHMS(A) MYSQLX_OPT_COMPRESSION_ALGORITHMS, (const char*)(A)
432
433
440typedef enum mysqlx_ssl_mode_enum
441{
442#define XAPI_SSL_MODE_ENUM(X,N) SSL_MODE_##X = N,
443
444 SSL_MODE_LIST(XAPI_SSL_MODE_ENUM)
445}
447
454typedef enum mysqlx_auth_method_enum
455{
456#define XAPI_AUTH_ENUM(X,N) MYSQLX_AUTH_##X = N,
458 AUTH_METHOD_LIST(XAPI_AUTH_ENUM)
459}
461
468typedef enum mysqlx_collection_opt_enum
469{
470
471#define XAPI_COLLECTION_OPT_ENUM(X,N) MYSQLX_OPT_COLLECTION_##X = N,
472
473 COLLECTION_OPTIONS_OPTION(XAPI_COLLECTION_OPT_ENUM)
474 MYSQLX_OPT_COLLECTION_LAST
475}
477
484typedef enum mysqlx_collection_validation_opt_enum
485{
487#define XAPI_COLLECTION_VALIDATION_OPT_ENUM(X,N) MYSQLX_OPT_COLLECTION_VALIDATION_##X = 1024+N,
488
489 COLLECTION_VALIDATION_OPTION(XAPI_COLLECTION_VALIDATION_OPT_ENUM)
490 MYSQLX_OPT_COLLECTION_VALIDATION_LAST
491}
493
499typedef enum mysqlx_collection_validation_level_enum
501
502#define XAPI_COLLECTION_VALIDATION_LEVEL_ENUM(X,N) MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_##X = 2048+N,
503
504 COLLECTION_VALIDATION_LEVEL(XAPI_COLLECTION_VALIDATION_LEVEL_ENUM)
505 MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_LAST
506}
508
509#define VALIDATION_OFF MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_OFF
510#define VALIDATION_STRICT MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL_STRICT
511
512#define OPT_COLLECTION_REUSE(X) MYSQLX_OPT_COLLECTION_REUSE, (unsigned int)X
513#define OPT_COLLECTION_VALIDATION(X) MYSQLX_OPT_COLLECTION_VALIDATION, (const char*)X
514#define OPT_COLLECTION_VALIDATION_LEVEL(X) MYSQLX_OPT_COLLECTION_VALIDATION_LEVEL, (unsigned int)X
515#define OPT_COLLECTION_VALIDATION_SCHEMA(X) MYSQLX_OPT_COLLECTION_VALIDATION_SCHEMA, (const char*)X
517typedef enum mysqlx_compression_mode_enum
518{
519#define XAPI_COMPRESSION_ENUM(X,N) MYSQLX_COMPRESSION_##X = N,
520
521 COMPRESSION_MODE_LIST(XAPI_COMPRESSION_ENUM)
522}
530typedef enum mysqlx_row_locking_enum
531{
532#define XAPI_ROW_LOCK_ENUM(X,N) ROW_LOCK_##X = N,
533
534 ROW_LOCK_NONE = 0,
535 LOCK_MODE_LIST(XAPI_ROW_LOCK_ENUM)
536}
538
544typedef enum mysqlx_lock_contention_enum
545{
546#define XAPI_LOCK_CONTENTION_ENUM(X,N) LOCK_CONTENTION_##X = N,
547
548 LOCK_CONTENTION_LIST(XAPI_LOCK_CONTENTION_ENUM)
549}
551
552/*
553 ====================================================================
554 Client operations
555 ====================================================================
556*/
557
620PUBLIC_API mysqlx_client_t *
621mysqlx_get_client_from_url(const char *conn_string, const char *client_opts,
622 mysqlx_error_t **error);
623
624
673PUBLIC_API mysqlx_client_t *
675 mysqlx_error_t **error);
676
694PUBLIC_API void mysqlx_client_close(mysqlx_client_t *client);
695
696/*
697 ====================================================================
698 Session operations
699 ====================================================================
700*/
701
713PUBLIC_API mysqlx_session_t *
715 mysqlx_error_t **error);
716
741PUBLIC_API mysqlx_session_t *
742mysqlx_get_session(const char *host, int port, const char *user,
743 const char *password, const char *database,
744 mysqlx_error_t **error);
745
746
828PUBLIC_API mysqlx_session_t *
829mysqlx_get_session_from_url(const char *conn_string,
830 mysqlx_error_t **error);
831
851PUBLIC_API mysqlx_session_t *
853 mysqlx_error_t **error);
854
855
856
872PUBLIC_API void mysqlx_session_close(mysqlx_session_t *session);
873
874
892PUBLIC_API int mysqlx_session_valid(mysqlx_session_t *sess);
893
913PUBLIC_API mysqlx_result_t *
914mysqlx_get_schemas(mysqlx_session_t *sess, const char *schema_pattern);
915
916
936PUBLIC_API mysqlx_schema_t *
937mysqlx_get_schema(mysqlx_session_t *sess, const char *schema_name,
938 unsigned int check);
939
940
968PUBLIC_API mysqlx_result_t *
970 const char *table_pattern,
971 int get_views);
972
973
993PUBLIC_API mysqlx_table_t *
994mysqlx_get_table(mysqlx_schema_t *schema, const char *tab_name,
995 unsigned int check);
996
997
1018PUBLIC_API mysqlx_result_t *
1020 const char *col_pattern);
1021
1022
1042PUBLIC_API mysqlx_collection_t *
1043mysqlx_get_collection(mysqlx_schema_t *schema, const char *col_name,
1044 unsigned int check);
1045
1046
1062PUBLIC_API int
1064
1065
1080PUBLIC_API int
1082
1083
1098PUBLIC_API int
1100
1101
1119PUBLIC_API const char*
1120mysqlx_savepoint_set( mysqlx_session_t *sess, const char *name);
1121
1122
1136PUBLIC_API int
1137mysqlx_savepoint_release(mysqlx_session_t *sess, const char *name);
1138
1139
1153PUBLIC_API int
1154mysqlx_rollback_to( mysqlx_session_t *sess, const char *name);
1155
1156
1169
1170
1182PUBLIC_API void mysqlx_free_options(mysqlx_session_options_t *opt);
1183
1184
1213PUBLIC_API int
1215
1216
1244PUBLIC_API int
1246 ...);
1247
1248/*
1249 ====================================================================
1250 SQL execution
1251 ====================================================================
1252*/
1253
1271 const char *query,
1272 size_t query_len);
1273
1274
1307 const char *query,
1308 size_t query_len, ...);
1309
1310
1336PUBLIC_API mysqlx_stmt_t *
1337mysqlx_sql_new(mysqlx_session_t *sess, const char *query,
1338 uint32_t length);
1339
1340
1341/*
1342 ====================================================================
1343 Collection operations
1344 ====================================================================
1345*/
1346
1359PUBLIC_API int
1360mysqlx_collection_count(mysqlx_collection_t *collection, uint64_t *count);
1361
1362
1378PUBLIC_API mysqlx_result_t *
1379mysqlx_collection_find(mysqlx_collection_t *collection, const char *criteria);
1380
1381
1414PUBLIC_API mysqlx_result_t *
1416
1417
1432PUBLIC_API mysqlx_result_t *
1433mysqlx_collection_remove(mysqlx_collection_t *collection, const char*criteria);
1434
1435
1468PUBLIC_API mysqlx_result_t *
1470 const char *criteria, ...);
1471
1472
1489PUBLIC_API mysqlx_result_t *
1491 const char *criteria, ...);
1492
1493
1511PUBLIC_API mysqlx_result_t *
1513 const char *criteria,
1514 const char *patch_spec);
1515
1516
1530PUBLIC_API int
1532 const char *patch_spec);
1533
1534/*
1535 Deferred statement execution
1536 ----------------------------
1537*/
1538
1555PUBLIC_API mysqlx_stmt_t *
1557
1558
1579PUBLIC_API int mysqlx_set_find_projection(mysqlx_stmt_t *stmt, const char *proj);
1580
1581
1590#define mysqlx_set_find_criteria mysqlx_set_where
1591
1592
1593/*
1594A macro defining a function for setting HAVING for FIND operation.
1595
1596@see mysqlx_set_having()
1597@ingroup xapi_tbl
1598*/
1599
1600#define mysqlx_set_find_having mysqlx_set_having
1601
1610#define mysqlx_set_find_group_by mysqlx_set_group_by
1611
1620#define mysqlx_set_find_limit_and_offset(STMT, LIM, OFFS) mysqlx_set_limit_and_offset(STMT, LIM, OFFS)
1621
1630#define mysqlx_set_find_order_by mysqlx_set_order_by
1631
1632
1641#define mysqlx_set_find_row_locking mysqlx_set_row_locking
1642
1643
1661PUBLIC_API mysqlx_stmt_t *
1663
1664
1690PUBLIC_API int
1691mysqlx_set_add_document(mysqlx_stmt_t *stmt, const char *json_doc);
1692
1693
1710PUBLIC_API mysqlx_stmt_t *
1712
1721#define mysqlx_set_remove_criteria mysqlx_set_where
1722
1731#define mysqlx_set_remove_order_by mysqlx_set_order_by
1732
1741#define mysqlx_set_remove_limit_and_offset mysqlx_set_limit_and_offset
1742
1743
1761PUBLIC_API mysqlx_stmt_t *
1763
1764
1787PUBLIC_API int
1789
1790
1804PUBLIC_API int
1806
1807
1827PUBLIC_API int
1829
1830
1850PUBLIC_API int
1852
1853
1866PUBLIC_API int mysqlx_set_modify_array_delete(mysqlx_stmt_t *stmt, ...);
1867
1876#define mysqlx_set_modify_criteria mysqlx_set_where
1877
1878
1879/*
1880 ====================================================================
1881 Table operations
1882 ====================================================================
1883*/
1884
1885
1898PUBLIC_API int
1899mysqlx_table_count(mysqlx_table_t *table, uint64_t *count);
1900
1901
1918PUBLIC_API mysqlx_result_t *
1919mysqlx_table_select(mysqlx_table_t *table, const char *criteria);
1920
1921
1949PUBLIC_API mysqlx_result_t *
1950mysqlx_table_select_limit(mysqlx_table_t *table, const char *criteria,
1951 uint64_t row_count, uint64_t offset, ...);
1952
1953
1978PUBLIC_API mysqlx_result_t *
1980
1981
1996PUBLIC_API mysqlx_result_t *
1997mysqlx_table_delete(mysqlx_table_t *table, const char *criteria);
1998
1999
2000
2026PUBLIC_API mysqlx_result_t *
2028 const char *criteria,
2029 ...);
2030
2031
2032/*
2033 Deferred statement execution
2034 ----------------------------
2035*/
2036
2056PUBLIC_API mysqlx_stmt_t *
2058
2067#define mysqlx_set_select_items mysqlx_set_items
2068
2077#define mysqlx_set_select_where mysqlx_set_where
2078
2079
2088#define mysqlx_set_select_order_by mysqlx_set_order_by
2089
2090
2091/*
2092 A macro defining a function for setting HAVING for SELECT operation.
2093
2094 @see mysqlx_set_having()
2095 @ingroup xapi_tbl
2096*/
2097
2098#define mysqlx_set_select_having mysqlx_set_having
2099
2108#define mysqlx_set_select_group_by mysqlx_set_group_by
2109
2118#define mysqlx_set_select_limit_and_offset mysqlx_set_limit_and_offset
2119
2120
2129#define mysqlx_set_select_row_locking mysqlx_set_row_locking
2130
2131
2149PUBLIC_API mysqlx_stmt_t *
2151
2152
2174PUBLIC_API int
2176
2177
2201PUBLIC_API int
2203
2204
2224PUBLIC_API mysqlx_stmt_t *
2226
2235#define mysqlx_set_delete_where mysqlx_set_where
2244#define mysqlx_set_delete_limit(STMT, LIM) mysqlx_set_limit_and_offset(STMT, LIM, 0)
2253#define mysqlx_set_delete_order_by mysqlx_set_order_by
2254
2255
2276PUBLIC_API mysqlx_stmt_t *
2278
2279
2308PUBLIC_API int mysqlx_set_update_values(mysqlx_stmt_t *stmt, ...);
2309
2318#define mysqlx_set_update_where mysqlx_set_where
2319
2328#define mysqlx_set_update_limit(STMT, LIM) mysqlx_set_limit_and_offset(STMT, LIM, 0)
2329
2330
2339#define mysqlx_set_update_order_by mysqlx_set_order_by
2340
2341
2342/*
2343 ====================================================================
2344 Statement execution
2345 ====================================================================
2346*/
2347
2370PUBLIC_API mysqlx_result_t *
2372
2373
2418PUBLIC_API int mysqlx_stmt_bind(mysqlx_stmt_t *stmt, ...);
2419
2420
2443PUBLIC_API int mysqlx_set_items(mysqlx_stmt_t *stmt, ...);
2444
2445
2474PUBLIC_API int mysqlx_set_where(mysqlx_stmt_t *stmt, const char *where_expr);
2475
2476
2505PUBLIC_API int mysqlx_set_having(mysqlx_stmt_t *stmt, const char *having_expr);
2506
2507
2534PUBLIC_API int mysqlx_set_group_by(mysqlx_stmt_t *stmt, ...);
2535
2567PUBLIC_API int mysqlx_set_order_by(mysqlx_stmt_t *stmt, ...);
2568
2569
2602PUBLIC_API int
2603mysqlx_set_limit_and_offset(mysqlx_stmt_t *stmt, uint64_t row_count,
2604 uint64_t offset);
2605
2636PUBLIC_API int
2637mysqlx_set_row_locking(mysqlx_stmt_t *stmt, int locking, int contention);
2638
2664PUBLIC_API void mysqlx_free(void *obj);
2665
2666
2667/*
2668 ====================================================================
2669 Result handling
2670 ====================================================================
2671*/
2672
2690
2691
2709PUBLIC_API const char * mysqlx_json_fetch_one(mysqlx_result_t *res, size_t *out_length);
2710
2711
2730PUBLIC_API int mysqlx_next_result(mysqlx_result_t *res);
2731
2732
2746PUBLIC_API uint64_t
2748
2749
2777PUBLIC_API int
2778mysqlx_store_result(mysqlx_result_t *result, size_t *num);
2779
2780
2798PUBLIC_API int
2799mysqlx_get_count(mysqlx_result_t *result, size_t *num);
2800
2801
2825PUBLIC_API const char *
2827
2828
2843PUBLIC_API uint64_t
2845
2846
2895PUBLIC_API int
2896mysqlx_get_bytes(mysqlx_row_t* row, uint32_t col,
2897 uint64_t offset, void *buf, size_t *buf_len);
2898
2899
2918PUBLIC_API int
2919mysqlx_get_uint(mysqlx_row_t* row, uint32_t col, uint64_t* val);
2920
2921
2940PUBLIC_API int
2941mysqlx_get_sint(mysqlx_row_t* row, uint32_t col, int64_t* val);
2942
2943
2962PUBLIC_API int
2963mysqlx_get_float(mysqlx_row_t* row, uint32_t col, float* val);
2964
2965
2984PUBLIC_API int
2985mysqlx_get_double(mysqlx_row_t* row, uint32_t col, double *val);
2986
2987
3001PUBLIC_API void mysqlx_result_free(mysqlx_result_t *res);
3002
3003
3004/*
3005 Result metadata
3006 ---------------
3007*/
3008
3020PUBLIC_API uint16_t
3021mysqlx_column_get_type(mysqlx_result_t *res, uint32_t pos);
3022
3023
3037PUBLIC_API uint16_t
3039
3040
3059PUBLIC_API uint32_t
3060mysqlx_column_get_length(mysqlx_result_t *res, uint32_t pos);
3061
3062
3074PUBLIC_API uint16_t
3076
3077
3078/*
3079 Get column flags.
3080
3081 @param res result handle
3082 @param pos zero-based column number
3083
3084 @return 32-bit unsigned integer containing column flags reported by
3085 server. TODO: Document these
3086
3087 @ingroup xapi_md
3088*/
3089//PUBLIC_API uint32_t
3090//mysqlx_column_get_flags(mysqlx_result_t *res, uint32_t pos);
3091
3092
3107PUBLIC_API uint32_t
3109
3110
3122PUBLIC_API const char *
3123mysqlx_column_get_name(mysqlx_result_t *res, uint32_t pos);
3124
3125
3137PUBLIC_API const char *
3139
3140
3152PUBLIC_API const char *
3153mysqlx_column_get_table(mysqlx_result_t *res, uint32_t pos);
3154
3155
3167PUBLIC_API const char *
3169
3170
3182PUBLIC_API const char *
3183mysqlx_column_get_schema(mysqlx_result_t *res, uint32_t pos);
3184
3185
3197PUBLIC_API const char *
3198mysqlx_column_get_catalog(mysqlx_result_t *res, uint32_t pos);
3199
3200
3201/*
3202 ====================================================================
3203 DDL statements
3204 ====================================================================
3205*/
3206
3220PUBLIC_API int
3221mysqlx_schema_create(mysqlx_session_t *sess, const char *schema);
3222
3223
3237PUBLIC_API int
3238mysqlx_schema_drop(mysqlx_session_t *sess, const char *schema);
3239
3240
3254PUBLIC_API int
3255mysqlx_collection_create(mysqlx_schema_t *schema, const char *collection);
3256
3257
3269PUBLIC_API mysqlx_collection_options_t *
3271
3272
3302PUBLIC_API int
3304
3305
3320PUBLIC_API int
3322 const char *collection,
3324
3372PUBLIC_API int
3374 const char *collection,
3375 const char* json_options);
3376
3377PUBLIC_API int
3378mysqlx_collection_modify_with_options(mysqlx_schema_t *schema,
3379 const char *collection,
3381
3382PUBLIC_API int
3383mysqlx_collection_modify_with_json_options(mysqlx_schema_t *schema,
3384 const char* collection,
3385 const char* json_options);
3386
3387
3388
3402PUBLIC_API int
3403mysqlx_collection_drop(mysqlx_schema_t *schema, const char *collection);
3404
3405
3406/*
3407 ====================================================================
3408 Diagnostics
3409 ====================================================================
3410*/
3411
3412
3427PUBLIC_API mysqlx_error_t * mysqlx_error(void *obj);
3428
3429
3444PUBLIC_API const char * mysqlx_error_message(void *obj);
3445
3446
3461PUBLIC_API unsigned int mysqlx_error_num(void *obj);
3462
3463
3473PUBLIC_API unsigned int mysqlx_result_warning_count(mysqlx_result_t *res);
3474
3475
3493PUBLIC_API mysqlx_error_t *
3495
3496
3517PUBLIC_API int
3519 const char *idx_spec);
3520
3539PUBLIC_API int
3540mysqlx_collection_drop_index(mysqlx_collection_t *coll, const char *name);
3541
3542
3543#ifdef __cplusplus
3544}
3545#endif
3546
3549#endif /* __MYSQLX_H__*/
int mysqlx_table_count(mysqlx_table_t *table, uint64_t *count)
Return a number of rows in a table.
int mysqlx_set_modify_array_append(mysqlx_stmt_t *stmt,...)
Append to array fields in a document.
mysqlx_stmt_t * mysqlx_collection_find_new(mysqlx_collection_t *collection)
Create a statement which finds documents in a collection.
int mysqlx_set_modify_patch(mysqlx_stmt_t *stmt, const char *patch_spec)
Set a given patch for a modify statement to be applied to documents in a collection after executing t...
mysqlx_result_t * mysqlx_collection_find(mysqlx_collection_t *collection, const char *criteria)
Execute a collection FIND statement with a specific find criteria.
mysqlx_result_t * mysqlx_collection_remove(mysqlx_collection_t *collection, const char *criteria)
Remove documents from a collection.
int mysqlx_set_modify_unset(mysqlx_stmt_t *stmt,...)
Unset fields in a document.
int mysqlx_collection_count(mysqlx_collection_t *collection, uint64_t *count)
Return a number of documents in a collection.
int mysqlx_set_modify_array_insert(mysqlx_stmt_t *stmt,...)
Insert elements into array fields in a document.
int mysqlx_set_modify_array_delete(mysqlx_stmt_t *stmt,...)
Delete elements from array fields in a document.
mysqlx_result_t * mysqlx_collection_modify_set(mysqlx_collection_t *collection, const char *criteria,...)
Modify documents in the collection.
mysqlx_result_t * mysqlx_collection_add(mysqlx_collection_t *collection,...)
Add a set of new documents to a collection.
mysqlx_stmt_t * mysqlx_collection_remove_new(mysqlx_collection_t *collection)
Create a statement which removes documents from a collection.
int mysqlx_set_add_document(mysqlx_stmt_t *stmt, const char *json_doc)
Specify a document to be added to a collection.
int mysqlx_set_modify_set(mysqlx_stmt_t *stmt,...)
Set fields in a document to given values.
mysqlx_stmt_t * mysqlx_collection_add_new(mysqlx_collection_t *collection)
Create a statement which adds documents to a collection.
mysqlx_result_t * mysqlx_collection_modify_unset(mysqlx_collection_t *collection, const char *criteria,...)
Unset fields in documents from the collection.
int mysqlx_set_find_projection(mysqlx_stmt_t *stmt, const char *proj)
Specify a projection for a collection find query.
mysqlx_result_t * mysqlx_collection_modify_patch(mysqlx_collection_t *collection, const char *criteria, const char *patch_spec)
Apply a given patch to documents in a collection.
mysqlx_stmt_t * mysqlx_collection_modify_new(mysqlx_collection_t *collection)
Create a statement which modifies documents in a collection.
int mysqlx_schema_drop(mysqlx_session_t *sess, const char *schema)
Drop a schema.
mysqlx_collection_options_t * mysqlx_collection_options_new()
Allocate a new create/modify collection options data.
int mysqlx_collection_create_with_json_options(mysqlx_schema_t *schema, const char *collection, const char *json_options)
Create a new collection in a specified schema.
int mysqlx_collection_options_set(mysqlx_collection_options_t *options,...)
Set collection options.
int mysqlx_collection_create_index(mysqlx_collection_t *coll, const char *name, const char *idx_spec)
Create index for a collection.
int mysqlx_collection_create_with_options(mysqlx_schema_t *schema, const char *collection, mysqlx_collection_options_t *options)
Create a new collection in a specified schema.
int mysqlx_collection_drop_index(mysqlx_collection_t *coll, const char *name)
Drop index on a collection.
int mysqlx_schema_create(mysqlx_session_t *sess, const char *schema)
Create a schema.
int mysqlx_collection_create(mysqlx_schema_t *schema, const char *collection)
Create a new collection in a specified schema.
int mysqlx_collection_drop(mysqlx_schema_t *schema, const char *collection)
Drop an existing collection in a specified schema.
mysqlx_error_t * mysqlx_error(void *obj)
Get the last error from the object.
unsigned int mysqlx_result_warning_count(mysqlx_result_t *res)
Get the number of warnings generated by a statement.
mysqlx_error_t * mysqlx_result_next_warning(mysqlx_result_t *res)
Get the next warning from the result.
const char * mysqlx_error_message(void *obj)
Get the error message from the object.
unsigned int mysqlx_error_num(void *obj)
Get the error number from the object.
const char * mysqlx_column_get_schema(mysqlx_result_t *res, uint32_t pos)
Get column's schema name.
const char * mysqlx_column_get_original_table(mysqlx_result_t *res, uint32_t pos)
Get column's original table name.
const char * mysqlx_column_get_name(mysqlx_result_t *res, uint32_t pos)
Get column name.
uint32_t mysqlx_column_get_length(mysqlx_result_t *res, uint32_t pos)
Get column length.
uint32_t mysqlx_column_get_count(mysqlx_result_t *res)
Get the number of columns in the result.
const char * mysqlx_column_get_original_name(mysqlx_result_t *res, uint32_t pos)
Get column original name.
const char * mysqlx_column_get_table(mysqlx_result_t *res, uint32_t pos)
Get column's table name.
uint16_t mysqlx_column_get_collation(mysqlx_result_t *res, uint32_t pos)
Get column collation number.
const char * mysqlx_column_get_catalog(mysqlx_result_t *res, uint32_t pos)
Get column's catalog name.
uint16_t mysqlx_column_get_precision(mysqlx_result_t *res, uint32_t pos)
Get column precision.
uint16_t mysqlx_column_get_type(mysqlx_result_t *res, uint32_t pos)
Get column type identifier.
const char * mysqlx_fetch_generated_id(mysqlx_result_t *result)
Get identifiers of the documents added to the collection.
uint64_t mysqlx_get_affected_count(mysqlx_result_t *res)
Get number of rows affected by a statement.
int mysqlx_store_result(mysqlx_result_t *result, size_t *num)
Store result data in an internal buffer.
int mysqlx_get_float(mysqlx_row_t *row, uint32_t col, float *val)
Get a float number from a row.
int mysqlx_get_uint(mysqlx_row_t *row, uint32_t col, uint64_t *val)
Get an unsigned integer number from a row.
mysqlx_row_t * mysqlx_row_fetch_one(mysqlx_result_t *res)
Fetch one row from the result.
const char * mysqlx_json_fetch_one(mysqlx_result_t *res, size_t *out_length)
Fetch one document as a JSON string.
int mysqlx_get_bytes(mysqlx_row_t *row, uint32_t col, uint64_t offset, void *buf, size_t *buf_len)
Read bytes stored in a row into a pre-allocated buffer.
int mysqlx_get_double(mysqlx_row_t *row, uint32_t col, double *val)
Get a double number from a row.
int mysqlx_get_count(mysqlx_result_t *result, size_t *num)
Function for getting the number of remaining cached items in a result.
int mysqlx_next_result(mysqlx_result_t *res)
Proceed to the next result set in the reply.
int mysqlx_get_sint(mysqlx_row_t *row, uint32_t col, int64_t *val)
Get a signed integer number from a row.
void mysqlx_result_free(mysqlx_result_t *res)
Free the result explicitly.
uint64_t mysqlx_get_auto_increment_value(mysqlx_result_t *res)
Get auto increment value generated by a statement that inserts rows into a table with auto increment ...
mysqlx_session_options_t * mysqlx_session_options_new()
Allocate a new session configuration data object.
mysqlx_client_t * mysqlx_get_client_from_url(const char *conn_string, const char *client_opts, mysqlx_error_t **error)
Create a client instance using connection string or URL and a client options JSON.
int mysqlx_session_option_set(mysqlx_session_options_t *opth,...)
Set session configuration options.
mysqlx_result_t * mysqlx_get_tables(mysqlx_schema_t *schema, const char *table_pattern, int get_views)
Get a list of tables and views in a schema.
int mysqlx_session_option_get(mysqlx_session_options_t *opth, int opt,...)
Read session configuration options.
mysqlx_session_t * mysqlx_get_session_from_url(const char *conn_string, mysqlx_error_t **error)
Create a session using connection string or URL.
mysqlx_result_t * mysqlx_get_schemas(mysqlx_session_t *sess, const char *schema_pattern)
Get a list of schemas.
void mysqlx_free_options(mysqlx_session_options_t *opt)
Free a session configuration data object.
int mysqlx_transaction_begin(mysqlx_session_t *sess)
Begin a transaction for the session.
int mysqlx_rollback_to(mysqlx_session_t *sess, const char *name)
Roll back to savepoint created by mysqlx_savepoint_set().
mysqlx_collection_t * mysqlx_get_collection(mysqlx_schema_t *schema, const char *col_name, unsigned int check)
Get a collection object and optionally check if it exists in the schema.
void mysqlx_session_close(mysqlx_session_t *session)
Close the session.
mysqlx_session_t * mysqlx_get_session(const char *host, int port, const char *user, const char *password, const char *database, mysqlx_error_t **error)
Create a new session.
int mysqlx_savepoint_release(mysqlx_session_t *sess, const char *name)
Release savepoint created by mysqlx_savepoint_set().
mysqlx_schema_t * mysqlx_get_schema(mysqlx_session_t *sess, const char *schema_name, unsigned int check)
Get a schema object and optionally check if it exists on the server.
void mysqlx_client_close(mysqlx_client_t *client)
Close the client pool and all sessions created by them.
mysqlx_result_t * mysqlx_get_collections(mysqlx_schema_t *schema, const char *col_pattern)
Get a list of collections in a schema.
int mysqlx_transaction_commit(mysqlx_session_t *sess)
Commit a transaction for the session.
mysqlx_client_t * mysqlx_get_client_from_options(mysqlx_session_options_t *opt, mysqlx_error_t **error)
Create a client pool using session configuration data.
int mysqlx_session_valid(mysqlx_session_t *sess)
Check the session validity.
const char * mysqlx_savepoint_set(mysqlx_session_t *sess, const char *name)
Create savepoint inside transaction.
mysqlx_table_t * mysqlx_get_table(mysqlx_schema_t *schema, const char *tab_name, unsigned int check)
Get a table object and optionally check if it exists in the schema.
mysqlx_session_t * mysqlx_get_session_from_options(mysqlx_session_options_t *opt, mysqlx_error_t **error)
Create a session using session configuration data.
int mysqlx_transaction_rollback(mysqlx_session_t *sess)
Roll back a transaction for the session.
mysqlx_result_t * mysqlx_sql(mysqlx_session_t *sess, const char *query, size_t query_len)
Execute a plain SQL query.
mysqlx_stmt_t * mysqlx_sql_new(mysqlx_session_t *sess, const char *query, uint32_t length)
Create a statement which executes a plain SQL query.
mysqlx_result_t * mysqlx_sql_param(mysqlx_session_t *sess, const char *query, size_t query_len,...)
Execute a plain SQL query with parameters.
int mysqlx_set_order_by(mysqlx_stmt_t *stmt,...)
Specify ordering for a statement.
mysqlx_result_t * mysqlx_execute(mysqlx_stmt_t *stmt)
Execute a statement.
int mysqlx_set_row_locking(mysqlx_stmt_t *stmt, int locking, int contention)
Set row locking mode for a statement.
int mysqlx_set_limit_and_offset(mysqlx_stmt_t *stmt, uint64_t row_count, uint64_t offset)
Set limit and offset information for a statement.
int mysqlx_stmt_bind(mysqlx_stmt_t *stmt,...)
Bind values for parametrized statements.
int mysqlx_set_having(mysqlx_stmt_t *stmt, const char *having_expr)
Specify filter conditions for a group of rows/documents or aggregates such as GROUP BY.
int mysqlx_set_insert_row(mysqlx_stmt_t *stmt,...)
Specify a row to be added by an INSERT statement.
int mysqlx_set_group_by(mysqlx_stmt_t *stmt,...)
Specify one or more columns/values to group the result in conjunction with the aggregate functions.
int mysqlx_set_items(mysqlx_stmt_t *stmt,...)
Specify a table query projection.
void mysqlx_free(void *obj)
Free the allocated handle explicitly.
int mysqlx_set_where(mysqlx_stmt_t *stmt, const char *where_expr)
Specify selection criteria for a statement.
mysqlx_stmt_t * mysqlx_table_delete_new(mysqlx_table_t *table)
Create a statement executing a table DELETE operation.
mysqlx_result_t * mysqlx_table_insert(mysqlx_table_t *table,...)
Execute a table INSERT statement with one row.
int mysqlx_set_insert_columns(mysqlx_stmt_t *stmt,...)
Specify column names for an INSERT statement.
mysqlx_result_t * mysqlx_table_delete(mysqlx_table_t *table, const char *criteria)
Execute a table DELETE statement with a WHERE clause.
mysqlx_stmt_t * mysqlx_table_update_new(mysqlx_table_t *table)
Create a statement executing a table UPDATE operation.
mysqlx_result_t * mysqlx_table_select(mysqlx_table_t *table, const char *criteria)
Execute a table SELECT statement with a WHERE clause.
mysqlx_stmt_t * mysqlx_table_select_new(mysqlx_table_t *table)
Create a statement which performs a table SELECT operation.
mysqlx_result_t * mysqlx_table_select_limit(mysqlx_table_t *table, const char *criteria, uint64_t row_count, uint64_t offset,...)
Execute a table SELECT statement with a WHERE, ORDER BY and LIMIT clauses.
mysqlx_stmt_t * mysqlx_table_insert_new(mysqlx_table_t *table)
Create a statement executing a table INSERT operation.
mysqlx_result_t * mysqlx_table_update(mysqlx_table_t *table, const char *criteria,...)
Execute a table UPDATE statement.
int mysqlx_set_update_values(mysqlx_stmt_t *stmt,...)
Set values for the columns in the UPDATE statement.
mysqlx_opt_type_t
Session options for use with mysqlx_session_option_get() and mysqlx_session_option_set() functions.
Definition: xapi.h:398
mysqlx_client_opt_type_t
Client options for use with mysqlx_session_option_get() and mysqlx_session_option_set() functions.
Definition: xapi.h:369
mysqlx_collection_validation_level_t
Collection validation level options .
Definition: xapi.h:496
mysqlx_lock_contention_t
Constants for defining the row locking options for mysqlx_set_row_locking() function.
Definition: xapi.h:538
struct mysqlx_result_struct mysqlx_result_t
Type of result handles.
Definition: xapi.h:301
mysqlx_collection_validation_opt_t
Collection validation options.
Definition: xapi.h:482
mysqlx_session_t * mysqlx_get_session_from_client(mysqlx_client_t *cli, mysqlx_error_t **error)
Create a new session.
struct mysqlx_row_struct mysqlx_row_t
Type of row handles.
Definition: xapi.h:288
mysqlx_collection_opt_t
Collection create/modify options.
Definition: xapi.h:467
struct mysqlx_stmt_struct mysqlx_stmt_t
Type of statement handles.
Definition: xapi.h:277
struct mysqlx_session_options_struct mysqlx_session_options_t
Type of handles for session configuration data.
Definition: xapi.h:227
struct mysqlx_session_struct mysqlx_session_t
Type of session handles.
Definition: xapi.h:205
mysqlx_data_type_t
The data type identifiers used in MYSQLX API.
Definition: xapi.h:309
struct mysqlx_client_struct mysqlx_client_t
Type of client handles.
Definition: xapi.h:213
struct mysqlx_collection_struct mysqlx_collection_t
Type of collection handles.
Definition: xapi.h:253
mysqlx_auth_method_t
Authentication method values for use with mysqlx_session_option_get() and mysqlx_session_option_set()...
Definition: xapi.h:454
mysqlx_compression_mode_t
Definition: xapi.h:513
struct mysqlx_error_struct mysqlx_error_t
Type of error handles.
Definition: xapi.h:196
mysqlx_ssl_mode_t
Session SSL mode values for use with mysqlx_session_option_get() and mysqlx_session_option_set() func...
Definition: xapi.h:441
mysqlx_row_locking_t
Constants for defining the row locking options for mysqlx_set_row_locking() function.
Definition: xapi.h:525
struct mysqlx_schema_struct mysqlx_schema_t
Type of database schema handles.
Definition: xapi.h:244
struct mysqlx_collection_options_struct mysqlx_collection_options_t
Type of handles for collection create/modify options.
Definition: xapi.h:236
struct mysqlx_table_struct mysqlx_table_t
Type of table handles.
Definition: xapi.h:261
mysqlx_sort_direction_t
Sort directions in sorting operations such as ORDER BY.
Definition: xapi.h:353
@ MYSQLX_TYPE_DECIMAL
Decimal type.
Definition: xapi.h:323
@ MYSQLX_TYPE_BOOL
Bool type.
Definition: xapi.h:326
@ MYSQLX_TYPE_BIT
Bit type.
Definition: xapi.h:322
@ MYSQLX_TYPE_SINT
64-bit signed integer number type
Definition: xapi.h:313
@ MYSQLX_TYPE_TIME
Time type.
Definition: xapi.h:318
@ MYSQLX_TYPE_EXPR
Expression type.
Definition: xapi.h:333
@ MYSQLX_TYPE_FLOAT
Floating point float number type.
Definition: xapi.h:316
@ MYSQLX_TYPE_STRING
String type.
Definition: xapi.h:328
@ MYSQLX_TYPE_UINT
64-bit unsigned integer number type
Definition: xapi.h:314
@ MYSQLX_TYPE_DOUBLE
Floating point double number type.
Definition: xapi.h:315
@ MYSQLX_TYPE_ENUM
Enum type.
Definition: xapi.h:321
@ MYSQLX_TYPE_NULL
NULL value.
Definition: xapi.h:332
@ MYSQLX_TYPE_BYTES
Bytes array type.
Definition: xapi.h:317
@ MYSQLX_TYPE_GEOMETRY
Geometry type.
Definition: xapi.h:329
@ MYSQLX_TYPE_TIMESTAMP
Timestamp type.
Definition: xapi.h:330
@ MYSQLX_TYPE_SET
Set type.
Definition: xapi.h:320
@ MYSQLX_TYPE_DATETIME
Datetime type.
Definition: xapi.h:319
@ MYSQLX_TYPE_JSON
JSON type.
Definition: xapi.h:327
@ ROW_LOCK_NONE
No locking.
Definition: xapi.h:528
@ SORT_ORDER_ASC
Ascending sorting (Default)
Definition: xapi.h:354
@ SORT_ORDER_DESC
Descending sorting.
Definition: xapi.h:355