ProjectPage mod ndb
| mod_ndb |
|
|---|
Contents |
[edit] About mod_ndb
Mod_ndb is an Apache module that provides a REST web services API for MySQL Cluster. It allows you to query and modify a database over HTTP using GET, POST, and DELETE requests, and retrieve results in many formats including JSON, XML, and HTML.
Mod_ndb supports MySQL Cluster versions 5.0, 5.1, and CGE, along with Apache httpd 1.3, 2.0, and 2.2.
An Apache web server running mod_ndb can join a MySQL Cluster as an API node and communicate directly with the cluster's data storage nodes. It will also properly interact with HTTP 1.1 caches and proxy servers. Altogether, mod_ndb provides many of the performance benefits of direct access to NDB, yet is much easier to use than the C++ NDB API. It can also interact directly with embedded Web application languages like PHP, Perl, and Ruby using Apache subrequests.
[edit] Important Links
- Project page at code.google.com, including downloads and issue tracking
- How to install and test mod_ndb
- Configuring mod_ndb
- Table of HTTP Requests and Responses
- Output Formats
- Scripting mod_ndb with PHP, Perl, or any Apache-embedded language
- Supported data types
- Project summary page on MySQL Forge
[edit] A Quick Example
A simple example can illustrate how mod_ndb might be used with MySQL Cluster.
[edit] Cluster Configuration
Each Apache proces that joins the cluster will connect to the cluster management server and obtain a Node ID. (Note that there is always a limit on the total number of nodes in a cluster, and because of this it may be best to run mod_ndb under a multi-threaded MPM in Apache 2.) In the cluster configuration file, you will need to define an API node for each Apache process. Empty "[API]" sections are sufficient for this, as follows:
[API] [API] [API]
[edit] Table Creation
A demonstration table can be created from a MySQL server.
CREATE DATABASE mod_ndb_test; USE mod_ndb_test; CREATE TABLE cars ( id INT NOT NULL PRIMARY KEY, make varchar(16) not null, model varchar(16), license_tag varchar(8), photo blob, index tag_idx (license_tag) ) engine=ndbcluster;
[edit] Configuration, requests, and responses
The majority of the information used to process and execute a request in mod_ndb is maintained in the Apache configuration file. Mod_nbd's configuration is similar to the PREPARE phase of many SQL APIs, when a developer can prepare a statement for execution and bind parameters to its variables. Later, the HTTP request, like the SQL EXECUTE phase, provides values for the named parameters. </p>
The following except from httpd.conf illustrates some ways to use the cars table.</p>
LoadModule ndb_module mod_ndb.so
AddModule mod_ndb.cc
ndb-connectstring = my_mgm_server
<Location /ndb>
SetHandler ndb-cluster
</Location>
<Location /ndb/car/>
Database car_db
Table cars
</Location>
<Location /ndb/car/by_id>
SELECT id, make, model, license_tag as tag from cars WHERE PRIMARY KEY = $id ;
PathInfo id
Format JSON
</Location>
<Location /ndb/car/photo>
PrimaryKey id
OrderedIndex tag_idx license_tag
Pathinfo license_tag
Columns photo
Format raw
DefaultType image/jpeg
</Location>
LoadModule and AddModule are used as with other Apache modules to load mod_ndb into the server. The subsequent ndb-connectstring directive indicates the location of the cluster management server .</p>
The remaining sections create a hierarchy of URL endpoints and describe how mod_ndb should generate response pages for them. The directive SetHandler ndb-cluster applies to all URLs beginning with /ndb. Subsequent Database and Table directives define database schemas and tables used at specific endpoints. </p>
At any given URL, users do not have complete or arbitrary access to an NDB table, but only the access explicitly allowed in the configuration file. That access is defined using a combination of N-SQL queries, such as the SELECT query shown at /ndb/car/by_id, and Apache-style configuration directives.
The N-SQL queries, PrimaryKey, UniqueIndex, and OrderedIndex directives enable requests to use particular named indexes. The request variables can be supplied in HTTP parameters, or mapped to the rightmost components of the URL using a PathInfo directive. The AllowUpdate directive specifies the columns that can be modified in an HTTP POST, and HTTP DELETE requests are allowed only if an explicit Deletes On directive or DELETE query enables them.
At /ndb/car/by_id, the configuration enables mod_ndb to respond to a request like /ndb/car/by_id?id=7 with the a row of results from the database. The additional line specifying "PathInfo id" maps the rightmost component of the URL to the id column, so that /ndb/car/by_id/7 will retrieve the same row. The result row will be returned in JSON format.</p>
Under the final configuration section, at /ndb/car/photo, only the BLOB column photo is returned, without any additional formatting. The DefaultType image/jpeg directive (which is handled by mod_mime, not mod_ndb) sets the MIME type of the response appropriately. Photos can be obtained using the primary key (/ndb/car/photo?id=3), the license number as an argument (/ndb/car/photo?license_tag=abc+123), or the license number as a part of the URL (/ndb/car/photo/abc+123).
[edit] More Examples
The example1 directory of the mod_ndb distribution contains a complete example, including sample data and a small test suite.
[edit] Configuring mod_ndb
A complete reference to mod_ndb configuration is available at Configuring_mod_ndb.
[edit] Subrequests, joins, and scripting
The Mod_ndb_scripting page describes in detail how mod_ndb can be used from an application language like PHP or Perl which is also embedded into the web server. In essence, the application code calls mod_ndb in an Apache subrequest, and then retrieves the result -- which would usually be sent to the browser -- from the Apache notes table. In the mod_ndb source distribution, the file htdocs/test_note.php contains an example.