MySQL® NDB API DEVELOPERS' GUIDE

VERSION 2.0 (2006-07-20)

Copyright 2003-2006 MySQL AB

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 MySQL disseminates it (that is, electronically for download on a website 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 MySQL AB. MySQL AB reserves any and all rights to this documentation not expressly granted above.

Please email for more information or if you are interested in doing a translation.

MySQL® NDB API DEVELOPERS' GUIDE

(revision: 2780)

Provides information for developers wishing to use the low-level C/C++-language NDB API for the MySQL® NDBCLUSTER storage engine. Includes concepts, terminology, programming class and structure references, practical examples, common problems, and tips for using the NDB API in applications.

The NDB and MGM APIs as presented in this guide are current for MySQL 5.1 — note that there have been significant changes in the API as implemented in previous MySQL Cluster versions. The definitions of NDB API classes and MGM API functions reflect the state of the MySQL main development tree as of MySQL 5.1.12 and later.


Table of Contents

1. OVERVIEW & CONCEPTS
1.1. Introduction
1.1.1. The NDB API
1.1.2. The MGM API
1.2. Terminology
1.3. The NDB Cluster 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. GETTING STARTED WITH THE NDB API
2.1. Compiling and Linking NDB API Programs
2.1.1. General Requirements
2.1.2. Compiler Options
2.1.3. Linker Options
2.1.4. Using Autotools
2.2. Connecting to the Cluster
2.2.1. Include Files
2.2.2. API Initialisation and Cleanup
2.2.3. Establishing the Connection
2.3. Mapping MySQL Database Object Names and Types to NDB
3. NDB API CLASSES
3.1. The Ndb Class
3.1.1. Ndb Class Methods
3.2. The Ndb_cluster_connection Class
3.2.1. Ndb_cluster_connection Class Methods
3.3. The NdbBlob Class
3.3.1. NdbBlob Types
3.3.2. NdbBlob Class Methods
3.4. The NdbDictionary Class
3.4.1. The Dictionary Class
3.4.2. The Column Class
3.4.3. The Object Class
3.4.4. The AutoGrowSpecification Structure
3.5. The NdbEventOperation Class
3.5.1. The NdbEventOperation::State Type
3.5.2. NdbEventOperation Class Methods
3.6. The NdbOperation Class
3.6.1. NdbOperation Types
3.6.2. NdbOperation Class Methods
3.6.3. The NdbIndexOperation Class
3.6.4. The NdbScanOperation Class
3.7. The NdbRecAttr Class
3.7.1. NdbRecAttr Class Methods
3.8. The NdbScanFilter Class
3.8.1. NdbScanFilter Types
3.8.2. NdbScanFilter Class Methods
3.9. The NdbTransaction Class
3.9.1. NdbTransaction Types
3.9.2. NdbTransaction Class Methods
4. NDB API ERRORS
4.1. The NdbError Structure
4.1.1. NdbError Types
4.2. NDB Error Codes, Classifications, and Messages
4.2.1. NDB Error Codes and Messages
4.2.2. NDB Error Classifications
5. THE MGM API
5.1. General Concepts
5.1.1. Working with Log Events
5.1.2. Structured Log Events
5.2. MGM C API Function Listing
5.2.1. Log Event Functions
5.2.2. MGM API Error Handling Functions
5.2.3. Management Server Handle Functions
5.2.4. Management Server Connection Functions
5.2.5. Cluster Status Functions
5.2.6. Functions for Starting & Stopping Nodes
5.2.7. Cluster Log Functions
5.2.8. Backup Functions
5.2.9. Single-User Mode Functions
5.3. MGM Datatypes
5.3.1. The ndb_mgm_node_type Type
5.3.2. The ndb_mgm_node_status Type
5.3.3. The ndb_mgm_error Type
5.3.4. The Ndb_logevent_type Type
5.3.5. The ndb_mgm_event_severity Type
5.3.6. The ndb_logevent_handle_error Type
5.3.7. The ndb_mgm_event_category Type
5.4. MGM Structures
5.4.1. The ndb_logevent Structure
5.4.2. The ndb_mgm_node_state Structure
5.4.3. The ndb_mgm_cluster_state Structure
5.4.4. The ndb_mgm_reply Structure
6. PRACTICAL EXAMPLES
6.1. Using Synchronous Transactions
6.2. Handling Errors and Retrying Transactions
6.3. Basic Scanning Example
6.4. Using Secondary Indexes in Scans
6.5. NDB API Event Handling Example
Index