MySQL 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 for the MySQL NDB storage engine, the C-language MGM API for communicating with and controlling NDB Cluster management servers, 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.

NDB Cluster also provides support for the Memcache API; for more information, see Chapter 6, ndbmemcache—Memcache API for NDB Cluster.

NDB Cluster 7.3 and later 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.21. 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.3. 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 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 7.6 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: 2020-06-02 (revision: 66153)

Table of Contents

Preface and Legal Notices
1 NDB Cluster APIs: Overview and Concepts
1.1 NDB Cluster API Overview: Introduction
1.1.1 NDB Cluster API Overview: The NDB API
1.1.2 NDB Cluster API Overview: The MGM API
1.2 NDB Cluster API Overview: Terminology
1.3 The NDB Transaction and Scanning API
1.3.1 Core NDB API Classes
1.3.2 Application Program Basics
1.3.3 Review of NDB Cluster Concepts
1.3.4 The Adaptive Send Algorithm
2.1 Getting Started with the NDB API
2.1.1 Compiling and Linking NDB API Programs
2.1.2 Connecting to the Cluster
2.1.3 Mapping MySQL Database Object Names and Types to NDB
2.2 The NDB API Class Hierarachy
2.3 NDB API Classes, Interfaces, and Structures
2.3.1 The AutoGrowSpecification Structure
2.3.2 The Column Class
2.3.3 The Datafile Class
2.3.4 The Dictionary Class
2.3.5 The Element Structure
2.3.6 The Event Class
2.3.7 The EventBufferMemoryUsage Structure
2.3.8 The ForeignKey Class
2.3.9 The GetValueSpec Structure
2.3.10 The HashMap Class
2.3.11 The Index Class
2.3.12 The IndexBound Structure
2.3.13 The LogfileGroup Class
2.3.14 The List Class
2.3.15 The Key_part_ptr Structure
2.3.16 The Ndb Class
2.3.17 The Ndb_cluster_connection Class
2.3.18 The NdbBlob Class
2.3.19 The NdbDictionary Class
2.3.20 The NdbError Structure
2.3.21 The NdbEventOperation Class
2.3.22 The NdbIndexOperation Class
2.3.23 The NdbIndexScanOperation Class
2.3.24 The NdbInterpretedCode Class
2.3.25 The NdbOperation Class
2.3.26 The NdbRecAttr Class
2.3.27 The NdbRecord Interface
2.3.28 The NdbScanFilter Class
2.3.29 The NdbScanOperation Class
2.3.30 The NdbTransaction Class
2.3.31 The Object Class
2.3.32 The OperationOptions Structure
2.3.33 The PartitionSpec Structure
2.3.34 The RecordSpecification Structure
2.3.35 The ScanOptions Structure
2.3.36 The SetValueSpec Structure
2.3.37 The Table Class
2.3.38 The Tablespace Class
2.3.39 The Undofile Class
2.4 NDB API Errors and Error Handling
2.4.1 Handling NDB API Errors
2.4.2 NDB Error Codes: by Type
2.4.3 NDB Error Codes: Single Listing
2.4.4 NDB Error Classifications
2.5 NDB API Examples
2.5.1 NDB API Example Using Synchronous Transactions
2.5.2 NDB API Example Using Synchronous Transactions and Multiple Clusters
2.5.3 NDB API Example: Handling Errors and Retrying Transactions
2.5.4 NDB API Basic Scanning Example
2.5.5 NDB API Example: Using Secondary Indexes in Scans
2.5.6 NDB API Example: Using NdbRecord with Hash Indexes
2.5.7 NDB API Example Comparing RecAttr and NdbRecord
2.5.8 NDB API Event Handling Example
2.5.9 NDB API Example: Basic BLOB Handling
2.5.10 NDB API Example: Handling BLOB Columns and Values Using NdbRecord
2.5.11 NDB API Simple Array Example
2.5.12 NDB API Simple Array Example Using Adapter
2.5.13 Timestamp2 Example
2.5.14 Common Files for NDB API Array Examples
3.1 MGM API Concepts
3.1.1 Working with Log Events
3.1.2 Structured Log Events
3.2 MGM API Function Listing
3.2.1 Log Event Functions
3.2.2 MGM API Error Handling Functions
3.2.3 Management Server Handle Functions
3.2.4 Management Server Connection Functions
3.2.5 Cluster Status Functions
3.2.6 Functions for Starting & Stopping Nodes
3.2.7 Cluster Log Functions
3.2.8 Backup Functions
3.2.9 Single-User Mode Functions
3.3 MGM API Data Types
3.3.1 The ndb_mgm_node_type Type
3.3.2 The ndb_mgm_node_status Type
3.3.3 The ndb_mgm_error Type
3.3.4 The Ndb_logevent_type Type
3.3.5 The ndb_mgm_event_severity Type
3.3.6 The ndb_logevent_handle_error Type
3.3.7 The ndb_mgm_event_category Type
3.4 MGM API Structures
3.4.1 The ndb_logevent Structure
3.4.2 The ndb_mgm_node_state Structure
3.4.3 The ndb_mgm_cluster_state Structure
3.4.4 The ndb_mgm_reply Structure
3.5 MGM API Errors
3.5.1 Request Errors
3.5.2 Node ID Allocation Errors
3.5.3 Service Errors
3.5.4 Backup Errors
3.5.5 Single User Mode Errors
3.5.6 General Usage Errors
3.6 MGM API Examples
3.6.1 Basic MGM API Event Logging Example
3.6.2 MGM API Event Handling with Multiple Clusters
4 MySQL NDB Cluster Connector for Java
4.1 MySQL NDB Cluster Connector for Java: Overview
4.1.1 MySQL NDB Cluster Connector for Java Architecture
4.1.2 Java and NDB Cluster
4.1.3 The ClusterJ API and Data Object Model
4.2 Using MySQL NDB Cluster Connector for Java
4.2.1 Getting, Installing, and Setting Up MySQL NDB Cluster Connector for Java
4.2.2 Using ClusterJ
4.2.3 Using Connector/J with NDB Cluster
4.3 ClusterJ API Reference
4.3.1 com.mysql.clusterj
4.3.2 com.mysql.clusterj.annotation
4.3.3 com.mysql.clusterj.query
4.3.4 Constant field values
4.4 MySQL NDB Cluster Connector for Java: Limitations and Known Issues
5 MySQL NoSQL Connector for JavaScript
5.1 MySQL NoSQL Connector for JavaScript Overview
5.2 Installing the JavaScript Connector
5.3 Connector for JavaScript API Documentation
5.3.1 Batch
5.3.2 Context
5.3.3 Converter
5.3.4 Errors
5.3.5 Mynode
5.3.6 Session
5.3.7 SessionFactory
5.3.8 TableMapping and FieldMapping
5.3.9 TableMetadata
5.3.10 Transaction
5.4 Using the MySQL JavaScript Connector: Examples
5.4.1 Requirements for the Examples
5.4.2 Example: Finding Rows
5.4.3 Inserting Rows
5.4.4 Deleting Rows
6 ndbmemcache—Memcache API for NDB Cluster
6.1 Overview
6.2 Compiling NDB Cluster with Memcache Support
6.3 memcached command line options
6.4 NDB Engine Configuration
6.5 Memcache protocol commands
6.6 The memcached log file
6.7 Known Issues and Limitations of ndbmemcache