MySQL Connector/C++ 9.1.0
MySQL connector library for C and C++ applications
xapi.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2016, 2024, 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 designed to work with certain software (including
9 * but not limited to OpenSSL) that is licensed under separate terms, as
10 * designated in a particular file or component or in included license
11 * documentation. The authors of MySQL hereby grant you an additional
12 * permission to link the program and your derivative works with the
13 * separately licensed software that they have either included with
14 * the program or referenced in the documentation.
15 *
16 * Without limiting anything contained in the foregoing, this file,
17 * which is part of Connector/C++, is also subject to the
18 * Universal FOSS Exception, version 1.0, a copy of which can be found at
19 * https://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
521typedef enum mysqlx_compression_mode_enum
522{
523#define XAPI_COMPRESSION_ENUM(X,N) MYSQLX_COMPRESSION_##X = N,
524
525 COMPRESSION_MODE_LIST(XAPI_COMPRESSION_ENUM)
526}
534typedef enum mysqlx_row_locking_enum
535{
536#define XAPI_ROW_LOCK_ENUM(X,N) ROW_LOCK_##X = N,
537
538 ROW_LOCK_NONE = 0,
539 LOCK_MODE_LIST(XAPI_ROW_LOCK_ENUM)
540}
542
548typedef enum mysqlx_lock_contention_enum
549{
550#define XAPI_LOCK_CONTENTION_ENUM(X,N) LOCK_CONTENTION_##X = N,
551
552 LOCK_CONTENTION_LIST(XAPI_LOCK_CONTENTION_ENUM)
553}
555
556/*
557 ====================================================================
558 Client operations
559 ====================================================================
560*/
561
624PUBLIC_API mysqlx_client_t *
625mysqlx_get_client_from_url(const char *conn_string, const char *client_opts,
626 mysqlx_error_t **error);
627
628
677PUBLIC_API mysqlx_client_t *
679 mysqlx_error_t **error);
680
698PUBLIC_API void mysqlx_client_close(mysqlx_client_t *client);
699
700/*
701 ====================================================================
702 Session operations
703 ====================================================================
704*/
705
717PUBLIC_API mysqlx_session_t *
719 mysqlx_error_t **error);
720
745PUBLIC_API mysqlx_session_t *
746mysqlx_get_session(const char *host, int port, const char *user,
747 const char *password, const char *database,
748 mysqlx_error_t **error);
749
750
832PUBLIC_API mysqlx_session_t *
833mysqlx_get_session_from_url(const char *conn_string,
834 mysqlx_error_t **error);
835
855PUBLIC_API mysqlx_session_t *
857 mysqlx_error_t **error);
858
859
860
876PUBLIC_API void mysqlx_session_close(mysqlx_session_t *session);
877
878
896PUBLIC_API int mysqlx_session_valid(mysqlx_session_t *sess);
897
917PUBLIC_API mysqlx_result_t *
918mysqlx_get_schemas(mysqlx_session_t *sess, const char *schema_pattern);
919
920
940PUBLIC_API mysqlx_schema_t *
941mysqlx_get_schema(mysqlx_session_t *sess, const char *schema_name,
942 unsigned int check);
943
944
972PUBLIC_API mysqlx_result_t *
974 const char *table_pattern,
975 int get_views);
976
977
997PUBLIC_API mysqlx_table_t *
998mysqlx_get_table(mysqlx_schema_t *schema, const char *tab_name,
999 unsigned int check);
1000
1001
1022PUBLIC_API mysqlx_result_t *
1024 const char *col_pattern);
1025
1026
1046PUBLIC_API mysqlx_collection_t *
1047mysqlx_get_collection(mysqlx_schema_t *schema, const char *col_name,
1048 unsigned int check);
1049
1050
1066PUBLIC_API int
1068
1069
1084PUBLIC_API int
1086
1087
1102PUBLIC_API int
1104
1105
1123PUBLIC_API const char*
1124mysqlx_savepoint_set( mysqlx_session_t *sess, const char *name);
1125
1126
1140PUBLIC_API int
1141mysqlx_savepoint_release(mysqlx_session_t *sess, const char *name);
1142
1143
1157PUBLIC_API int
1158mysqlx_rollback_to( mysqlx_session_t *sess, const char *name);
1159
1160
1173
1174
1186PUBLIC_API void mysqlx_free_options(mysqlx_session_options_t *opt);
1187
1188
1217PUBLIC_API int
1219
1220
1248PUBLIC_API int
1250 ...);
1251
1252/*
1253 ====================================================================
1254 SQL execution
1255 ====================================================================
1256*/
1257
1275 const char *query,
1276 size_t query_len);
1277
1278
1311 const char *query,
1312 size_t query_len, ...);
1313
1314
1340PUBLIC_API mysqlx_stmt_t *
1341mysqlx_sql_new(mysqlx_session_t *sess, const char *query,
1342 uint32_t length);
1343
1344
1345/*
1346 ====================================================================
1347 Collection operations
1348 ====================================================================
1349*/
1350
1363PUBLIC_API int
1364mysqlx_collection_count(mysqlx_collection_t *collection, uint64_t *count);
1365
1366
1382PUBLIC_API mysqlx_result_t *
1383mysqlx_collection_find(mysqlx_collection_t *collection, const char *criteria);
1384
1385
1418PUBLIC_API mysqlx_result_t *
1420
1421
1436PUBLIC_API mysqlx_result_t *
1437mysqlx_collection_remove(mysqlx_collection_t *collection, const char*criteria);
1438
1439
1472PUBLIC_API mysqlx_result_t *
1474 const char *criteria, ...);
1475
1476
1493PUBLIC_API mysqlx_result_t *
1495 const char *criteria, ...);
1496
1497
1515PUBLIC_API mysqlx_result_t *
1517 const char *criteria,
1518 const char *patch_spec);
1519
1520
1534PUBLIC_API int
1536 const char *patch_spec);
1537
1538/*
1539 Deferred statement execution
1540 ----------------------------
1541*/
1542
1559PUBLIC_API mysqlx_stmt_t *
1561
1562
1583PUBLIC_API int mysqlx_set_find_projection(mysqlx_stmt_t *stmt, const char *proj);
1584
1585
1594#define mysqlx_set_find_criteria mysqlx_set_where
1595
1596
1597/*
1598A macro defining a function for setting HAVING for FIND operation.
1599
1600@see mysqlx_set_having()
1601@ingroup xapi_tbl
1602*/
1603
1604#define mysqlx_set_find_having mysqlx_set_having
1605
1614#define mysqlx_set_find_group_by mysqlx_set_group_by
1615
1624#define mysqlx_set_find_limit_and_offset(STMT, LIM, OFFS) mysqlx_set_limit_and_offset(STMT, LIM, OFFS)
1625
1634#define mysqlx_set_find_order_by mysqlx_set_order_by
1635
1636
1645#define mysqlx_set_find_row_locking mysqlx_set_row_locking
1646
1647
1665PUBLIC_API mysqlx_stmt_t *
1667
1668
1694PUBLIC_API int
1695mysqlx_set_add_document(mysqlx_stmt_t *stmt, const char *json_doc);
1696
1697
1714PUBLIC_API mysqlx_stmt_t *
1716
1725#define mysqlx_set_remove_criteria mysqlx_set_where
1726
1735#define mysqlx_set_remove_order_by mysqlx_set_order_by
1736
1745#define mysqlx_set_remove_limit_and_offset mysqlx_set_limit_and_offset
1746
1747
1765PUBLIC_API mysqlx_stmt_t *
1767
1768
1791PUBLIC_API int
1793
1794
1808PUBLIC_API int
1810
1811
1831PUBLIC_API int
1833
1834
1854PUBLIC_API int
1856
1857
1870PUBLIC_API int mysqlx_set_modify_array_delete(mysqlx_stmt_t *stmt, ...);
1871
1880#define mysqlx_set_modify_criteria mysqlx_set_where
1881
1882
1883/*
1884 ====================================================================
1885 Table operations
1886 ====================================================================
1887*/
1888
1889
1902PUBLIC_API int
1903mysqlx_table_count(mysqlx_table_t *table, uint64_t *count);
1904
1905
1922PUBLIC_API mysqlx_result_t *
1923mysqlx_table_select(mysqlx_table_t *table, const char *criteria);
1924
1925
1953PUBLIC_API mysqlx_result_t *
1954mysqlx_table_select_limit(mysqlx_table_t *table, const char *criteria,
1955 uint64_t row_count, uint64_t offset, ...);
1956
1957
1982PUBLIC_API mysqlx_result_t *
1984
1985
2000PUBLIC_API mysqlx_result_t *
2001mysqlx_table_delete(mysqlx_table_t *table, const char *criteria);
2002
2003
2004
2030PUBLIC_API mysqlx_result_t *
2032 const char *criteria,
2033 ...);
2034
2035
2036/*
2037 Deferred statement execution
2038 ----------------------------
2039*/
2040
2060PUBLIC_API mysqlx_stmt_t *
2062
2071#define mysqlx_set_select_items mysqlx_set_items
2072
2081#define mysqlx_set_select_where mysqlx_set_where
2082
2083
2092#define mysqlx_set_select_order_by mysqlx_set_order_by
2093
2094
2095/*
2096 A macro defining a function for setting HAVING for SELECT operation.
2097
2098 @see mysqlx_set_having()
2099 @ingroup xapi_tbl
2100*/
2101
2102#define mysqlx_set_select_having mysqlx_set_having
2103
2112#define mysqlx_set_select_group_by mysqlx_set_group_by
2113
2122#define mysqlx_set_select_limit_and_offset mysqlx_set_limit_and_offset
2123
2124
2133#define mysqlx_set_select_row_locking mysqlx_set_row_locking
2134
2135
2153PUBLIC_API mysqlx_stmt_t *
2155
2156
2178PUBLIC_API int
2180
2181
2205PUBLIC_API int
2207
2208
2228PUBLIC_API mysqlx_stmt_t *
2230
2239#define mysqlx_set_delete_where mysqlx_set_where
2248#define mysqlx_set_delete_limit(STMT, LIM) mysqlx_set_limit_and_offset(STMT, LIM, 0)
2257#define mysqlx_set_delete_order_by mysqlx_set_order_by
2258
2259
2280PUBLIC_API mysqlx_stmt_t *
2282
2283
2312PUBLIC_API int mysqlx_set_update_values(mysqlx_stmt_t *stmt, ...);
2313
2322#define mysqlx_set_update_where mysqlx_set_where
2323
2332#define mysqlx_set_update_limit(STMT, LIM) mysqlx_set_limit_and_offset(STMT, LIM, 0)
2333
2334
2343#define mysqlx_set_update_order_by mysqlx_set_order_by
2344
2345
2346/*
2347 ====================================================================
2348 Statement execution
2349 ====================================================================
2350*/
2351
2374PUBLIC_API mysqlx_result_t *
2376
2377
2422PUBLIC_API int mysqlx_stmt_bind(mysqlx_stmt_t *stmt, ...);
2423
2424
2447PUBLIC_API int mysqlx_set_items(mysqlx_stmt_t *stmt, ...);
2448
2449
2478PUBLIC_API int mysqlx_set_where(mysqlx_stmt_t *stmt, const char *where_expr);
2479
2480
2509PUBLIC_API int mysqlx_set_having(mysqlx_stmt_t *stmt, const char *having_expr);
2510
2511
2538PUBLIC_API int mysqlx_set_group_by(mysqlx_stmt_t *stmt, ...);
2539
2571PUBLIC_API int mysqlx_set_order_by(mysqlx_stmt_t *stmt, ...);
2572
2573
2606PUBLIC_API int
2607mysqlx_set_limit_and_offset(mysqlx_stmt_t *stmt, uint64_t row_count,
2608 uint64_t offset);
2609
2640PUBLIC_API int
2641mysqlx_set_row_locking(mysqlx_stmt_t *stmt, int locking, int contention);
2642
2668PUBLIC_API void mysqlx_free(void *obj);
2669
2670
2671/*
2672 ====================================================================
2673 Result handling
2674 ====================================================================
2675*/
2676
2694
2695
2713PUBLIC_API const char * mysqlx_json_fetch_one(mysqlx_result_t *res, size_t *out_length);
2714
2715
2734PUBLIC_API int mysqlx_next_result(mysqlx_result_t *res);
2735
2736
2750PUBLIC_API uint64_t
2752
2753
2781PUBLIC_API int
2782mysqlx_store_result(mysqlx_result_t *result, size_t *num);
2783
2784
2802PUBLIC_API int
2803mysqlx_get_count(mysqlx_result_t *result, size_t *num);
2804
2805
2829PUBLIC_API const char *
2831
2832
2847PUBLIC_API uint64_t
2849
2850
2899PUBLIC_API int
2900mysqlx_get_bytes(mysqlx_row_t* row, uint32_t col,
2901 uint64_t offset, void *buf, size_t *buf_len);
2902
2903
2922PUBLIC_API int
2923mysqlx_get_uint(mysqlx_row_t* row, uint32_t col, uint64_t* val);
2924
2925
2944PUBLIC_API int
2945mysqlx_get_sint(mysqlx_row_t* row, uint32_t col, int64_t* val);
2946
2947
2966PUBLIC_API int
2967mysqlx_get_float(mysqlx_row_t* row, uint32_t col, float* val);
2968
2969
2988PUBLIC_API int
2989mysqlx_get_double(mysqlx_row_t* row, uint32_t col, double *val);
2990
2991
3005PUBLIC_API void mysqlx_result_free(mysqlx_result_t *res);
3006
3007
3008/*
3009 Result metadata
3010 ---------------
3011*/
3012
3024PUBLIC_API uint16_t
3025mysqlx_column_get_type(mysqlx_result_t *res, uint32_t pos);
3026
3027
3041PUBLIC_API uint16_t
3043
3044
3063PUBLIC_API uint32_t
3064mysqlx_column_get_length(mysqlx_result_t *res, uint32_t pos);
3065
3066
3078PUBLIC_API uint16_t
3080
3081
3082/*
3083 Get column flags.
3084
3085 @param res result handle
3086 @param pos zero-based column number
3087
3088 @return 32-bit unsigned integer containing column flags reported by
3089 server. TODO: Document these
3090
3091 @ingroup xapi_md
3092*/
3093//PUBLIC_API uint32_t
3094//mysqlx_column_get_flags(mysqlx_result_t *res, uint32_t pos);
3095
3096
3111PUBLIC_API uint32_t
3113
3114
3126PUBLIC_API const char *
3127mysqlx_column_get_name(mysqlx_result_t *res, uint32_t pos);
3128
3129
3141PUBLIC_API const char *
3143
3144
3156PUBLIC_API const char *
3157mysqlx_column_get_table(mysqlx_result_t *res, uint32_t pos);
3158
3159
3171PUBLIC_API const char *
3173
3174
3186PUBLIC_API const char *
3187mysqlx_column_get_schema(mysqlx_result_t *res, uint32_t pos);
3188
3189
3201PUBLIC_API const char *
3202mysqlx_column_get_catalog(mysqlx_result_t *res, uint32_t pos);
3203
3204
3205/*
3206 ====================================================================
3207 DDL statements
3208 ====================================================================
3209*/
3210
3224PUBLIC_API int
3225mysqlx_schema_create(mysqlx_session_t *sess, const char *schema);
3226
3227
3241PUBLIC_API int
3242mysqlx_schema_drop(mysqlx_session_t *sess, const char *schema);
3243
3244
3258PUBLIC_API int
3259mysqlx_collection_create(mysqlx_schema_t *schema, const char *collection);
3260
3261
3273PUBLIC_API mysqlx_collection_options_t *
3275
3276
3306PUBLIC_API int
3308
3309
3324PUBLIC_API int
3326 const char *collection,
3328
3376PUBLIC_API int
3378 const char *collection,
3379 const char* json_options);
3380
3381PUBLIC_API int
3382mysqlx_collection_modify_with_options(mysqlx_schema_t *schema,
3383 const char *collection,
3385
3386PUBLIC_API int
3387mysqlx_collection_modify_with_json_options(mysqlx_schema_t *schema,
3388 const char* collection,
3389 const char* json_options);
3390
3391
3392
3406PUBLIC_API int
3407mysqlx_collection_drop(mysqlx_schema_t *schema, const char *collection);
3408
3409
3410/*
3411 ====================================================================
3412 Diagnostics
3413 ====================================================================
3414*/
3415
3416
3431PUBLIC_API mysqlx_error_t * mysqlx_error(void *obj);
3432
3433
3448PUBLIC_API const char * mysqlx_error_message(void *obj);
3449
3450
3465PUBLIC_API unsigned int mysqlx_error_num(void *obj);
3466
3467
3477PUBLIC_API unsigned int mysqlx_result_warning_count(mysqlx_result_t *res);
3478
3479
3497PUBLIC_API mysqlx_error_t *
3499
3500
3521PUBLIC_API int
3523 const char *idx_spec);
3524
3543PUBLIC_API int
3544mysqlx_collection_drop_index(mysqlx_collection_t *coll, const char *name);
3545
3546
3547#ifdef __cplusplus
3548}
3549#endif
3550
3553#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:542
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
Compression modes.
Definition: xapi.h:517
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:529
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:532
@ SORT_ORDER_ASC
Ascending sorting (Default)
Definition: xapi.h:354
@ SORT_ORDER_DESC
Descending sorting.
Definition: xapi.h:355