Table Of ContentMySQL NDB Cluster API Developer Guide
MySQL NDB Cluster API Developer Guide
This is the MySQL NDB Cluster API Developer Guide, which provides information about developing applications
using NDB Cluster as a data store. Application interfaces covered in this Guide include the low-level C++-language
NDB API (see MySQL NDB Cluster API Developer Guide), the C-language MGM API for communicating with
and controlling NDB Cluster management servers (see Chapter 3, The MGM API), and the MySQL NDB Cluster
Connector for Java, which is a collection of Java APIs for writing applications against NDB Cluster, including JDBC,
JPA, and ClusterJ (see Chapter 4, MySQL NDB Cluster Connector for Java).
NDB Cluster 8.0 also provides support for applications written using Node.js. See Chapter 5, MySQL NoSQL
Connector for JavaScript, for more information.
This Guide includes concepts, terminology, class and function references, practical examples, common problems, and
tips for using these APIs in applications.
For information about NDB internals that may be of interest to developers working with NDB, see MySQL NDB Cluster
Internals Manual.
The information presented in this guide is current for recent releases of NDB Cluster up to and including NDB Cluster
8.0.32. Due to significant functional and other changes in NDB Cluster and its underlying APIs, you should not expect
this information to apply to versions of the NDB Cluster software prior to NDB Cluster 7.4. Users of older NDB Cluster
releases should upgrade to the latest available release of NDB Cluster 8.0, currently the most recent GA release
series.
For more information about NDB 8.0, see What is New in MySQL NDB Cluster.
For legal information, see the Legal Notices.
For help with using MySQL, please visit the MySQL Forums, where you can discuss your issues with other MySQL
users.
Licensing information—NDB APIs. If you are using the NDB APIs with a Commercial release of MySQL NDB
Cluster, see the MySQL NDB Cluster 8.0 Commercial Release License Information User Manual for licensing
information, including licensing information relating to third-party software that may be included in this Commercial
release. If you are using the NDB APIs with a Community release of MySQL NDB Cluster, see the MySQL NDB
Cluster 8.0 Community Release License Information User Manual for licensing information, including licensing
information relating to third-party software that may be included in this Community release.
Document generated on: 2023-01-26 (revision: 74905)
Table of Contents
Preface and Legal Notices ................................................................................................................ vii
1 NDB Cluster APIs: Overview and Concepts ...................................................................................... 1
1.1 NDB Cluster API Overview: Introduction ................................................................................ 1
1.1.1 NDB Cluster API Overview: The NDB API .................................................................. 1
1.1.2 NDB Cluster API Overview: The MGM API ................................................................. 2
1.2 NDB Cluster API Overview: Version Compatibility .................................................................. 2
1.3 NDB Cluster API Overview: Terminology............................................................................... 3
1.4 The NDB Transaction and Scanning API ............................................................................... 4
1.4.1 Core NDB API Classes .............................................................................................. 5
1.4.2 Application Program Basics ........................................................................................ 5
1.4.3 Review of NDB Cluster Concepts ............................................................................. 13
1.4.4 The Adaptive Send Algorithm ................................................................................... 14
1.5 Application-level partitioning ................................................................................................ 15
1.6 Using NdbInterpretedCode.................................................................................................. 16
2 The NDB API ................................................................................................................................ 23
2.1 Getting Started with the NDB API ....................................................................................... 24
2.1.1 Compiling and Linking NDB API Programs ................................................................ 24
2.1.2 Connecting to the Cluster ......................................................................................... 27
2.1.3 Mapping MySQL Database Object Names and Types to NDB .................................... 28
2.2 The NDB API Class Hierarachy .......................................................................................... 33
2.3 NDB API Classes, Interfaces, and Structures ....................................................................... 34
2.3.1 The Column Class ................................................................................................... 35
2.3.2 The Datafile Class ................................................................................................... 53
2.3.3 The Dictionary Class ................................................................................................ 58
2.3.4 The Element Structure ............................................................................................. 77
2.3.5 The Event Class ...................................................................................................... 78
2.3.6 The ForeignKey Class ............................................................................................. 89
2.3.7 The HashMap Class ................................................................................................ 97
2.3.8 The Index Class .................................................................................................... 100
2.3.9 The LogfileGroup Class .......................................................................................... 106
2.3.10 The List Class ...................................................................................................... 110
2.3.11 The Ndb Class ..................................................................................................... 111
2.3.12 The Ndb_cluster_connection Class....................................................................... 135
2.3.13 The NdbBlob Class.............................................................................................. 146
2.3.14 The NdbDictionary Class ...................................................................................... 156
2.3.15 The NdbError Structure ........................................................................................ 163
2.3.16 The NdbEventOperation Class .............................................................................. 167
2.3.17 The NdbIndexOperation Class .............................................................................. 177
2.3.18 The NdbIndexScanOperation Class ....................................................................... 179
2.3.19 The NdbInterpretedCode Class ............................................................................. 185
2.3.20 The NdbOperation Class ...................................................................................... 213
2.3.21 The NdbRecAttr Class .......................................................................................... 253
2.3.22 The NdbRecord Interface ..................................................................................... 260
2.3.23 The NdbScanFilter Class ...................................................................................... 261
2.3.24 The NdbScanOperation Class ............................................................................... 273
2.3.25 The NdbTransaction Class ................................................................................... 285
2.3.26 The Object Class ................................................................................................. 304
2.3.27 The Table Class .................................................................................................. 309
2.3.28 The Tablespace Class .......................................................................................... 336
2.3.29 The Undofile Class ............................................................................................... 341
2.4 NDB API Errors and Error Handling ................................................................................... 347
iii
MySQL NDB Cluster API Developer Guide
2.4.1 Handling NDB API Errors ....................................................................................... 347
2.4.2 NDB Error Codes: by Type.................................................................................... 351
2.4.3 NDB Error Codes: Single Listing ............................................................................. 422
2.4.4 NDB Error Classifications ....................................................................................... 500
2.5 NDB API Examples .......................................................................................................... 501
2.5.1 Basic NDB API Examples ...................................................................................... 501
2.5.2 NDB API Example Using Synchronous Transactions ................................................ 508
2.5.3 NDB API Example Using Synchronous Transactions and Multiple Clusters ................ 513
2.5.4 NDB API Example: Handling Errors and Retrying Transactions ................................. 518
2.5.5 NDB API Basic Scanning Example ......................................................................... 523
2.5.6 NDB API Example: Using Secondary Indexes in Scans ............................................ 537
2.5.7 NDB API Example: Using NdbRecord with Hash Indexes ......................................... 541
2.5.8 NDB API Example Comparing RecAttr and NdbRecord ............................................ 547
2.5.9 NDB API Event Handling Example .......................................................................... 595
2.5.10 NDB API Example: Basic BLOB Handling ............................................................. 600
2.5.11 NDB API Example: Handling BLOB Columns and Values Using NdbRecord ............ 607
2.5.12 NDB API Simple Array Example ........................................................................... 616
2.5.13 NDB API Simple Array Example Using Adapter ..................................................... 622
2.5.14 Timestamp2 Example........................................................................................... 628
2.5.15 Common Files for NDB API Array Examples ......................................................... 631
3 The MGM API ............................................................................................................................. 641
3.1 MGM API Concepts .......................................................................................................... 641
3.2 MGM API Function Listing ................................................................................................ 643
3.2.1 Log Event Functions.............................................................................................. 643
3.2.2 MGM API Error Handling Functions ........................................................................ 646
3.2.3 Management Server Handle Functions .................................................................... 648
3.2.4 Management Server Connection Functions ............................................................. 649
3.2.5 Cluster Status Functions ........................................................................................ 655
3.2.6 Functions for Starting & Stopping Nodes ................................................................. 657
3.2.7 Cluster Log Functions ............................................................................................ 663
3.2.8 Backup Functions .................................................................................................. 665
3.2.9 Single-User Mode Functions ................................................................................... 669
3.3 MGM API Data Types ....................................................................................................... 670
3.4 MGM API Data Structures ................................................................................................. 679
3.5 MGM API Errors ............................................................................................................... 686
3.6 MGM API Examples ......................................................................................................... 688
3.6.1 Basic MGM API Event Logging Example ................................................................. 688
3.6.2 MGM API Event Handling with Multiple Clusters ...................................................... 690
4 MySQL NDB Cluster Connector for Java ...................................................................................... 695
4.1 MySQL NDB Cluster Connector for Java: Overview ............................................................ 695
4.1.1 MySQL NDB Cluster Connector for Java Architecture .............................................. 695
4.1.2 Java and NDB Cluster ........................................................................................... 695
4.1.3 The ClusterJ API and Data Object Model ................................................................ 697
4.2 Using MySQL NDB Cluster Connector for Java .................................................................. 699
4.2.1 Getting, Installing, and Setting Up MySQL NDB Cluster Connector for Java ............... 699
4.2.2 Using ClusterJ....................................................................................................... 701
4.2.3 Using Connector/J with NDB Cluster ....................................................................... 710
4.3 ClusterJ API Reference ..................................................................................................... 710
4.3.1 com.mysql.clusterj .................................................................................................. 710
4.3.2 com.mysql.clusterj.annotation ................................................................................. 759
4.3.3 com.mysql.clusterj.query ......................................................................................... 767
4.3.4 Constant field values.............................................................................................. 774
4.4 MySQL NDB Cluster Connector for Java: Limitations and Known Issues .............................. 775
5 MySQL NoSQL Connector for JavaScript ..................................................................................... 777
iv
MySQL NDB Cluster API Developer Guide
5.1 MySQL NoSQL Connector for JavaScript Overview ............................................................ 777
5.2 Installing the JavaScript Connector .................................................................................... 778
5.3 Connector for JavaScript API Documentation ..................................................................... 779
5.3.1 Batch ..................................................................................................................... 779
5.3.2 Context .................................................................................................................. 779
5.3.3 Converter ............................................................................................................... 782
5.3.4 Errors.................................................................................................................... 782
5.3.5 Mynode ................................................................................................................. 783
5.3.6 Session ................................................................................................................. 785
5.3.7 SessionFactory...................................................................................................... 786
5.3.8 TableMapping and FieldMapping............................................................................ 787
5.3.9 TableMetadata ....................................................................................................... 788
5.3.10 Transaction .......................................................................................................... 789
5.4 Using the MySQL JavaScript Connector: Examples ............................................................ 790
5.4.1 Requirements for the Examples .............................................................................. 790
5.4.2 Example: Finding Rows .......................................................................................... 794
5.4.3 Inserting Rows....................................................................................................... 796
5.4.4 Deleting Rows ....................................................................................................... 798
6 ndbmemcache—Memcache API for NDB Cluster (NO LONGER SUPPORTED) .............................. 801
6.1 Overview .......................................................................................................................... 801
6.2 Compiling NDB Cluster with Memcache Support ................................................................ 801
6.3 memcached command line options .................................................................................... 802
6.4 NDB Engine Configuration ................................................................................................ 803
6.5 Memcache protocol commands ......................................................................................... 809
6.6 The memcached log file .................................................................................................... 811
6.7 Known Issues and Limitations of ndbmemcache ................................................................. 812
Index.............................................................................................................................................. 815
v
vi
Preface and Legal Notices
This is the MySQL NDB Cluster API Developer Guide, which provides information about developing
applications using NDB Cluster as a data store. Application interfaces covered in this Guide include the
low-level C++-language NDB API (see MySQL NDB Cluster API Developer Guide), the C-language MGM
API for communicating with and controlling NDB Cluster management servers (see Chapter 3, The MGM
API), and the MySQL NDB Cluster Connector for Java, which is a collection of Java APIs for writing
applications against NDB Cluster, including JDBC, JPA, and ClusterJ (see Chapter 4, MySQL NDB Cluster
Connector for Java).
NDB Cluster 8.0 also provides support for applications written using Node.js. See Chapter 5, MySQL
NoSQL Connector for JavaScript, for more information.
This Guide includes concepts, terminology, class and function references, practical examples, common
problems, and tips for using these APIs in applications. It also contains information about NDB internals
that may be of interest to developers working with NDB, such as communication protocols employed
between nodes, file systems used by management nodes and data nodes, error messages, and debugging
(DUMP) commands in the management client.
The information presented in this guide is current for recent releases of NDB Cluster up to and including
NDB Cluster 8.0.32. Due to significant functional and other changes in NDB Cluster and its underlying
APIs, you should not expect this information to apply to previous releases of the NDB Cluster software
prior to NDB Cluster 7.4. Users of older NDB Cluster releases should upgrade to the latest available
release of NDB Cluster 8.0, which is the most recent GA release series.
For more information about NDB 8.0, see What is New in MySQL NDB Cluster.
For legal information, see the Legal Notices.
Licensing information—MySQL NDB Cluster 8.0. This product may include third-party software,
used under license. If you are using a Commercial release of MySQL NDB Cluster 8.0, see the MySQL
NDB Cluster 8.0 Commercial Release License Information User Manual for licensing information, including
licensing information relating to third-party software that may be included in this Commercial release. If you
are using a Community release of MySQL NDB Cluster 8.0, see the MySQL NDB Cluster 8.0 Community
Release License Information User Manual for licensing information, including licensing information relating
to third-party software that may be included in this Community release.
Legal Notices
Copyright © 1997, 2023, Oracle and/or its affiliates.
This software and related documentation are provided under a license agreement containing restrictions
on use and disclosure and are protected by intellectual property laws. Except as expressly permitted
in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast,
modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any
means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for
interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free.
If you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it
on behalf of the U.S. Government, then the following notice is applicable:
vii
Documentation Accessibility
U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated
software, any programs embedded, installed or activated on delivered hardware, and modifications of
such programs) and Oracle computer documentation or other Oracle data delivered to or accessed by
U.S. Government end users are "commercial computer software" or "commercial computer software
documentation" pursuant to the applicable Federal Acquisition Regulation and agency-specific
supplemental regulations. As such, the use, reproduction, duplication, release, display, disclosure,
modification, preparation of derivative works, and/or adaptation of i) Oracle programs (including any
operating system, integrated software, any programs embedded, installed or activated on delivered
hardware, and modifications of such programs), ii) Oracle computer documentation and/or iii) other Oracle
data, is subject to the rights and limitations specified in the license contained in the applicable contract.
The terms governing the U.S. Government's use of Oracle cloud services are defined by the applicable
contract for such services. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications, including
applications that may create a risk of personal injury. If you use this software or hardware in dangerous
applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other
measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages
caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks
of their respective owners.
Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks
are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,
Epyc, and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a
registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content,
products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and
expressly disclaim all warranties of any kind with respect to third-party content, products, and services
unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its
affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of
third-party content, products, or services, except as set forth in an applicable agreement between you and
Oracle.
This documentation is NOT distributed under a GPL license. Use of this documentation is subject to the
following terms:
You may create a printed copy of this documentation solely for your own personal use. Conversion to other
formats is allowed as long as the actual content is not altered or edited in any way. You shall not publish
or distribute this documentation in any form or on any media, except if you distribute the documentation in
a manner similar to how Oracle disseminates it (that is, electronically for download on a Web site with the
software) or on a CD-ROM or similar medium, provided however that the documentation is disseminated
together with the software on the same medium. Any other use, such as any dissemination of printed
copies or use of this documentation, in whole or in part, in another publication, requires the prior written
consent from an authorized representative of Oracle. Oracle and/or its affiliates reserve any and all rights
to this documentation not expressly granted above.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website
at
https://www.oracle.com/corporate/accessibility/.
viii
Access to Oracle Support for Accessibility
Access to Oracle Support for Accessibility
Oracle customers that have purchased support have access to electronic support through My Oracle
Support. For information, visit
https://www.oracle.com/corporate/accessibility/learning-support.html#support-tab.
ix
x
Description:For more information, see Chapter 6, ndbmemcache—Memcache API for MySQL
Cluster. This Guide also provides information about support for JavaScript
