MySQL Cluster API Developer Guide

MySQL Cluster API Developer Guide

This is the MySQL Cluster API Developer Guide, which provides information about developing applications using MySQL 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 MySQL Cluster management servers, and the MySQL Cluster Connector for Java, which is a collection of Java APIs introduced in MySQL Cluster NDB 7.1 for writing applications against MySQL Cluster, including JDBC, JPA, and ClusterJ.

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

MySQL Cluster NDB 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. 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 MySQL Cluster up to and including MySQL Cluster NDB 7.4.13. Due to significant functional and other changes in MySQL Cluster and its underlying APIs, you should not expect this information to apply to previous releases of the MySQL Cluster software prior to MySQL Cluster NDB 7.2. Users of older MySQL Cluster releases should upgrade to the latest available GA release of MySQL Cluster NDB 7.4.

For legal information, see the Legal Notices.

For help with using MySQL, please visit either the MySQL Forums or MySQL Mailing Lists, where you can discuss your issues with other MySQL users.

For additional documentation on MySQL products, including translations of the documentation into other languages, and downloadable versions in variety of formats, including HTML and PDF formats, see the MySQL Documentation Library.

Third-party licensing information.  This product may include third-party software, used under license. If you are using a Commercial release of MySQL Cluster, see this document for licensing information relating to third-party software that may be included in this Commercial release. If you are using a Community release of MySQL Cluster, see this document for licensing information relating to third-party software that may be included in this Community release.

Document generated on: 2016-09-16 (revision: 49023)


Table of Contents

Preface and Legal Notices
1 MySQL Cluster APIs: Overview and Concepts
1.1 MySQL Cluster API Overview: Introduction
1.1.1 MySQL Cluster API Overview: The NDB API
1.1.2 MySQL Cluster API Overview: The MGM API
1.2 MySQL 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 MySQL Cluster Concepts
1.3.4 The Adaptive Send Algorithm
2 The NDB API
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 Examples
2.4.1 NDB API Example Using Synchronous Transactions
2.4.2 NDB API Example Using Synchronous Transactions and Multiple Clusters
2.4.3 NDB API Example: Handling Errors and Retrying Transactions
2.4.4 NDB API Basic Scanning Example
2.4.5 NDB API Example: Using Secondary Indexes in Scans
2.4.6 NDB API Example: Using NdbRecord with Hash Indexes
2.4.7 NDB API Example Comparing RecAttr and NdbRecord
2.4.8 NDB API Event Handling Example
2.4.9 NDB API Example: Basic BLOB Handling
2.4.10 NDB API Example: Handling BLOB Columns and Values Using NdbRecord
2.4.11 NDB API Simple Array Example
2.4.12 NDB API Simple Array Example Using Adapter
2.4.13 Common Files for NDB API Array Examples
3 The MGM API
3.1 General Concepts
3.1.1 Working with Log Events
3.1.2 Structured Log Events
3.2 MGM C 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 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 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 Examples
3.5.1 Basic MGM API Event Logging Example
3.5.2 MGM API Event Handling with Multiple Clusters
4 MySQL Cluster Connector for Java
4.1 MySQL Cluster Connector for Java: Overview
4.1.1 MySQL Cluster Connector for Java Architecture
4.1.2 Java and MySQL Cluster
4.1.3 The ClusterJ API and Data Object Model
4.2 Using MySQL Cluster Connector for Java
4.2.1 Getting, Installing, and Setting Up MySQL Cluster Connector for Java
4.2.2 Using ClusterJ
4.2.3 Using JPA with MySQL Cluster
4.2.4 Using Connector/J with MySQL 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 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 MySQL Cluster
6.1 Overview
6.2 Compiling MySQL 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
7 MySQL Cluster API Errors
7.1 MGM API Errors
7.1.1 Request Errors
7.1.2 Node ID Allocation Errors
7.1.3 Service Errors
7.1.4 Backup Errors
7.1.5 Single User Mode Errors
7.1.6 General Usage Errors
7.2 NDB API Errors and Error Handling
7.2.1 Handling NDB API Errors
7.2.2 NDB Error Codes: by Type
7.2.3 NDB Error Codes: Single Listing
7.2.4 NDB Error Classifications
7.3 ndbd Error Messages
7.3.1 ndbd Error Codes
7.3.2 ndbd Error Classifications
7.4 NDB Transporter Errors
8 MySQL Cluster Internals
8.1 MySQL Cluster File Systems
8.1.1 MySQL Cluster Data Node File System
8.1.2 MySQL Cluster Management Node File System
8.2 MySQL Cluster Management Client DUMP Commands
8.2.1 DUMP 1
8.2.2 DUMP 13
8.2.3 DUMP 14
8.2.4 DUMP 15
8.2.5 DUMP 16
8.2.6 DUMP 17
8.2.7 DUMP 18
8.2.8 DUMP 20
8.2.9 DUMP 21
8.2.10 DUMP 22
8.2.11 DUMP 23
8.2.12 DUMP 24
8.2.13 DUMP 25
8.2.14 DUMP 70
8.2.15 DUMP 400
8.2.16 DUMP 401
8.2.17 DUMP 402
8.2.18 DUMP 403
8.2.19 DUMP 404 (OBSOLETE)
8.2.20 DUMP 908
8.2.21 DUMP 1000
8.2.22 DUMP 1223
8.2.23 DUMP 1224
8.2.24 DUMP 1225
8.2.25 DUMP 1226
8.2.26 DUMP 1228
8.2.27 DUMP 1229
8.2.28 DUMP 1332
8.2.29 DUMP 1333
8.2.30 DUMP 2300
8.2.31 DUMP 2301
8.2.32 DUMP 2302
8.2.33 DUMP 2303
8.2.34 DUMP 2304
8.2.35 DUMP 2305
8.2.36 DUMP 2308
8.2.37 DUMP 2315
8.2.38 DUMP 2350
8.2.39 DUMP 2352
8.2.40 DUMP 2354
8.2.41 DUMP 2398
8.2.42 DUMP 2399
8.2.43 DUMP 2400
8.2.44 DUMP 2401
8.2.45 DUMP 2402
8.2.46 DUMP 2403
8.2.47 DUMP 2404
8.2.48 DUMP 2405
8.2.49 DUMP 2406
8.2.50 DUMP 2500
8.2.51 DUMP 2501
8.2.52 DUMP 2502
8.2.53 DUMP 2503 (OBSOLETE)
8.2.54 DUMP 2504
8.2.55 DUMP 2505
8.2.56 DUMP 2506 (OBSOLETE)
8.2.57 DUMP 2507
8.2.58 DUMP 2508
8.2.59 DUMP 2509
8.2.60 DUMP 2510
8.2.61 DUMP 2511
8.2.62 DUMP 2512
8.2.63 DUMP 2513
8.2.64 DUMP 2514
8.2.65 DUMP 2515
8.2.66 DUMP 2516
8.2.67 DUMP 2517
8.2.68 DUMP 2550
8.2.69 DUMP 2555
8.2.70 DUMP 2600
8.2.71 DUMP 2601
8.2.72 DUMP 2602
8.2.73 DUMP 2603
8.2.74 DUMP 2604
8.2.75 DUMP 5900
8.2.76 DUMP 7000
8.2.77 DUMP 7001
8.2.78 DUMP 7002
8.2.79 DUMP 7003
8.2.80 DUMP 7004
8.2.81 DUMP 7005
8.2.82 DUMP 7006
8.2.83 DUMP 7007
8.2.84 DUMP 7008
8.2.85 DUMP 7009
8.2.86 DUMP 7010
8.2.87 DUMP 7011
8.2.88 DUMP 7012
8.2.89 DUMP 7013
8.2.90 DUMP 7014
8.2.91 DUMP 7015
8.2.92 DUMP 7016
8.2.93 DUMP 7017
8.2.94 DUMP 7018
8.2.95 DUMP 7019
8.2.96 DUMP 7020
8.2.97 DUMP 7021
8.2.98 DUMP 7024
8.2.99 DUMP 7033
8.2.100 DUMP 7080
8.2.101 DUMP 7090
8.2.102 DUMP 7098
8.2.103 DUMP 7099
8.2.104 DUMP 7901
8.2.105 DUMP 8004
8.2.106 DUMP 8005
8.2.107 DUMP 8010
8.2.108 DUMP 8011
8.2.109 DUMP 8013
8.2.110 DUMP 9002
8.2.111 DUMP 9800
8.2.112 DUMP 9801
8.2.113 DUMP 9802
8.2.114 DUMP 9803
8.2.115 DUMP 10000
8.2.116 DUMP 11000
8.2.117 DUMP 12001
8.2.118 DUMP 12002
8.2.119 DUMP 12009
8.3 The NDB Communication Protocol
8.3.1 NDB Protocol Overview
8.3.2 NDB Protocol Messages
8.3.3 Operations and Signals
8.4 NDB Kernel Blocks
8.4.1 The BACKUP Block
8.4.2 The CMVMI Block
8.4.3 The DBACC Block
8.4.4 The DBDICT Block
8.4.5 The DBDIH Block
8.4.6 The DBINFO Block
8.4.7 The DBLQH Block
8.4.8 The DBSPJ Block
8.4.9 The DBTC Block
8.4.10 The DBTUP Block
8.4.11 The DBTUX Block
8.4.12 The DBUTIL Block
8.4.13 The LGMAN Block
8.4.14 The NDBCNTR Block
8.4.15 The NDBFS Block
8.4.16 The PGMAN Block
8.4.17 The QMGR Block
8.4.18 The RESTORE Block
8.4.19 The SUMA Block
8.4.20 The THRMAN Block
8.4.21 The TRPMAN Block
8.4.22 The TSMAN Block
8.4.23 The TRIX Block
8.5 MySQL Cluster Start Phases
8.5.1 Initialization Phase (Phase -1)
8.5.2 Configuration Read Phase (STTOR Phase -1)
8.5.3 STTOR Phase 0
8.5.4 STTOR Phase 1
8.5.5 STTOR Phase 2
8.5.6 NDB_STTOR Phase 1
8.5.7 STTOR Phase 3
8.5.8 NDB_STTOR Phase 2
8.5.9 STTOR Phase 4
8.5.10 NDB_STTOR Phase 3
8.5.11 STTOR Phase 5
8.5.12 NDB_STTOR Phase 4
8.5.13 NDB_STTOR Phase 5
8.5.14 NDB_STTOR Phase 6
8.5.15 STTOR Phase 6
8.5.16 STTOR Phase 7
8.5.17 STTOR Phase 8
8.5.18 NDB_STTOR Phase 7
8.5.19 STTOR Phase 9
8.5.20 STTOR Phase 101
8.5.21 System Restart Handling in Phase 4
8.5.22 START_MEREQ Handling
8.6 NDB Schema Object Versions
8.7 NDB Internals Glossary
Index