The MySQL Cluster API Developer Guide

Version 3.0 (2010-11-04)

Copyright © 2003, 2010, Oracle and/or its affiliates. All rights reserved.

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 software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software 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 which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. MySQL is a trademark of Oracle Corporation and/or its affiliates, and shall not be used without Oracle's express written authorization. Other names may be trademarks of their respective owners.

This software and documentation may provide access to or information on 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. 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.

This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this material is subject to the terms and conditions of your Oracle Software License and Service Agreement, which has been executed and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle or as specifically provided below. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

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.

For more information on the terms of this license, for details on how the MySQL documentation is built and produced, or if you are interested in doing a translation, please visit

If you want 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.

The MySQL Cluster API Developer Guide

Document generated on: 2010-11-04 (revision: 23557)

This guide provides information for developers wishing to develop applications against MySQL Cluster. These include:

  • The low-level C++-language NDB API for the MySQL NDBCLUSTER storage engine

  • the C-language MGM API for communicating with and controlling MySQL Cluster management servers

  • The MySQL Cluster Connector for Java, which is a a collection of Java APIs introduced in MySQL Cluster NDB 7.1 for writing applications against MySQL Cluster, including JDBC, JPA, and ClusterJ.

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 NDBCLUSTER, such as communication protocols employed between nodes, filesystems used by data nodes, and error messages.

The information presented in this guide is current for recent MySQL Cluster NDB 6.2, NDB 6.3, NDB 7.0, and NDB 7.1 releases. You should be aware that there have been significant changes in the NDB API, MGM API, and other particulars in MySQL Cluster versions since MySQL 5.1.12.

Table of Contents

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 Column Class
2.3.2. The Datafile Class
2.3.3. The Dictionary Class
2.3.4. The Event Class
2.3.5. The Index Class
2.3.6. The LogfileGroup Class
2.3.7. The List Class
2.3.8. The Ndb Class
2.3.9. The NdbBlob Class
2.3.10. The NdbDictionary Class
2.3.11. The NdbEventOperation Class
2.3.12. The NdbIndexOperation Class
2.3.13. The NdbIndexScanOperation Class
2.3.14. The NdbInterpretedCode Class
2.3.15. The NdbOperation Class
2.3.16. The NdbRecAttr Class
2.3.17. The NdbScanFilter Class
2.3.18. The NdbScanOperation Class
2.3.19. The NdbTransaction Class
2.3.20. The Object Class
2.3.21. The Table Class
2.3.22. The Tablespace Class
2.3.23. The Undofile Class
2.3.24. The Ndb_cluster_connection Class
2.3.25. The NdbRecord Interface
2.3.26. The AutoGrowSpecification Structure
2.3.27. The Element Structure
2.3.28. The GetValueSpec Structure
2.3.29. The IndexBound Structure
2.3.30. The Key_part_ptr Structure
2.3.31. The NdbError Structure
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.4. NDB API Examples
2.4.1. Using Synchronous Transactions
2.4.2. Using Synchronous Transactions and Multiple Clusters
2.4.3. Handling Errors and Retrying Transactions
2.4.4. Basic Scanning Example
2.4.5. Using Secondary Indexes in Scans
2.4.6. Using NdbRecord with Hash Indexes
2.4.7. Comparing RecAttr and NdbRecord
2.4.8. NDB API Event Handling Example
2.4.9. Basic BLOB Handling Example
2.4.10. Handling BLOBs Using NdbRecord
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. Package com.mysql.clusterj
4.3.2. Package com.mysql.clusterj.annotation
4.3.3. Package com.mysql.clusterj.query
4.4. MySQL Cluster Connector for Java: Limitations and Known Issues
5. MySQL Cluster API Errors
5.1. MGM API Errors
5.1.1. Request Errors
5.1.2. Node ID Allocation Errors
5.1.3. Service Errors
5.1.4. Backup Errors
5.1.5. Single User Mode Errors
5.1.6. General Usage Errors
5.2. NDB API Errors and Error Handling
5.2.1. Handling NDB API Errors
5.2.2. NDB Error Codes and Messages
5.2.3. NDB Error Classifications
5.3. ndbd Error Messages
5.3.1. ndbd Error Codes
5.3.2. ndbd Error Classifications
5.4. NDB Transporter Errors
6. MySQL Cluster Internals
6.1. MySQL Cluster File Systems
6.1.1. Cluster Data Node File System
6.1.2. Cluster Management Node File System
6.2. DUMP Commands
6.2.1. DUMP Codes 1 to 999
6.2.2. DUMP Codes 1000 to 1999
6.2.3. DUMP Codes 2000 to 2999
6.2.4. DUMP Codes 3000 to 3999
6.2.5. DUMP Codes 4000 to 4999
6.2.6. DUMP Codes 5000 to 5999
6.2.7. DUMP Codes 6000 to 6999
6.2.8. DUMP Codes 7000 to 7999
6.2.9. DUMP Codes 8000 to 8999
6.2.10. DUMP Codes 9000 to 9999
6.2.11. DUMP Codes 10000 to 10999
6.2.12. DUMP Codes 11000 to 11999
6.2.13. DUMP Codes 12000 to 12999
6.3. The NDB Protocol
6.3.1. NDB Protocol Overview
6.3.2. Message Naming Conventions and Structure
6.3.3. Operations and Signals
6.4. NDB Kernel Blocks
6.4.1. The BACKUP Block
6.4.2. The CMVMI Block
6.4.3. The DBACC Block
6.4.4. The DBDICT Block
6.4.5. The DBDIH Block
6.4.6. DBLQH Block
6.4.7. The DBTC Block
6.4.8. The DBTUP Block
6.4.9. DBTUX Block
6.4.10. The DBUTIL Block
6.4.11. The LGMAN Block
6.4.12. The NDBCNTR Block
6.4.13. The NDBFS Block
6.4.14. The PGMAN Block
6.4.15. The QMGR Block
6.4.16. The RESTORE Block
6.4.17. The SUMA Block
6.4.18. The TSMAN Block
6.4.19. The TRIX Block
6.5. MySQL Cluster Start Phases
6.5.1. Initialization Phase (Phase -1)
6.5.2. Configuration Read Phase (STTOR Phase -1)
6.5.3. STTOR Phase 0
6.5.4. STTOR Phase 1
6.5.5. STTOR Phase 2
6.5.6. NDB_STTOR Phase 1
6.5.7. STTOR Phase 3
6.5.8. NDB_STTOR Phase 2
6.5.9. STTOR Phase 4
6.5.10. NDB_STTOR Phase 3
6.5.11. STTOR Phase 5
6.5.12. NDB_STTOR Phase 4
6.5.13. NDB_STTOR Phase 5
6.5.14. NDB_STTOR Phase 6
6.5.15. STTOR Phase 6
6.5.16. STTOR Phase 7
6.5.17. STTOR Phase 8
6.5.18. NDB_STTOR Phase 7
6.5.19. STTOR Phase 9
6.5.20. STTOR Phase 101
6.5.21. System Restart Handling in Phase 4
6.5.22. START_MEREQ Handling
6.6. NDB Internals Glossary