CUBRID APIs Wiki

CUBRID ODBC Driver Release Notes

2012-01-04T00:10:48-08:00

CUBRID ODBC Driver 9.1.0.p1 Release Note(2013-05-06)

Download: http://ftp.cubrid.org/CUBRID_Drivers/ODBC_Driver/

Changed and Enhanced Features:

APIS-184 - ODBC] how to do auto_commit off in C#

Fixed bugs:

APIS-152 - ODBC] Error when executing a query in Korean
APIS-155 - Run time error when selecting in CUBRID ODBC Driver
APIS-156 - user reported> ODBC driver has a Fetch error
APIS-443 - Fetch error in using openrowset() call in sql server
APIS-445 - sql server core dump if openrowset() call on numeric field from ODBC driver
APIS-536 - ODBC] The returned value of OdbcConnection.Database is incorrect
APIS-538 - ODBC] A problem of the returned value of OdbcConnection.DataSource property
APIS-539 - ODBC] OdbcDataReader.GetDataTypeName doesn't work
APIS-540 - ODBC] OdbcDataReader GetInt16, GetInt32 doesn't returns expected exception when read an overbound integer

CUBRID ODBC Driver 9.1.0 Release Note

Functionality added or changed:

The following ODBC APIs are newly supported by CUBRID ODBC:

SQLPrimaryKeys
SQLForeignKeys
SQLProcedures
SQLProcedureColumns
SQLTablePrivileges

All four functions are catalog functions, which can get schema information of database you connect to. CUBRID schema information is stored in system catalog table, so you can also get this information from system catalog virtual table using SQL statement.

Database schema information is important for data modeling tools like CA ERwin Data Modeler, which enables you to visualize complex data structures. It uses schema information, for example, tables of database, columns and attributes of table, the primary and foreign keys of table, and relationships between tables and so on, to get the structure of the database.

SQLPrimaryKeys returns the column names that make up the primary key for a table.
SQLForeignKeys can return:
1. A list of foreign keys in the specified table (columns in the specified table that refer to primary keys in other tables).
2. A list of foreign keys in other tables that refer to the primary key in the specified table.
SQLProcedures returns returns the list of function/procedure names stored in a specific data source.
1. Stored functions/procedures are blocks of code that have a flow of commands for data manipulation and are easy to manipulate and administer. CUBRID supports to develop stored functions and procedures in Java. Java stored functions/procedures are executed on the JVM (Java Virtual Machine) hosted by CUBRID.
SQLProcedureColumns returns the list of input and output parameters for the specified procedures, but not including the return columns.
SQLTablePrivileges returns a list of tables and the privileges associated with each table, which represents authorization information of the classes for which the current user has authorization in the database.

Fixed bugs:

SQLFetchScroll: When parameter FetchOrientation is SQL_FETCH_LAST, SQLFetchScroll should return the last complete rowset in the result set. But it will return the first, not the last.
- SQLFetchScroll is used to fetches the specified rowset of data from the result set and returns data for all bound columns. Rowsets can be specified at an absolute or relative position or by bookmark.
SQLSetPos: Application will crash when calling SQLSetPos.
- SQLSetPos sets the cursor position in a rowset and allows an application to refresh, update or delete data in the result set.
SQLSetPos: The default value of statement attribute SQL_ATTR_ROW_ARRAY_SIZE is 1, which is the number of rows returned by each call to SQLFetch or SQLFetchScroll. If we set this attribute to value that is more than 1, SQLSetPos can't work correctly.
SQLStatistics and SQLSpecialColumns: The results of the two catalog functions are not valid.

SQLStatistics retrieves a list of statistics about a single table and the indexes associated with the table. SQLSpecialColumns retrieves the following information about columns within a specified table:
- When IdentifierType is SQL_BEST_ROWID, it will return information of columns that uniquely identifies a row in the table;
- When IdentifierType is SQL_ROWVER, it will return information of columns that are automatically updated when any value in the row is updated by a transaction.
  
  No data type in CUBRID will auto-update, so it only can return the columns which compose the unique keys.

CUBRID OLEDB Driver Release Notes

2012-04-23T01:27:38-07:00

CUBRID OLEDB Driver 9.1.0.p1 Release Note (2013-05-06)

Download: http://ftp.cubrid.org/CUBRID_Drivers/OLEDB_Driver

Fixed bugs:

APIS-390 - Requesting schema_info unnecessarily
APIS-398 - OLEDB] The previous Connection String doesn't work when connecting to a remote CUBRID
APIS-406 - OLEDB] provider 64bit doesn't work well - CLONE from CUBRIDSUS
APIS-407 - OLEDB] Supporting Charset setting in OLEDB Provider
APIS-457 - OLEDB] Some warnings in Test Connection, if using 64bit provider
APIS-490 - When using CursorLocation = adUseClient, it is crashed!
APIS-531 - OLEDB] OleDbCommand.ExecuteReader(CommandBehavior) problem
APIS-534 - OLEDB] return value of OleDbDataAdapter.Fill(DataTable) is not right
APIS-535 - OLEDB]if use Reader.GetBoolean to get a bit data, it will throw an exception
APIS-541 - OLEDB] rollback of OleDbTransaction is not work

CUBRID OLEDB Driver 9.1.0 Release Note

Updates summary since beta release
=================================================

2 new schema rowsets added (Catalog and SQL language)
New test cases added (localization, data types handling, extended connect)
Changed the login internal procedure to use the connect_with_url CCI function; additional parameters included (login & query timeout, auto-commit)
64-bit driver library available for download
Various updates in the source code; more code cleanup
Additional resources made available (new tutorial and short video)
Some improvements in LOB handling
New Installer version

General development notes
=================================================

The 8.4.1 provider code is based on the legacy CUBRID 3.1 OLE DB provider code
Various enhancements and support for latest CUBRID releases has been implemented
We have focused on supporting OLE DB Consumer templates (http://msdn.microsoft.com/en-us/library/8k76sd16%28v=vs.80%29.aspx). Direct OLE DB interfaces should work as well, but the technology is deprecated.
A full suite of open source test cases is now part of the driver code base release
Regarding .NET support (via System.Data.OleDb namespace), we are encouraging the use of the fully managed CUBRID ADO.NET driver instead (http://www.cubrid.org/wiki_apis/entry/cubrid-ado-net-driver).
The code is released under the BSD license (http://www.cubrid.org/bsd_license).

Release components

==============================================

The driver source code (http://svn.cubrid.org/cubridapis/oledb/branches/RB-8.4.1/Source/)
The driver OLE DB Data Provider compiled library x32/x64 release (CUBRIDProvider.dll)
Win32 Driver Installer (with a short video)
Release notes
Test cases suite : 60+ OLE DB Consumer test cases (see the attachments for a test suite run output)
3 Tutorials

Known limitations
=================================================

There is limited support for queries not based on tables structures, in terms of columns automatic definitions
There is no full support yet for BLOB/BLOB Dynamic Accessors
Update() support is restricted to Auto-Commit mode = Off, which must be explicitly stated via session transaction.
Not all schema are implemented as defined here: http://msdn.microsoft.com/en-us/library/a6fhbff0%28v=vs.71%29.aspx.
More test coverage is required for testing non-standard data types
We are supporting mainly C++ OLE DB templates; there is limited or no support for other driver usages (direct interfaces
Very limited support for some special data types: SET, MUTISET and SEQUENCE

What's next/To-Do
=================================================

Re-Generate and publish the Doxygen driver documentation
Continue to improve support for BLOB/CLOB
Make available in write-mode additional connection properties: loging & query timeouts
Add more test cases coverage, in particular for CUBRID specific data types and for .NET OleDb access.
Remove the data provider distribution from the CUBRID standard installer
Continue SVN cleanup and update Trunk

CUBRID OLEDB Driver 9.1.0.p1 Release Note

2013-05-03T18:44:35-07:00

9.1.0.p1

Fixed bugs:

[APIS-390] - 수행하지 않는(필요없는) schema_info 요청
[APIS-398] - OLEDB] Driver를 사용하여 원격지의 CUBRID 연결 시 기존 Connection String이 적용되지 않음
[APIS-406] - OLEDB] provider 64비트가 정상동작하지 않음 - CLONE from CUBRIDSUS
[APIS-407] - OLEDB] OLEDB 프로바이더에 charset 지정 가능하도록 수정
[APIS-457] - OLEDB] Some warnings in Test Connection, if using 64bit provider
[APIS-490] - When using CursorLocation = adUseClient, it is crashed!
[APIS-531] - OLEDB] OleDbCommand.ExecuteReader(CommandBehavior) problem
[APIS-534] - OLEDB] return value of OleDbDataAdapter.Fill(DataTable) is not right
[APIS-535] - OLEDB]if use Reader.GetBoolean to get a bit data, it will throw an exception
[APIS-541] - OLEDB] rollback of OleDbTransaction is not work

CUBRID OLEDB Driver

2012-01-04T23:10:15-08:00

OLE DB (Object Linking and Embedding, Database) is an API designed by Microsoft for accessing data from a variety of sources in a uniform manner, thus can be used by all Microsoft platforms. It is a set of interfaces implemented using the Component Object Model (COM).

.NET Framework is a software framework for Microsoft Windows operating systems. It includes a large library, and it supports several programming languages which allows language interoperability (each language can utilize code written in other languages). The .NET library is available to all the programming languages that .NET supports. A data provider in the .NET Framework serves as a bridge between an application and a data source; a data provider is used to retrieve data from a data source and to reconcile changes to that data back to the data source.

OLEDB driver source code is distributed under the terms of BSD open source license.

CUBRID ODBC Driver

2011-08-15T04:11:55-07:00

If you want to use CUBRID as a data source for your Windows applications using the ODBC Driver, follow tutorials provided in this project page.

CUBRID ODBC driver supports ODBC version 3.52, ODBC core, and some of Level 1 and Level 2 APIs. Since it has been developed based on ODBC Spec 3.x, backward compatibility is not completely ensured for programs written using ODBC Spec 2.x.

ODBC driver source code is distributed under the terms of BSD open source license.

CUBRID OLEDB Driver Installation Instructions

2013-04-26T01:39:49-07:00

The scope of this tutorial is to provide an introduction to the CUBRID OLEDB Data Provider. We will show you where to get the CUBRID OLEDB Provider library, how to setup a CUBRID connection and how to develop some simple applications, mainly using OLE DB Consumer templates.

Notice: If your CUBRID OLEDB driver version is 9.1.0.p1 or later, only one installation package is needed for both Windows 32 bit and 64 bit. Our new OLEDB installer supports CUBRID DB engine 8.4.1 or later.

If your CUBRID OLEDB Driver version is 9.1.0 or older, it may have a problem on 64 bit operating system. Please see our installation tutorial for an old version: http://www.cubrid.org/wiki_apis/entry/cubrid-oledb-driver-installation-instructions-old

Download

Download a new installation package file which name is "CUBRID_OLEDB_Provider-<version>-win32-x64.zip".

It will install both CUBRIDProvider32.dll and CUBRIDPRovider64.dll at once. You can find a CUBRID OLEDB Provider installer at:

http://ftp.cubrid.org/CUBRID_Drivers/OLEDB_Driver/ or

http://www.cubrid.org/?mid=downloads&item=oledb_driver

Driver Installation

Run a CUBRID OLEDB Provider Installer (exe) and click the Next / Install Button.

In your installation directory, you can see the following DLL files and uninstall. exe.

DB Connection

Data Link Properties Dialog Box

To access this dialog box in Visual Studio .NET, select Connect to Database from the Tools menu or click the Connect to Database icon in Server Explorer.
You also can open this dialog box by double-clicking a universal data link (.udl) file in Windows Explorer, and in a variety of other ways, including programmatically.

1）you must install Visual Studio first, click “Connect to Database”

2) Choose <other>,and .Net Famework Data Provider for OLE DB, Then click continue button

3) Choose CUBRID OLE DB Provider, then click Data links button

4) Fill in the information, and click Test Connection button, if driver connect database successful, success dialog will pop up.
More information can found in msdn: http://msdn.microsoft.com/en-us/library/79t8s5dk(v=vs.71).aspx

5) A simple method of open dialog
First, create a text file, and modify extension to *.udl: 1.txt -> 1.udl

Second, double click 1.udl, dialog will pop up.

6) Setting method of character set

Connection String:

"Provider=CUBRIDProvider;Data Source=demodb;Location=10.34.64.104;User ID=dba;Password=;Port=30000;Fetch Size=100;Charset=utf-8;"

Configuration

The following tutorials will help you when developing your application thru CUBRID OLEDB Provider.

Installing CUBRID PHP Driver using PECL

2011-12-29T21:18:19-08:00

If PECL packager is installed in your system, the installation of CUBRID PHP Driver is straightforward. PECL will download and compile the library for you.

Requirements

To install the PHP Driver using PECL, you need to have CUBRID Database installed in your system since PHP Driver is dependent on CUBRID CCI API.

Installation

Type the following command to install the latest version of CUBRID PHP Driver.

sudo pecl install cubrid

If you need older version of the driver, you can indicate its exact version like:

sudo pecl install cubrid-8.3.0.0005

During the installation you will be prompted to enter "CUBRID base install dir [!autodetect] :". Just to make sure your installation goes smoothly, enter the full path to the directory where you have installed CUBRID. Ex: if CUBRID was installed at /home/cubridtest/CUBRID, then enter /home/cubridtest/CUBRID.

a) If you have Centos 6.0 and above or Fedora 15 and above, then do not edit the php.ini as stated in step b and instead create a file named cubrid.ini in which you add only the line extension=cubrid.so. This file has to be placed in the /etc/php.d folder.

b) Edit the php.ini (default location: /etc/php5/apache2/php.ini or /etc/php.ini) and add the following two lines at the end of the file.

[!CUBRID] extension=cubrid.so

To apply the changes, restart your Web Server.

What If I don't have PECL installed?

If you do not have PECL installed, follow these instructions to get it installed in your system.

Ubuntu Instructions

In order to install CUBRID-PHP API on Ubuntu, you will need PHP Development Tools (phpize) and pear packager.

Type the following command to install phpize:
```
sudo apt-get install php5-dev
```
Type the following command to install pear package:
```
sudo apt-get install php-pear
```

Then follow the above instructions to install CUBRID PHP Driver.

Fedora/CentOS Instructions

In order to install CUBRID-PHP API on Fedora/CentOS, you will need PHP PEAR and phpize packages.

Install phpize. Remember that php-dev should be either PHP 5.2.x compatible or PHP 5.3.x since CUBRID-PHP Extension is developed for these PHP versions. If your Linux distribution installs earlier version, you need to update it.
```
yum install php-devel
```
Download PEAR package:
```
wget http://pear.php.net/go-pear.phar
```
Run PEAR package with PHP:
```
php go-pear.phar
```

What's Next?

Refer to CUBRID PHP Tutorials

CUBRID Sharding with node-cubrid 2.0

2013-03-26T23:53:17-07:00

In this guide we will go through the process of setting up a CUBRID SHARD environment and using the CUBRID Node.js 2.0 driver to insert and retrieve data from the shard DB nodes.

If you are not familiar with the CUBRID Node.js driver yet, check out our CUBRID Node.js Tutorials. Same goes for the CUBRID SHARD basic concepts – see CUBRID SHARD.

Setting up the CUBRID SHARD environment

The first thing we need to do is set up the CUBRID SHARD and the shard databases architecture. For simplicity we will use two shard DB nodes.

So let’s get right to it. First, in each shard DB node we will create a database and a user account, and start the database:

Shard DB name: sharddb
Shard DB user account: shard
Shard DB user password: shard123

To do this, we will use the CUBRID command line tool “csql”. In each shard DB node, type the following commands:

# Creating CUBRID SHARD DB
cubrid createdb sharddb

# Creating CUBRID SHARD user account
csql -S -u dba sharddb -c "create user shard password 'shard123'"

# Starting CUBRID SHARD DB
cubrid server start sharddb

Next, we have to change the shard configurations. In the node that we choose to be the shard server we have to edit three shard configuration files located in the \CUBRID\conf directory:

shard.conf
shard_connection.txt
shard_key.txt

The first file, shard.conf, contains the shard broker parameters. The only thing to do here is to make sure that the following parameters are set:

SHARD_DB_NAME        = sharddb
SHARD_DB_USER        = shard
SHARD_DB_PASSWORD    = shard123

In the second file - shard_connection.txt, we will configure the network addresses of the shard DB nodes. In our setup, one node is on the same machine as the shard server, and the other one is located somewhere else in the local area network.

# shard-id  	real-db-name  		connection-info
0           		sharddb       		localhost
1           		sharddb      		10.0.0.186

Make sure that you set the correct IP address for the second shard DB node.

The last file that we need to configure is shard_key.txt. This file configures the shard DB mapping configuration, for the shard key hash value, as follows:

[!%shard_key]: Sets the shard key section
min: The minimum value range of the shard key hash results.
max: The maximum range of the shard key hash results.
shard_id: The shard identifier

[!%shard_key]
#min		max		shard_id
0		127      		0
128		255     		1

This configuration means that an INSERT statement will execute on shard 0 when the shard key hash result created by default hash function is between 0 and 127, and will execute on shard 1 when the shard key hash result created by the default hash function is between 128 and 255.

We are now ready to start the CUBRID SHARD service:

cubrid shard start
@ cubrid shard start
++ cubrid shard start: success

We have one more step to complete before we can use Node.js with CUBRID SHARD – prepare our test data.

Let’s create a table in each shard DB:

csql -C -u shard -p 'shard123' sharddb@localhost -c "create table student (s_no int, s_name varchar, s_age int, primary key(s_no))"

Using the CUBRID Node.js 2.0 driver with CUBRID SHARD

The code examples we will show in this guide use the CUBRID Node.js 2.0 driver to perform the followings operations:

Connect to the shard broker
Insert data into the shard DB nodes
Query the data we inserted

Inserting data:

Let’s see how to insert data into the shard DB nodes:

var CUBRID = require('node-cubrid'),
  Helpers = CUBRID.Helpers,
  ActionQueue = CUBRID.ActionQueue;

var client = CUBRID.createCUBRIDConnection('localhost', 45011, 'shard', 'shard123', 'sharddb');
ActionQueue.enqueue(
  [
    function (cb) {
      client.connect(cb);
    },
    function (cb) {
      Helpers.logInfo('Connected.');
      var i = 0;
      ActionQueue.while(
        function () {
          return i < 255;
        },
        function (cb) {
          Helpers.logInfo('Executing insert number ' + i + '.');
          client.executeWithTypedParams('INSERT INTO student VALUES (/*+ shard_key */ ?,?,?)', [i, 'name_' + i, 20 + i % 8], // i % 8 to set the age of the student between 20 and 27
            ['int', 'varchar', 'int'], function () {
              client.commit(function () {
                i++;
                cb.call();
              });
            });
        },
        function () {
          cb.call();
        }
      );
    },
    function (cb) {
      client.close(cb);
    }
  ],
  function () {
    Helpers.logInfo('Connection closed.');
  }
);

The output is:

Connected.
Executing insert number 0.
Executing insert number 1.
Executing insert number 2.
Executing insert number 3.
(…)
Executing insert number 251.
Executing insert number 252.
Executing insert number 253.
Executing insert number 254.
Connection closed.

As you can see, there are a few differences in the above code when compared to connecting and inserting in a “normal” CUBRID database setup. The most important one is the connection port. By default, the CUBRID SHARD broker port is 45011, but you can change it in the shard.conf file.

Another key difference is in the INSERT statement that we execute. Here we have to specify the shard_key column using a shard SQL hint. It will tell the shard broker which shard DB to choose according to the setup we made in the shard_key.txt file.

Tip: For more information about shard SQL hints see Selecting a Shard DB through the Shard SQL Hint.

So, let’s see what CUBRID SHARD did when it executed these statements, by checking the shard broker log file located in \CUBRID\log\broker\proxy_log:

Select shard. (shard_id:0, key_column:[shard_key_column], shard_key_id:0).
Select shard. (prev_shard_id:-1, curr_shard_id:0). context(cid:1, uid:12, is_busy:Y, is_in_tran:N, is_prepare_for_execute:N, free_on_end_tran:N, free_on_client_io_write:N, free_context:N, is_client_in_tran:Y, is_cas_in_tran:N, is_bypass_msg:N, waiting_event:((nil), -), func_code:-1, stmt_h_id:-1, stmt_hint_type:-1, wait_timeout:30, client_id:1, shard_id:-1, cas_id:-1, error_ind:0, error_code:0, error_msg:[-] ).
As expected, the CUBRID SHARD broker selected our first shard node and ran the statement on it. It is the same for the first 127 queries. So what about query number 128 and next?
Select shard. (shard_id:1, key_column:[shard_key_column], shard_key_id:4).
Select shard. (prev_shard_id:-1, curr_shard_id:1). context(cid:1, uid:12, is_busy:Y, is_in_tran:N, is_prepare_for_execute:N, free_on_end_tran:N, free_on_client_io_write:N, free_context:N, is_client_in_tran:Y, is_cas_in_tran:N, is_bypass_msg:N, waiting_event:((nil), -), func_code:-1, stmt_h_id:-1, stmt_hint_type:-1, wait_timeout:30, client_id:1, shard_id:-1, cas_id:-1, error_ind:0, error_code:0, error_msg:[-] ).
For the 128th INSERT statement (“INSERT INTO student VALUES (/*+ shard_key */ 128,’name_128’,20)”) the broker selected the other shard node since according to our shard_key.txt configuration, INSERT statements with the key column value (here s_no = 128) bigger than 127 will execute on the second shard DB node.

Querying the CUBRID SHARD DB nodes

In the next section we will learn how to retrieve the data from our shard DB nodes. The only thing that is different here is that CUBRID SHARD uses the (old) 8.4.x TCP protocol for query execution, so before we can run a query we have to tell Node.js driver to use this protocol by calling the setEnforceOldQueryProtocol() method. Now we can execute our queries, again using the shard SQL hints:

var CUBRID = require('node-cubrid'),
  Helpers = CUBRID.Helpers,
  ActionQueue = CUBRID.ActionQueue,
  Result2Array = CUBRID.Result2Array;

var client = CUBRID.createCUBRIDConnection('localhost', 45011, 'shard', 'shard123', 'sharddb');
ActionQueue.enqueue(
  [
    function (cb) {
      client.connect(cb);
    },
    function (cb) {
      client.setEnforceOldQueryProtocol(true);
      Helpers.logInfo('Querying: select * from student /*+ shard_id(0) */');
      client.query('select * from student /*+ shard_id(0) */', cb);
    },
    function (result, queryHandle, cb) {
      Helpers.logInfo('Resutls from the first shard (shard_id = 0):');
      Helpers.logInfo('Query result rows count: ' + Result2Array.TotalRowsCount(result));
      var arr = Result2Array.RowsArray(result);
      for (var j = 0; j < arr.length; j++) {
        Helpers.logInfo(arr[j].toString());
      }
      client.closeQuery(queryHandle, cb);
    },
    function (queryHandle, cb) {
      client.close(cb);
    }
  ],
  function () {
  }
);

Here we used the /*+ shard_id(0) */ SQL hint to specify which shard DB we are targeting. As expected, we have retrieved the data from the first shard DB node:

Querying: select * from student /*+ shard_id(0) */
Results from the first shard (shard_id = 0):
Query result rows count: 128
0,name_0,20
1,name_1,21
2,name_2,22
3,name_3,23
(…)
124,name_124,24
125,name_125,25
126,name_126,26
127,name_127,27

To get the data from the other shard DB the only thing we have to change is the parameter of the SQL hint to 1: /*+ shard_id(1) */ and we will get the desired results:

Querying: select * from student /*+ shard_id(1) */
Results from the first shard (shard_id = 1):
Query result rows count: 127
128,name_128,20
129,name_129,21
130,name_130,22
131,name_131,23
(…)
251,name_251,23
252,name_252,26
253,name_253,25
254,name_254,26

What if we want to get data from an invalid shard id, for example if we run “select * from student /*+ shard_id(2) */”? The shard broker will obviously return an error. So let’s look at the log file after we ran this query:

Create new sql statement. (index:0). statement(index:0, num_alloc:1, stmt_h_id:0, status:1, context id:0, context uid:1, num pinned:0, lru_next:(nil), lru_prev:(nil), sql_stmt:[select * from student /*+ shard_id(2) */]). context(cid:0, uid:1, is_busy:Y, is_in_tran:N, is_prepare_for_execute:N, free_on_end_tran:N, free_on_client_io_write:N, free_context:N, is_client_in_tran:Y, is_cas_in_tran:N, is_bypass_msg:N, waiting_event:((nil), -), func_code:-1, stmt_h_id:-1, stmt_hint_type:-1, wait_timeout:30, client_id:0, shard_id:-1, cas_id:-1, error_ind:0, error_code:0, error_msg:[-] ).
Invalid shard/CAS id is requested. (shard_id:2, cas_id:-1).
send error(msg) to the client. (error_ind:-1, error_code:-1001, errro_msg:-)

References and links

CUBRID Node.js driver home page	https://github.com/CUBRID/node-cubrid https://github.com/organizations/CUBRID
Online driver documentation	https://github.com/CUBRID/node-cubrid/tree/master/documentation
Online Wiki	http://www.cubrid.org/wiki_apis/entry/cubrid-node-js-driver
Driver tutorials and examples	http://www.cubrid.org/wiki_apis/entry/cubrid-node-js-tutorials
CUBRID SHARD documentation	http://www.cubrid.org/manual/843/en/CUBRID%20SHARD
Database Sharding the right way: Easy, Reliable and Open source	http://www.slideshare.net/cubrid/database-sharding-the-right-way-easy-reliable-and-open-source-highload-2012
Selecting a Shard DB through the Shard SQL Hint	http://www.cubrid.org/manual/90/en/Selecting%20a%20Shard%20DB%20through%20the%20SHARD%20SQL%20Hint

We hope you enjoyed using the CUBRID Node.js 2.0 driver in a sharding environment!

Please let us know your feedback and suggestions, so we can improve! And do not forget, tryout the CUBRID Node.js 2.0 driver!

CUBRID PDO Driver Installation Instructions

2012-01-03T17:29:09-08:00

There are several ways to install CUBRID PDO Driver. Below you will see instructions for each of them.

[Installing CUBRID PDO Driver using PECL] (Linux)
[Downloading and Installing Precompiled CUBRID PHP/PDO Driver (Windows)]
Create a CUBRID Database VM with Vagrant and Chef Cookbook under 5 minutes (Linux)
[Build CUBRID PDO Driver on Mac OS X through PECL using CCI Driver] (Mac OS X)

Installing CUBRID PDO Driver using PECL

2012-01-03T17:15:06-08:00

If PECL packager is installed in your system, the installation of CUBRID PDO Driver is straightforward. PECL will download and compile the library for you.

Requirements

To install the PDO Driver using PECL, you need to have CUBRID Database installed in your system since PDO Driver is dependent on CUBRID CCI API.

Installation

Type the following command to install the latest version of CUBRID PDO Driver.

sudo pecl install pdo_cubrid

If you need older version of the driver, you can indicate its exact version like:

sudo pecl install pdo_cubrid-8.3.1.0003

During the installation you will be prompted to enter "CUBRID base install dir [!autodetect] :". Just to make sure your installation goes smoothly, enter the full path to the directory where you have installed CUBRID. Ex: if CUBRID was installed at /home/cubridtest/CUBRID, then enter /home/cubridtest/CUBRID.

a) If you have Centos 6.0 and above, Fedora 15 and above, or Ubuntu 13.04 and above, create a file named pdo_cubrid.ini in /etc/php5/conf.d/ or /etc/php.d (check where in your system other .ini files are located).

b) Otherwise, edit the php.ini (default location: /etc/php5/apache2/php.ini or /etc/php.ini).

Then in the above .ini file add the following line:

extension=pdo_cubrid.so

To apply the changes, restart your Web Server.

What If I don't have PECL installed?

Install PECL packager

What's Next?

Refer to CUBRID PDO Tutorials

Build CUBRID PDO Driver on Mac OS X through PECL using CCI Driver

2013-05-07T23:11:14-07:00

In this tutorial you will learn how to install CUBRID PDO driver on Mac OS X through PECL repository using CUBRID CCI driver.

Download CCI driver

CUBRID PDO driver has a dynamic dependency on CCI driver. You can download either 64 or 32 bit version of CUBRID CCI diver depending on your Mac OS architecture. Once you download it, you need to copy the contents of the /lib directory to /usr/lib and the contents of /include directory to /usr/include. The following example illustrates how to extract a 64-bit version and copy its contents.

tar zxvf CUBRID-CCI-8.4.1.4009-x64.macosx.tar.gz
sudo cp CUBRID-CCI-8.4.1.4009-x64/lib/* /usr/lib
sudo cp CUBRID-CCI-8.4.1.4009-x64/include/* /usr/include

Install PDO driver using PECL

Type the following command to install the latest version of CUBRID PDO Driver from PECL repository.

sudo pecl install pdo_cubrid

If you need older version of the driver, you can indicate its exact version like:

sudo pecl install pdo_cubrid-8.4.3.0001

During the installation you will be prompted to enter "CUBRID base install dir [!autodetect]:". Enter that same directory where we have extracted CUBRID CCI driver files.

CUBRID base install dir [!autodetect] : /usr

Configure php.ini

Now find the php.ini file and add the following line which instructs your Web server or FastCGI Process Manager to load CUBRID PDO extension with the next restart.

extension=pdo_cubrid.so

Done! Now restart your Web server to load CUBRID extension.

Test CUBRID PHP API

Create a simple test.php file with the following contents:

<?php phpinfo(); ?>

In your browser visit http://localhost/test.php. Search for "pdo_cubrid". You should see entries like Version, CCI Version, and CUBRID Version.

If you have any questions, please ask them at our Q&A site. If any issues with installation, post on our forum.

CUBRID OLEDB Driver Installation Instructions Old

2012-04-23T01:36:40-07:00

The scope of this tutorial is to provide an introduction to the CUBRID OLEDB Data Provider, version 8.4.1. We will show you where to get the CUBRID OLEDB Provider library, how to setup a CUBRID connection and how to develop some simple applications, mainly using OLE DB Consumer templates.

Requirements

Windows Vista/7
CUBRID 8.4.1 (The CUBRID version must match the Driver version)
Visual Studio 2010 Express Edition (http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express)
.NET framework 3.5 or above (http://www.microsoft.com/download/en/details.aspx?id=21)

CUBRID OLE DB Data Provider

Before you start to developing applications with CUBRID, you will need the provider library (CUBRIDProvider.dll). Make sure to download the appropiate DLL according to your CUBRID installation. You can check the CUBRID version by using the command "cubrid --version". You have several options:

Use official installer

Use the official CUBRID OLED DB Data Provider Installer. You can follow this 1 minute video tutorial to see how to install CUBRIDProvider using the installer.

Download the compiled libraries

If you choose to install it manually (by just downloading the CUBRIDProvider.dll), you need to properly register the driver before you can use it, through one of the following registration methods:

1. Download the CUBRIDProvider.tlb file from here, and make sure it is located in the same folder with the CUBRIDProvider.dll, and run the following command in that folder:

regsvr32 CUBRIDProvider.dll

2. Download the CUBRIDProvider.reg file from here, update it by specifying your own path location of the CUBRIDProvider.dll (the CUBRIDProvider.reg file you downloaded will contain by default the following location: C:\CUBRID\oledb\CUBRIDProvider.dll) and then run the following command:

regedit CUBRIDProvider.reg

Compile from source code

Checkout the code from the SVN repository:http://svn.cubrid.org/cubridapis/oledb/branches/RB-8.4.1/Source/.

For compiling the source code and the example in this tutorial, use Microsoft Visual Studio Express edition – you can download it from: http://www.microsoft.com/express/Downloads/#2010-Visual-CPP. Please make sure you download the appropriate version – 32 or 64-bit.

Compile or modify the installer

If you wish to make certain changes to our OLEDB Data Provider Installer, refer to [Compiling the CUBRID OLE DB installer].

CUBRID OLEDB Driver 9.1.0 release note

2013-04-25T22:58:53-07:00

9.1.0.0001

Updates summary since beta release
=================================================

2 new schema rowsets added (Catalog and SQL language)
New test cases added (localization, data types handling, extended connect)
Changed the login internal procedure to use the connect_with_url CCI function; additional parameters included (login & query timeout, auto-commit)
64-bit driver library available for download
Various updates in the source code; more code cleanup
Additional resources made available (new tutorial and short video)
Some improvements in LOB handling
New Installer version

General development notes
=================================================

The 8.4.1 provider code is based on the legacy CUBRID 3.1 OLE DB provider code
Various enhancements and support for latest CUBRID releases has been implemented
We have focused on supporting OLE DB Consumer templates (http://msdn.microsoft.com/en-us/library/8k76sd16%28v=vs.80%29.aspx). Direct OLE DB interfaces should work as well, but the technology is deprecated.
A full suite of open source test cases is now part of the driver code base release
Regarding .NET support (via System.Data.OleDb namespace), we are encouraging the use of the fully managed CUBRID ADO.NET driver instead (http://www.cubrid.org/wiki_apis/entry/cubrid-ado-net-driver).
The code is released under the BSD license (http://www.cubrid.org/bsd_license).

Release components
==============================================

The driver source code (http://svn.cubrid.org/cubridapis/oledb/branches/RB-8.4.1/Source/)
The driver OLE DB Data Provider compiled library x32/x64 release (CUBRIDProvider.dll)
Win32 Driver Installer (with a short video)
Release notes
Test cases suite : 60+ OLE DB Consumer test cases (see the attachments for a test suite run output)
3 Tutorials

Known limitations
=================================================

There is limited support for queries not based on tables structures, in terms of columns automatic definitions
There is no full support yet for BLOB/BLOB Dynamic Accessors
Update() support is restricted to Auto-Commit mode = Off, which must be explicitly stated via session transaction.
Not all schema are implemented as defined here: http://msdn.microsoft.com/en-us/library/a6fhbff0%28v=vs.71%29.aspx.
More test coverage is required for testing non-standard data types
We are supporting mainly C++ OLE DB templates; there is limited or no support for other driver usages (direct interfaces
Very limited support for some special data types: SET, MUTISET and SEQUENCE

What's next/To-Do
=================================================

Re-Generate and publish the Doxygen driver documentation
Continue to improve support for BLOB/CLOB
Make available in write-mode additional connection properties: loging & query timeouts
Add more test cases coverage, in particular for CUBRID specific data types and for .NET OleDb access.
Remove the data provider distribution from the CUBRID standard installer
Continue SVN cleanup and update Trunk

CUBRID ODBC Driver Installation Instructions

2013-04-26T00:30:40-07:00

If you want to use CUBRID as a data source for your Windows applications using the ODBC Driver, this article will help you achieve this.

Notice: If your CUBRID ODBC Driver version is 9.1.0.p1 or later, only one installation package is needed for both Windows 32 bit and 64 bit. Our new ODBC installer supports CUBRID DB engine 8.4.1 or later.

If your CUBRID ODBC Driver version is 9.1.0 or older, it may have a problem on 64 bit operating system. Please see our installation tutorial for an old version: http://www.cubrid.org/wiki_apis/entry/cubrid-odbc-driver-installation-instructions-old

Download

Download a new installation package file which name is "cubrid-odbc-<version>-win32-x64.zip".
It will install both cubrid_odbc32.dll and cubrid_odbc64.dll at once. You can find a CUBRId ODBC inataller at:

http://ftp.cubrid.org/CUBRID_Drivers/ODBC_Driver/ or
http://www.cubrid.org/?mid=downloads&item=odbc_driver

Driver Installation

Run a CUBRID ODBC Installer (exe) and click the Next / Install Button.

In your installation directory, you can see the following DLL files and uninstall. exe.

Configuration

On your PC, first open the => . You should see a list of tools available on your Windows OS as shown below.

Double click on the to open it.

OPEN DATA SOURCES ON WINDOWS 64-BIT

If your driver version is 9.1.0.p1 or later, you should launch Data Sources (ODBC) as shown above as it will start 64-bit version of Data Sources (ODBC) program, otherwise you need to start 32-bit version of Data Sources (ODBC) which is located in C:\Windows\SysWOW64\odbcad32.exe. Make sure you start this one. SysWOW64 means Windows 32-bits on Windows 64-bit.

Create new data source

Then navigate back to the tab and click on the button.

In the pop-up window choose the CUBRID Driver and click the button.

Fill out the fields with the necessary data as shown in the image below.

DSN: Give a desired name to this data source (eg. your database name).
Description: Enter the description for this data source.
DB Name: Enter the target database name.
DB User: Database user name.
Password: Database user password.
Server Address: Database host address (localhost). You can also enter the remote server's IP address.
Server Port: CUBRID Broker's port number. The default port is 33000.
You can check this in your command line terminal. Type cubrid service status. In the output you will seebroker1 in the first column and the port number in the third. You will notice that the broker uses the default port number 33000. If set otherwise, enter that port number into this field.
Another way to find the Broker port number is in the Broker's configuration file located at%CUBRID%confcubrid_broker.conf. See the BROKER_PORT value.
FETCH_SIZE: Set the number of record to fetch from the database. 100 should be reasonable.

Once filled out, click button. You will see CUBRID among the User Data Sources as shown below.

Connecting to a database directly without DSN

It is also possible to connect to the CUBRID database directly in the application source code indicating the connecting string. In this case, use the following connection string.

conn = "driver={CUBRID Driver};server=localhost;port=33000;uid=dba;pwd=;db_name=demodb;"

Before establishing a connection

Make sure that your database is started before you try to connect or link to a CUBRID database. Otherwise, you will receive an ODBC call failed error.

This is all you need to do in order to connect to a CUBRID database using the ODBC driver.

CUBRID ODBC Driver Installation Instructions Old

2011-08-15T03:58:06-07:00

If you want to use CUBRID as a data source for your Windows applications using the ODBC Driver, this article will help you achieve this.

Notice: This Tutorial is only available for cubrid-odbc-8.4.0 or older versions. CUBRID ODBC installation used to have a problem on 64 bit OS so we have offered a new installation package available for both 32bit and 64 bit OS since 2013-05. If your CUBRID DB Engine is running on 64 bit OS, please choose a new installation package by following : http://www.cubrid.org/wiki_apis/entry/cubrid-odbc-driver-installation-instructions

If you still wish to separately download the ODBC driver, perhaps, for remote connection when CUBRID is not installed on your machine, you can download it from http://www.cubrid.org/?mid=downloads&item=odbc_driver&os=windows or from http://ftp.cubrid.org/CUBRID_Drivers/ODBC_Driver/.

Configuration

Open Data Sources on Windows 32-bit

On you PC, first open the Control Panel => Administrative Tools. You should see a list of tools available on your Windows OS as shown below.

Double click on the Data Sources (ODBC) to open it.

OPEN DATA SOURCES ON WINDOWS 64-BIT

If you are using 64-bit Windows, you should not launch Data Sources (ODBC) as shown above as it will start 64-bit version of Data Sources (ODBC) program. Since CUBRID ODBC driver is available only in 32-bit version, we need to start 32-bit version of Data Sources (ODBC) which is located in c:\Windows\System32\odbcad32.exe. Make sure you start this one.

Create new data source

Once you started the 32-bit version of Data Sources (ODBC), navigate to the Drivers tab and make sure the CUBRID Driver is available as shown below, which will mean that it has been successfully installed on your system.

Then navigate back to the User DSN tab and click on the Add button.

In the pop-up window choose the CUBRID Driver and click the Finish button.

Fill out the fields with the necessary data as shown in the image below.

DSN: Give a desired name to this data source (eg. your database name).
Description: Enter the description for this data source.
DB Name: Enter the target database name.
DB User: Database user name.
Password: Database user password.
Server Address: Database host address (localhost). You can also enter the remote server's IP address.
Server Port: CUBRID Broker's port number. The default port is 33000.
You can check this in your command line terminal. Type cubrid service status. In the output you will see broker1 in the first column and the port number in the third. You will notice that the broker uses the default port number 33000. If set otherwise, enter that port number into this field.
Another way to find the Broker port number is in the Broker's configuration file located at %CUBRID%confcubrid_broker.conf. See the BROKER_PORT value.
FETCH_SIZE: Set the number of record to fetch from the database. 100 should be reasonable.

Once filled out, click OK button. You will see CUBRID among the User Data Sources as shown below.

Connecting to a database directly without DSN

It is also possible to connect to the CUBRID database directly in the application source code indicating the connecting string. In this case, use the following connection string.

conn = "driver={CUBRID Driver};server=localhost;port=33000;uid=dba;pwd=;db_name=demodb;"

Before establishing a connection

Make sure that your database is started before you try to connect or link to a CUBRID database. Otherwise, you will receive an ODBC call failed error.

This is all you need to do in order to connect to a CUBRID database using the ODBC driver.

QA OK Sign - CUBRID OLEDB Driver

2013-04-25T23:42:53-07:00

[CUBRID OLEDB 9.0.1.p1 QA Test Report]

CUBRID OLEDB 9.0.1.p1 QA Test Report

2013-05-03T18:37:57-07:00

1. Test Info

Driver Build: ODBC 9.1, OLEDB 9.1
Server Build: CUBRID 9.1 (9.1.0.0212) (64bit release build for linux_gnu)
Test Platform: Windows7 32bit, Windows XP 32bit, Windows2003 64bit
.Net Framework: 3.5

2. Test Results

OLEDB Interface

3. Bug status

Total	14
Closed	14
Postpone	0

4. Function Testing

Total	Pass	Fail	Success Rate
236	236	0	100%

5. Issues

1) Some CUBRID Date Type Name are not consistent with OLEDB Date Type Name. It may be ambiguous to users. We think it should be optimized. Please refer http://jira.cubrid.org/browse/APIS-30

2) The CUBRID OLEDB Interface manual should describe the data type mapping between CUBRID and OLEDB, like the ODBC manual http://www.cubrid.org/manual/91/en/api/odbc.html. It will help user to develop with OLEDB interface more easily

3) Some properties value of db connection should be consistent with MSDN. It will help users use CUBRID more clearly. Such as http://jira.cubrid.org/browse/APIS-532

CUBRID ODBC Driver 9.1.0 Release Note

2013-04-25T23:23:11-07:00

9.1.0

Functionality added or changed:

The following ODBC APIs are newly supported by CUBRID ODBC:

SQLPrimaryKeys
SQLForeignKeys
SQLProcedures
SQLProcedureColumns
SQLTablePrivileges

SQLPrimaryKeys returns the column names that make up the primary key for a table.
SQLForeignKeys can return:
1. A list of foreign keys in the specified table (columns in the specified table that refer to primary keys in other tables).
2. A list of foreign keys in other tables that refer to the primary key in the specified table.
SQLProcedures returns returns the list of function/procedure names stored in a specific data source.
1. Stored functions/procedures are blocks of code that have a flow of commands for data manipulation and are easy to manipulate and administer. CUBRID supports to develop stored functions and procedures in Java. Java stored functions/procedures are executed on the JVM (Java Virtual Machine) hosted by CUBRID.
SQLProcedureColumns returns the list of input and output parameters for the specified procedures, but not including the return columns.
SQLTablePrivileges returns a list of tables and the privileges associated with each table, which represents authorization information of the classes for which the current user has authorization in the database.

Fixed bugs:

SQLFetchScroll: When parameter FetchOrientation is SQL_FETCH_LAST, SQLFetchScroll should return the last complete rowset in the result set. But it will return the first, not the last.
- SQLFetchScroll is used to fetches the specified rowset of data from the result set and returns data for all bound columns. Rowsets can be specified at an absolute or relative position or by bookmark.
SQLSetPos: Application will crash when calling SQLSetPos.
- SQLSetPos sets the cursor position in a rowset and allows an application to refresh, update or delete data in the result set.
SQLSetPos: The default value of statement attribute SQL_ATTR_ROW_ARRAY_SIZE is 1, which is the number of rows returned by each call to SQLFetch or SQLFetchScroll. If we set this attribute to value that is more than 1, SQLSetPos can't work correctly.
SQLStatistics and SQLSpecialColumns: The results of the two catalog functions are not valid.

SQLStatistics retrieves a list of statistics about a single table and the indexes associated with the table. SQLSpecialColumns retrieves the following information about columns within a specified table:
- When IdentifierType is SQL_BEST_ROWID, it will return information of columns that uniquely identifies a row in the table;
- When IdentifierType is SQL_ROWVER, it will return information of columns that are automatically updated when any value in the row is updated by a transaction.
  
  No data type in CUBRID will auto-update, so it only can return the columns which compose the unique keys.

CUBRID ODBC Driver 9.1.0.p1 Release Note

2013-05-03T18:30:17-07:00

9.1.0.p1

Changed and Enhanced Features:

[APIS-184] - [ODBC]how to do auto_commit off in C#

Fixed bugs:

[APIS-152] - [ODBC] 한글 쿼리 실행 시 에러
[APIS-155] - CUBRID ODBC Driver에서 SELECT 수행시 런타임 오류 발생
[APIS-156] - user reported> ODBC driver has a Fetch error
[APIS-443] - Fetch error in using openrowset() call in sql server
[APIS-445] - sql server core dump if openrowset() call on numeric field from ODBC driver
[APIS-536] - [ODBC] The returned value of OdbcConnection.Database is incorrect
[APIS-538] - [ODBC] A problem of the returned value of OdbcConnection.DataSource property
[APIS-539] - [ODBC] OdbcDataReader.GetDataTypeName doesn't work
[APIS-540] - [ODBC] OdbcDataReader GetInt16, GetInt32 doesn't returns expected exception when read an overbound integer

CUBRID ODBC 9.0.1.0.p1 QA Test Report

2013-05-03T17:47:31-07:00

1. Test Info

Driver Build: ODBC 9.1
Server Build: CUBRID 9.1 (9.1.0.0212) (64bit release build for linux_gnu)
Test Platform: Windows7 32bit, Windows XP 32bit, Windows2003 64bit
.Net Framework: 3.5

2.Test Results

ODBC Interface

3.Bug status

Total	14
Closed	14
Postpone	0

4. Function Testing

Total

Pass

Fail

Success Rate

271

100%

5. Issues

None

QA OK Sign - CUBRID ODBC Driver

2013-04-25T23:31:46-07:00

[CUBRID ODBC 9.0.1.0.p1 QA Test Report]

CUBRID JDBC Maven Repository

2012-04-25T17:31:11-07:00

[CUBRID JDBC Driver|CUBRID JDBC] is an API that allows users to connect to CUBRID database within applications written in Java.

In order to add CUBRID JDBC driver to your maven project, add the following dependency to your project's pom.xml file:

<dependency>
<groupId>cubrid</groupId>
<artifactId>cubrid-jdbc</artifactId>
<version>8.4.3.1005</version>
</dependency>

Remember to indicate the appropriate version number. The list of available versions can be found at http://maven.cubrid.org/cubrid/cubrid-jdbc/.

You should also add the repository information into your pom.xml file:

<repository>   
<id>CUBRID</id>
<name>CUBRID-releases</name>
<url>http://maven.cubrid.org</url>
</repository>

This concludes the maven tutorial. If you have any question, please post it on our Q&A Site or on our forum.

Compiling the CUBRID OLE DB installer

2012-06-10T17:12:15-07:00

Introduction

The CUBRID OLE DB installer is open-source code, BSD licensed and built using NSIS.

NSIS (Nullsoft Scriptable Install System) is a professional open source system for creating Windows installers. It is designed to be as small and flexible as possible and is therefore very suitable for internet distribution.

We choosed NSIS because it is widely used in open source projects, it is script-based and allows us to create the logic to handle even the most complex installation tasks.

Updating and compiling the installer

The source code for CUBRID OLEDB Installer is located in the CUBRID SVN repository:
http://svn.cubrid.org/cubridapis/oledb/branches/RB-xxx/installer/installer.nsi

If you want to compile the installer yourself, (and maybe change it,) we recommend the followings:

Download the installer script source code - see the above specified location
Update the script, if needed; we recommend using HM NIS Edit tool.

"HM NIS Edit is the best Editor/IDE for Nullsoft Scriptable Install System (NSIS). Its useful for experts and beginners in the creation of Setup programs with the NSIS. Its Script Wizard will help you to create standard Setup programs with only few clicks, also its InstallOptions designer will help you to create your own custom pages with a friendly drag and drop interface."
Compile the installer. (If you use HM NIS Edit it is just a matter of clicking a toolbar button.)

Notes:

By default, the installer script code is for creating the x32 installer. If you want to create the x64 installer,

please update the installer script first by commenting/uncommenting the appropiate lines of code (just search for "64" in the script).

OLEDB Connection String

2012-04-23T05:02:48-07:00

The first thing we need to know in order to create a CUBRID connection is to how to build the connection string.

Looking into the CUBRID documentation (http://www.cubrid.org/manual/841/en/Configuring%20Connection%20Strings), you will find out that in order touse the CUBRID OLE DB Provider, the connection string must be built using the following "pieces":

Item	Exampe/Value	Description
Provider	CUBRIDProvider	Provider name. Do not change this value.
Data Source	demodb	Database name.
Location	127.0.0.1 (or "localhost")	The IP address of the CUBRID Broker Server.
User Id	dba	Database username.
Password	xxxxxx	User password.
Port	30000	Broker port number (typically 30000 or 33000, for more info see Connecting to a remote CUBRID Database).

For example, to connect to the demodb database, using the public user, on a local CUBRID installation, the connection string will be:

 Provider=CUBRIDProvider;Location=localhost;Data Source=demodb;User Id=public;Port=33000

Please note that in the next provider releases, you will be able to specify in the connection string additional information such as:

Connection encoding
Auto-commit mode

CUBRID Ruby API Documentation

2012-01-06T03:13:47-08:00

1 Overview
2 Getting Help
3 Preparing the Environment
- 3.1 Preparing CUBRID
- 3.2 Preparing Ruby
  - 3.2.1 On Windows
    - 3.2.1.1 Install Ruby
    - 3.2.1.2 Install Ruby Driver for CUBRID
  - 3.2.2 On Linux
    - 3.2.2.1 Install Ruby
    - 3.2.2.2 Install Ruby Driver for CUBRID
4 Ruby API
5 See also

Overview

This tutorial will explain all steps that you need to perform in order to connect to CUBRID Database and run SQL statements through Ruby programming language.

At any time if you feel lost somewhere, you can always visit the main page for Ruby Programming to start from the beginning.

Getting Help

If you have any troubles connecting to CUBRID through Ruby, post your questions to Ruby Forum at http://www.cubrid.org/forum.

Preparing the Environment

Preparing CUBRID

First thing you have to do is to make sure you have installed CUBRID Database according to all the steps explained in Install CUBRID. If you have not installed CUBRID yet, Download CUBRID and follow the Installation Instructions. In this tutorial I will be using the latest stable release CUBRID 9.1.0. On my machine it is installed in C:CUBRID. However, you do not have to worry much about it, as the CUBRID Installer automatically adds its location path to the Windows environment.
NOTE For Windows users: Make sure you have installed Java Development Kit (JDK) and Microsoft C++ 2008 Redistributable Package.

Preparing Ruby

On Windows

Install Ruby

You can download Ruby Installer from various places. I prefer to Download Ruby Installer from http://rubyinstaller.org. At this point you will see me using pure Ruby 1.8.7-p299. Currently Ruby 1.9.1 is not supported, as the Ruby Driver for CUBRID has been compiled in the 1.8.7 environment. But we have already started building for 1.9.1, so it will be available soon.

Install Ruby Driver for CUBRID

If you have installed the above mentioned Ruby 1.8.7-p299, you should already have RubyGem installed. RubyGem is required to install additional external packages such as CUBRID Database driver, ActiveRecord, and other similar extensions. In order to install the Ruby Driver for CUBRID, in the command line type gem install cubrid as shown below.

C:\Ruby> gem install cubrid
Successfully installed cubrid-0.65-x86-mingw32
1 gem installed
Installing ri documentation for cubrid-0.65-x86-mingw32...
Installing RDoc documentation for cubrid-0.65-x86-mingw32...

At this point you should see the message about the successful installation of cubrid-0.65-x86-mingw32 driver. The Ruby Driver provides the same functions as the original CUBRID CCI (C Interface) Library does. Below you will see sample tests which illustrate how to communicate with the CUBRID Database.

On Linux

Install Ruby

In order to install Ruby, we will use the generic Linux command. In this tutorial we will work under Ubuntu 10.4, and install Ruby 1.8.7. Type the following command to get Ruby and other necessary packages installed together.

sudo apt-get -y install ruby1.8-dev ruby1.8 ri1.8 rdoc1.8 irb1.8 libreadline-ruby1.8 libruby1.8 libopenssl-ruby rubygems1.8
sudo ln -s /usr/bin/ruby1.8 /usr/bin/ruby
sudo ln -s /usr/bin/rdoc1.8 /usr/bin/rdoc
sudo ln -s /usr/bin/irb1.8 /usr/bin/irb
sudo ln -s /usr/bin/ri1.8 /usr/bin/ri

The first line indicates which packages should be installed. Notice that I am installing Ruby 1.8 version. At this moment Ruby 1.9.1 is not supported. But we have already started building for 1.9.1, so it will be available soon. The rest four lines create symbol links so that you are able to run the commands link "ruby", "rdoc", "irb", and "ri". Actually, you will need only the first one.

Install Ruby Driver for CUBRID

On Linux there are two ways to get Ruby Driver for CUBRID installed.

Install Ruby Gem.
Manually compile the code and install the library.

Install Ruby Gem

CUBRID gem has been successfully pushed to RubyGems.org. So, now on Linux users can get CUBRID connector through gem.
Add the -E flag when installing the gem with sudo like "sudo -E gem install cubrid". The -E flag is necessary to make sure sudo does not reset the user path where CUBRID Database has been installed.

Manually Build the Library

Download source code of Ruby Driver for CUBRID.
Extract, then run the following command in the terminal, which means that you are running the Ruby code within extconf.rb file. It will create a Makefile.

ruby extconf.rb

After the Makefile has been successfully created, type the following command to install the driver in your system.

make install

That's all! To see if everything has successfully been installed, print out the CUBRID Database version. Remember that in order to connect to a certain database, you have to first start that database. Otherwise, you will receive an error.

Example

Create a file called "testcubrid.rb" and paste the following Ruby code.

require 'rubygems'
require 'cubrid'
db = 'demodb'
con = Cubrid.connect(db)
if con
	puts "connection established"
	puts "CUBRID Database version is: #{con.server_version}"
	con.close()
else
	puts "Connection could not be established"
end

Then type the following commands in the terminal.

cubrid service start
cubrid server start demodb
ruby --rubygems testcubrid.rb

The first line will start CUBRID services.
The second line will start the database called "demodb".
The third line will run the Ruby code inside "testcurbid.rb" file.

You should see the following output.

connection established
CUBRID Database version is: 8.2.2.0261

Ruby API

Connection Class

Data Constants

Description

The following Data Types represent the Cubrid class data type constants declared in the Ruby API.

Syntax

Cubrid::DATE

Support Data Type Constants

CHAR

VARCHAR

STRING

NCHAR

VARNCHAR

BIT

VARBIT

NUMERIC

INT

SHORT

MONETARY

FLOAT

DOUBLE

DATE

TIME

TIMESTAMP

SET

MULTISET

SEQUENCE

OBJECT

INCLUDE_OID

READ_LOCK

WRITE_LOCK

auto_commit=

Description

This method is used to set the auto_commit mode of the current connection. If auto_commit is set to true, after every Statement.execute call the transaction will be immediately committed.

Syntax

auto_commit= true or false ? nil

Return value

nil

auto_commit?

Description

This method is used to determine whether auto_commit mode of the current connection is set to true or false.

Syntax

auto_commit? ? true or false

Return value

true: auto_commit is set to true
false: auto_commit is set to false

connect

Description

This method is used to establish the connection with the database server by using the given information such as the database name, server address, port number, username and password. If the username and password are not set, public is used as default the default username and "" (empty password) is used as a password.

Example

@con = Cubrid.connect('db_name', 'host', port, 'db_user', 'db_password')
 
#OR
 
@con = Cubrid.connect('db_name')

db_name : a string representing the database name
host : a string representing the host name of the server (by default it is localhost)
port : an integer representing the server port (by default it is 30000 - thirty thousand)
db_user : a string representing the database user name (by default it is public)
db_passwd : a string representing the database user password (by default it is "" - empty password)

Return Value

@con: The connection has successfully been established!

nil: Filed to establish the connection.

close

Description

This method is used to terminate the connection with the server. All pending Statements will also be closed.

Example

@con.close()

commit

Description

This method is used to commit the transactions being performed currently in the connection.

Example

@con.commit

Return value

nil

rollback

Description

This method is used to rollback the last performed transactions. If the transaction is terminated, all Statement objects will also be closed.

Example

@con.rollback

Return value

nil

glo_new

Description

This method is used to create a new GLO object. The glo_new method will return the OID of the newly created object. When glo_new is called CUBRID provides GLO which will store the binary data. Later GLO object can be directly accessed by OID.

Syntax

glo_new(classname <, filename>) ? OID

Return value

OID:

Example

The below example illustrates how to use glo_new method. When called, the data inside the file, whose filename has been passed as a parameter, will be stored in the database. If the filename is not indicated, the method will create an empty GLO object.

con = Cubrid.connect('subway')
con.query('create table attachfile under glo (name string)')
con.commit
 
glo = con.glo_new('attachfile', 'pic.jpg')
glo.glo_size  #=> 1234
 
glo = con.glo_new('attachfile', '')
glo.glo_size  #=> 0
glo.glo_save('pic.jpg')
glo.glo_size  #=> 1234

query

Description

This method directly executes the SQL statement, which has been passed as a parameter, without a need to perform the execute method.

Syntax

query(sql [!, option]) ? Statement
 
OR
 
query(sql [!, option]) { |row|
  ...
} ? nil

Parameters

sql : a string representing the SQL statement
option: [!Optional] If Cubrid::INCLUDE_OID is passed as an option, the query method will behave like the prepare method.

Return value

stmt: The request handler
nil: The query has not been executed

Examples

sql = "INSERT INTO table1 (id, name) VALUES (1, 'Ruby')"
stmt = @con.query(sql)
@con.commit

con = Cubrid.connect('demodb')
stmt = con.query('SELECT * FROM db_user')
 
while row = stmt.fetch
   print row
end

stmt.close
stmt = con.query('SELECT * FROM db_user') { |row|
   print row
}

con.close

prepare

Description

This method is used to prepare an SQL statement.

Syntax

prepare(sql <, option>) ? Statement
 
#OR
 
prepare(sql <, option>) { |stmt|
  ...
} ? nil

Parameters

sql : a string representing the SQL statement
option : [!Optional] If Cubrid::INCLUDE_OID is passed as an option, the returned results will include OID, which can be later retrieved by calling stmt.get_oid method.

Return Value

stmt: The request handle

nil: Filed to prepare the SQL statement.

Example

sql = "INSERT INTO table1 (id, name) VALUES (?, ?)"
stmt = @con.prepare(sql)
con = Cubrid.connect('demodb')
stmt = con.prepare('SELECT * FROM db_user')
stmt.execute
r = stmt.fetch

stmt.close
con.close
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   r = stmt.fetch
}
con.close

to_s

Description

This method is used to get the current connection information.

Example

# same as
# puts @con
connection_info = @con.to_s

Return values

connection_info : a string representing the connection information.

server_version

Description

This method is used to get the version of the database server.

Example

version = @con.server_version

Return values

version : a string representing the version of the database server.

Statement Class

Data Types

The table below shows the data type conversion between CUBRID native data types and Ruby representation.

CUBRID Data Types	Ruby Data Type Representation
int, short	fixnum, bignum
float, double, numeric, monetary	float
char, varchar, ncahr, varnchar	string
bit, varbit	string
date, time, timestamp	Time
object	OID
collection	array

affected_rows

Description

This method is used to get the number of rows which have been affected by the SQL statements (INSERT, DELETE, UPDATE).

Example

stmt = @con.query("UPDATE cities SET name = 'Paris' WHERE id = 4")
@con.commit
num = stmt.affected_rows

Return values

num : an integer representing the number of rows affected by the last SQL statement.

bind

Description

This method is used to substitute the values instead of the variables indicated in the SQL queries as question marks (?) in the prepare method.

Syntax

bind(index, data [!, db_type, set_type]) ? nil

Parameters

index : an integer representing the order of the variable to be replaced - first, second, ...
data : a value representing the data to be replaced for the variable at the order index.
db_type : [!Optional] db_type is a type of the value to be bound. It can be omitted by default. If it is omitted, the type is automatically cast to an appropriate one.
set_type : [!Optional]

Return value

nil

Example

index = 1
value = "Ruby"

stmt.bind(index, value)
con = Cubrid.connect('demodb')
con.auto_commit = true
con.query('create table a (a int, b double, c string, d date)')
 
con.prepare('insert into a values (?, ?, ?, ?)') { |stmt|
   stmt.bind(1, 10)
   stmt.bind(2, 3.141592)
   stmt.bind(3, 'hello')
   stmt.bind(4, Time.local(2007, 12, 25, 10, 10, 10), Cubrid::DATE)
   stmt.execute
}
con.close

close

Description

This method is used to close the Statement.

Syntax

close() ? nil

Return value

nil

Example

stmt.close

column_info

Description

Returns the column information of the fetched rows. Because of the column information is represented as a hash, it is returned in the form of array.

Syntax

column_info() ? array

Return value

array: an array representing the hash of the key name, type_name, precision, scale, nullable, which refer to the column's name, the column's data type, precision, scale, null-ability, respectively.

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   stmt.column_info.each { |col|
   print col[!'name']
   print col[!'type_name']
   print col[!'precision']
   print col[!'scale']
  print col[!'nullable']
   }
}
con.close

each

Description

Returns the fetched rows one by one in a cycle to the inside block. The row is represented as an array.

Syntax

each() { |row| block } ? nil

Return value

nil

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   stmt.each { |r|
   print r[!0]
   }
}
con.close

each_hash

Description

Returns the fetched rows one by one in a cycle to the inside block similar to the each() method. The difference is that each_hash returns a row which is represented as a hash.

Syntax

each_hash() { |hash| block } ? nil

Return value

nil

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   stmt.each_hash { |r|
   print r[!'name']
   }
}
con.close

execute

Description

This method is used to execute a given SQL statement. It can receive zero or more parameters depending on whether the bind method has been used before or not. If the statement stmt has been already binded' to the values, the execute method does not need any parameter. If the statementstmt has not been binded' to any values yet, the execute method will instantly bind the receive parameters and execute the SQL statement. If auto_commit is set to true, the execute method will automatically commit the transaction.

Syntax

execute() ? int
execute(...) ? int

Parameters

values : [!Optional] a value representing the data to be binded to each variable in the SQL statement.

Return value

int: Returns 1, if successful; 0 in case of failure.

Example

con = Cubrid.connect('demodb')
con.prepare('insert into a values (?, ?, ?, ?)') { |stmt|
   stmt.execute (10, 3.141592, 'hello', Time.local(2007, 12, 25))
}
con.close
sql = "INSERT INTO table1 (id, name) VALUES (?, ?)"
stmt = @con.prepare(sql)
value1 = 1
value2 = "Ruby"
stmt.bind(1, value1)
stmt.bind(2, value2)
stmt.execute

sql = "INSERT INTO table1 (id, name) VALUES (?, ?)"
stmt = @con.prepare(sql)
stmt.execute(value1, value2)

fetch

Description

Returns the row under the cursor as an array of column data. Once fetched the cursor is incremented by one, that is pointed to the next row. The row is represented as an array.

Syntax

fetch() ? array or nil

Return value

array : an array representing the row with columns.
nil: if there is no row to be fetched, the method returns nil.

Below is a table which illustrates how

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   r = stmt.fetch
   print r[!0]
}
con.close

fetch_hash

Description

Returns the row under the cursor as a hash of column data. Once fetched the cursor is incremented by one, that is pointed to the next row. The row is represented as an array.

Syntax

fetch_hash() ? hash or nil

Return value

hash : a hash representing the row with columns.
nil: if there is no row to be fetched, the method returns nil.

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user') { |stmt|
   stmt.execute
   r = stmt.fetch_hash
   print r[!'name']
}
con.close

get_oid

Description

In case a statement has been prepared with Cubrid::INCLUDE_OID option, the get_oid method will return the Oid of the created GLO object.

Syntax

get_oid() ? Oid

Return value

Oid: the OID of the newly created GLO object.

Example

con = Cubrid.connect('demodb')
con.prepare('SELECT * FROM db_user', Cubrid::INCLUDE_OID) { |stmt|
   stmt.execute
   stmt.fetch
   oid = stmt.get_oid
   print oid.table
}
con.close

Oid Class

[!](col_name)

Description

Returns the column data of the OID.

Syntax

[!](col_name) ? obj

Return value

obj: the column data of the OID.

Example

con = Cubrid.connect('demodb')
stmt = con.prepare('SELECT * FROM db_user', Cubrid::INCLUDE_OID)
stmt.execute
stmt.fetch
oid = stmt.get_oid
print oid[!'name']
print oid.name
stmt.close
con.close

Another way to access the data in the column is to call the name as a method.

oid = stmt.get_oid
print oid.name

[!]=(col_name, obj)

Description

Stores the data to the OID column. In order to reflect the saved data in the database server save method should be called afterwards.

Syntax

[!]=(col_name, obj) ? nil

Return value

obj: the column data of the OID.

Example

con = Cubrid.connect('demodb')
stmt = con.prepare('SELECT * FROM db_user', Cubrid::INCLUDE_OID)
stmt.execute
stmt.fetch
oid = stmt.get_oid
oid[!'name'] = 'foo'
oid.save
stmt.close
con.close

It is also possible to store and save the data using the corresponding name and save methods for the column.

oid = stmt.get_oid
oid.name = 'foo'
oid.save

drop

Description

Removes the OID from the database server.

Syntax

drop() ? self

Return value

self

each

Description

Passes the column name and its data to the following block.

Syntax

each() { |name, val|
  ...
} ? nil

Return value

nil

Example

con = Cubrid.connect('demodb')
stmt = con.prepare('SELECT * FROM db_user', Cubrid::INCLUDE_OID)
stmt.execute
stmt.fetch
oid = stmt.get_oid
oid.each { |name, val|
   print name
   print val
}

lock

Description

Sets the Cubrid::READ_LOCK or Cubrid::WRITE_LOCK to the OID.

Syntax

lock(lockmode) ? self

Parameter

lockmode : the mode of the lock. Can be either Cubrid::READ_LOCK or Cubrid::WRITE_LOCK.

Return value

self

refresh

Description

Reads the OID data from the database server. The column data of the OID is not automatically synchronized with the database server. In case much time has been elapsed since the Oid object has been created, the refresh method has to be called to read the data from the database server.

Syntax

refresh() ? self

Return value

self

Example

con = Cubrid.connect('demodb')
stmt = con.prepare('SELECT * FROM db_user', Cubrid::INCLUDE_OID)
stmt.execute
stmt.fetch
oid = stmt.get_oid
print oid[!'name']

#after some time
oid.refresh
print oid[!'name']
stmt.close
con.close

save

Description

Saves the data of OID to the database server.

Syntax

save() ? self

Return value

self

table

Description

Returns the table name of the OID.

Syntax

table() ? string

Return value

string : the table name of the OID

to_hash

Description

Returns the OID data in a hash.

Syntax

to_hash() ? Hash

Return value

Hash : The OID data. The key will indicate on its name, and the value - its data.

to_s

Description

Returns the OID string.

Syntax

to_s() ? string

Return value

string : the OID string.

CUBRID Ruby Driver Installation Instructions

2012-01-03T17:58:59-08:00

On Windows

We have pushed the CUBRID Connector to Gemcutter. Use the above command (gem install cubrid) in the command line to install the latest version of Ruby Driver for CUBRID on Windows.

On Linux

Linux users can also install the CUBRID Connector through gem. Remember to add -E flag when installing the gem with sudo like "sudo -E gem install cubrid". The -E flag is necessary to make sure sudo does not reset the user path where CUBRID Database has been installed.

What if I don't have Gem Installer?

On Windows

Install Ruby 1.8.7. You can download it from RubyInstaller site at http://rubyinstaller.org/downloads/.
Install DevKit. Most Ruby gems out there require the mingw compiler to build gems written in C. CUBRID gem has C codes as well, so DevKit is required to install the latest CUBRID gem. You can download the DevKit from the same RubyInstaller site at http://rubyinstaller.org/downloads/.
- In the command line navigate to the location where you installed the DevKit and initialize DevKit by typing the following command. This will generate the config.yml file to be used later in this Step. Your installed Rubies will be listed there (only those installed by a RubyInstaller package are detected at present).
- If necessary, edit config.yml file to include installed Rubies not automagically discovered or remove Rubies you do not want to use the DevKit with. This step is not required if you have installed Ruby from http://rubyinstaller.org/downloads/.
- Install DevKit by typing the following command in the command line. This step installs (or updates) an operating_system.rb file into the relevant directory needed to implement a RubyGems pre_install hook and a devkit.rb helper library file into <RUBY_INSTALL_DIR>lib ubysite_ruby.
- For more information on DevKit, refer to http://github.com/oneclick/rubyinstaller/wiki/Development-Kit.
- Before trying to install cubrid, make sure that the "make" and "gcc" commands are available in your command line. If not, add C:\DevKit\bin\ and C:\DevKit\mingw\bin\ to your PATH environment variable (we assumed DevKit is in C:\DevKit).
Install CUBRID gem by typing the following command.

gem install cubrid

On Linux

Install Ruby 1.8.7 by typing the following command.

sudo apt-get -y install ruby1.8-dev ruby1.8 ri1.8 rdoc1.8 irb1.8 libreadline-ruby1.8 libruby1.8 libopenssl-ruby rubygems1.8

You can see that ruby1.8-dev package has also been installed. It is necessary to compile the C code of the gem. If you do not have ruby1.8-dev package already in your system, install it by typing the following command.

sudo apt-get install ruby1.8-dev

Create a symbolic link for ruby to be able to run ruby command from the terminal.

sudo ln -s /usr/bin/ruby1.8 /usr/bin/ruby

Install CUBRID gem by typing the following command. Do not forget to add -E flag after sudo to include the path to CUBRID.

sudo -E gem install cubrid

Here is a test_cubrid.rb file to see if CUBRID driver is correctly installed. Run the following command to execute the code:

ruby -rubygems test_cubrid.rb

Note: If you don't want to use "-rubygems" attribute, then you must copy the cubrid.so file from C:\Ruby187\lib\ruby\gems\1.8\gems\cubrid-0.65\ext to C:\Ruby187\lib\ruby\site_ruby\1.8\i386-msvcrt (the paths may vary according to your ruby installation).

CUBRID Node.js 2.0 Tutorial – What’s new? (Part II)

2013-03-21T02:03:11-07:00

The 1st part of this tutorial was focused on the new queries queuing feature. In this 2nd part of the tutorial we will show you some other new features implemented in the 2.0 release:

Support for database parameters
LOB objects handling support
Extended database schema support

And others…

Database parameters

After connecting to a database, a user can specify some “global” session parameters that will control the behavior of SQL statements transactions’ isolation level execution, the auto-commit behavior and others.

The complete list of these CUBRID database parameters is defined in the Constants.js file:

exports.CCIDbParam = {
  CCI_PARAM_ISOLATION_LEVEL   : 1,
  CCI_PARAM_LOCK_TIMEOUT      : 2,
  CCI_PARAM_MAX_STRING_LENGTH : 3,
  CCI_PARAM_AUTO_COMMIT       : 4
};

For each parameter, the CUBRID communication protocol implements a dedicated support for GET and SET operations. Therefore, in order to manipulate them, also a dedicate functionality was needed in the Node.js driver and this is what we did in the 2.0 release.

Please note one exception - the MAX_STRING_LENGTH parameter cannot be set programmatically from code; it’s a broker parameter and the client can only query its current value.

We have provided support for:

Getting a parameter value, using the getDatabaseParameter (…) method
Setting a parameter value, using the setDatabaseParameter (…) method

Let’s see some examples. First, let set the value of the ISOLATION_LEVEL parameter:

CUBRIDClient.connect(function (err) {
    CUBRIDClient.setDatabaseParameter(CAS.CCIDbParam.CCI_PARAM_ISOLATION_LEVEL,
      CAS.CUBRIDIsolationLevel.TRAN_REP_CLASS_COMMIT_INSTANCE, function (err) {
          CUBRIDClient.close(function (err) {
…

And let’s see how we can retrieve the value of the LOCK_TIMEOUT parameter for the current session:

CUBRIDClient.connect(function (err) {
  CUBRIDClient.getDatabaseParameter(CAS.CCIDbParam.CCI_PARAM_LOCK_TIMEOUT, function (err, value) {
    Helpers.logInfo('LOCK_TIMEOUT is: ' + value);
    CUBRIDClient.close(function (err) {
    });
  });
});

The output result is:

LOCK_TIMEOUT is: -1

Note: The same value can be obtained also from CUBRID Manager Client:

If you need to change the default values for these parameters, it is highly recommended to do it immediately after connect (). One consequence is that you must use an explicit connect () statement in your application, and not the “implicit connect” driver feature (the “implicit connect” feature means that the driver can auto-connect when a query is first executed, without the need to issues an explicit connect() command).

LOB objects handling

In the previous driver version, the support for LOB (CLOB/BLOB) objects was limited to query only. Now, we have implemented the completed protocol required to update such data type columns. Please note that, as in the other CUBRID drivers, we have implemented dedicated driver query functions for handling LOB objects, as follows:

lobNew(…)
lobRead(…)
lobWrite(…)

Let’s see a simple example of inserting a LOB value (the code below is an “extract” from an ActionQueue series of method calls):

…
    function (cb) {
      CUBRIDClient.lobNew(CUBRIDClient.LOB_TYPE_BLOB, cb);
    },

    function (lobObject, cb) {
      Helpers.logInfo('Number of bytes to write: ' + 2 * CUBRIDClient._LOB_MAX_IO_LENGTH);
      var data = new Buffer(2 * CUBRIDClient._LOB_MAX_IO_LENGTH);
      for (var i = 0; i < 2 * CUBRIDClient._LOB_MAX_IO_LENGTH; i++) {
        data[i] = i;
      }
      CUBRIDClient.lobWrite(lobObject, 1, data, cb);
    },

    function (lobObject, written_length, cb) {
      CUBRIDClient.executeWithTypedParams('insert into test_blob values(1, ?)', [lobObject], ['blob'], cb);
    },
…

And this is how we retrieve a LOB value:

…
    function (cb) {
      CUBRIDClient.query('select * from test_lob', cb);
    },

    function (result, queryHandle, cb) {
      var arr = Result2Array.RowsArray(result);
      var lobObject = arr[0][0];
      CUBRIDClient.lobRead(lobObject, 1, lobObject.lobLength, cb);
    },

    function (str, read_length, cb) {
…

(the str variable will contain the LOB data)

As you can see, it’s pretty simple to deal with LOB data types!

Database schema

If you remember, in the previous driver versions, we provided integrated support for querying two database schemas:

TABLEs
VIEWs

But CUBRID provides many more and some of the information cannot be obtained by querying the system objects – see, for example, the foreign keys.

Therefore, one of the things we did in this release was to improve the support for database schema, and so we add support for:

ATTRIBUTEs (Table columns)
CONSTRAINTs
PRIMARY KEYs
IMPORTED KEYs (Foreign keys)
EXPORTED KEYs
TABLE PRIVILEGEs

The method which must be used to retrieve a database schema is:

CUBRIDClient.getSchema(…)

Depending on schema, some method parameters might be mandatory!

For example, if you query the CONSTRAINTS schema, you need to provide the table name.

See the driver documentation for more details.

Let’s see an example for retrieving the list of foreign keys for a table (we will use the game table in the demodb database):

The code is pretty simple:

ActionQueue.enqueue(
  [!
    function (callback) {
      CUBRIDClient.connect(callback);
    },

    function (callback) {
      Helpers.logInfo('Getting foreign keys for the game table...');
      CUBRIDClient.getSchema(CUBRIDClient.SCHEMA_IMPORTED_KEYS, 'game', callback);
    },

    function (result, callback) {
      for (var i = 0; i < result.length; i++) {
        Helpers.logInfo(result[!i]);
      }
      }
      CUBRIDClient.close(callback);
    }
  ],
…

And the output is:

{ FkName: 'fk_game_event_code',
  PkName: 'pk_event_code',
  FkTableName: 'game',
  PkTableName: 'event',
  FkColumnName: 'event_code',
  PkColumnName: 'code',
  UpdateAction: 1,
  DeleteAction: 1 }
{ FkName: 'fk_game_athlete_code',
  PkName: 'pk_athlete_code',
  FkTableName: 'game',
  PkTableName: 'athlete',
  FkColumnName: 'athlete_code',
  PkColumnName: 'code',
  UpdateAction: 1,
  DeleteAction: 1 }

Please note that some of the database schemas can be obtained very easily by querying the appropriate system table – you don’t need the getSchema(…) method. For such schemas, we will not provide a dedicated functionality in the driver.

One simple example is the USERs schema, which can be obtained like this:

ActionQueue.enqueue(
  [!
    function (callback) {
      CUBRIDClient.connect(callback);
    },

    function (callback) {
      CUBRIDClient.query('select [name] from db_user', callback);
    },

    function (result, queryHandle, callback) {
      Helpers.logInfo(Result2Array.ColumnNamesArray(result).toString());
      var arr = Result2Array.RowsArray(result);
      for (var i = 0; i < arr.length; i++) {
        Helpers.logInfo(arr[!i].toString());
      }

      callback();
    },
…

When running this script on the demodb database, we will get the list of users defined in the demodb:

name
DBA
PUBLIC

Other features

Connection timeout

One of the requests we got for the 2.0 driver release was to implement a connection timeout feature. Simply said - wait for the connection to the database to complete within the specified number of seconds and eventually throw an error if the timeout occurs.

Obviously, the key thing here was to set the connection timeout at the Node.js socket connection layer level (and not on the consumer level):

self._socket = Net.createConnection(self.initialBrokerPort, self.brokerServer);
self._socket.setNoDelay(true);
self._socket.setTimeout(this._CONNECTION_TIMEOUT);

Now let’s see this in action:

var client = new CUBRIDConnection('10.255.255.1', 33000, 'public', '', 'demodb');

Helpers.logInfo(module.filename.toString() + ' started...');

client.setConnectionTimeout(2000);
client.connect(function (err) {
  if (err) {
    assert(err.message === ErrorMessages.ERROR_CONNECTION_TIMEOUT);
    Helpers.logInfo('Connection timeout');
…

As you see, the timeout specified is 2.000, which is 2 sec.

After the 2 seconds, the script will timeout:

Connection timeout
Process finished with exit code 0

Extended events information

Another thing we have enhanced in the 2.0 release is the events information provided to the user.

This is actually one of the key things we are constantly looking into improving in our driver – the events model – because we believe it provides many advantages over the “classical” callbacks programming model.

For example, the query() events now returns also the source SQL statement:

CUBRIDClient.connect();

CUBRIDClient.on(CUBRIDClient.EVENT_CONNECTED, function () {
  CUBRIDClient.addQuery(SQL_A, null);
});

CUBRIDClient.on(CUBRIDClient.EVENT_QUERY_DATA_AVAILABLE, function (result, queryHandle, sql) {

For more details about the events model, please take a look at the driver documentation.

Objects array

Remember that in the version 1.0, when you we were retrieving the data returned by a query, we were accessing the data using an array notation:

Helpers.logInfo(arr[!j][!0] + "," + arr[!j][!1] + "," + arr[!j][!2] + "," + arr[!j][!2]);

Now, you can also do this - use an object notation:

Helpers.logInfo(arr[!j].code + "," + arr[!j].name + "," + arr[!j].continent + "," + arr[!j].capital);

Even if it looks easier to understand, we do not recommend using the object-type notation, unless you have good reasons. This is because of one reason – the syntax errors cannot be detected at development time, but only at runtime!

What we usually recommend instead is to use named-indexes in the array notation, for example:

if (self._queriesQueue[!idx][!self._QUERY_INFO.CALLBACK] &&
    typeof(self._queriesQueue[!idx][!self._QUERY_INFO.CALLBACK]) === 'function') {

Under the hood…

In this section, we will look at some internal driver implementation details.

The queue processor

In order to have an “automatic” queue processor, which takes care of executing the statements the users added to the queue, we needed a way to implement a routine which could (auto-)execute in a recursive manner, but without blocking the events queue. And this without using a “timer”, because this is not available in Node.js.

Note: Just to clarify, when we say that the “standard timer” feature is not available in Node.js, we are referring to the Windows timer functionality, where you don’t need to auto-call the recurrent function by yourself again and again, but you simply setup the timer function handler only once and the system takes care automatically of running it without any other actions required from the application.

Here is the logical structure of this routine we have developed:

// Check if some query is still in execution - if YES, exit and retry
for (i = 0; i < self._queriesQueue.length; i++) {
  if (self._queriesQueue[!i][!self._QUERY_INFO.STATUS] === self._QUERY_STATUS.IN_EXECUTION) {
    // retry queue processing after a while
    setTimeout(function () {
      self._enableQueriesBackgroundProcessor();
    }, self._QUERIES_QUEUE_CHECK_INTERVAL);
    return;
  }
}

// Find the first query not started and execute it
for (i = 0; i < self._queriesQueue.length; i++) {
  if (self._queriesQueue[!i][!self._QUERY_INFO.STATUS] === self._QUERY_STATUS.NOT_STARTED) {
    ...
    break;
  }
}

// Re-start queries processor
setTimeout(function () {
  self._enableQueriesBackgroundProcessor();
}, self._QUERIES_QUEUE_CHECK_INTERVAL);

Tip: As you can see there is an internal parameter - _QUERIES_QUEUE_CHECK_INTERVAL - which controls after which interval the routine restart itself. The default value is 1.000 msec. If for some reason, you need a “faster” queue, you can lower down the values of this parameter, for example:

<your_CUBRIDConnection_client_instance_name>._QUERIES_QUEUE_CHECK_INTERVAL = 500;

Some backward compatibility notes

Maybe you have asked if the “old” query(…) statement is still available…

The short answer is: Yes, it is still there in the driver and not only as an empty “shell”, but complete - nothing was changed in its implementation.

We made this choice for a couple of reasons:

Not everybody will actually need the queries queue functionality
Executing a query using the ”old” query(…) function is slighter faster and uses lesser resources. The reason is obvious – you will be bypassing entirely the queue processor.

Tip: Before you start coding, think about if you need the queue processor and make the best decision for your applications. Remember, there are 3 main ways to use the driver:

Through the queries queue
Through the ActionQueue (or any similar implementation, see Async for example)
Using simple “callback-chained“ queries

References and links

CUBRID Node.js driver home page	https://github.com/CUBRID/node-cubrid https://github.com/organizations/CUBRID
Online driver documentation	https://github.com/CUBRID/node-cubrid/tree/master/documentation
Online Wiki	http://www.cubrid.org/wiki_apis/entry/cubrid-node-js-driver
Driver tutorials and examples	http://www.cubrid.org/wiki_apis/entry/cubrid-node-js-tutorials

We hope you enjoyed this tutorial!

Please let us know your feedback and suggestions, so we can improve! And do not forget, tryout the CUBRID Node.js 2.0 driver!

CUBRID ADO.NET Driver

2011-12-06T17:24:55-08:00

CUBRID ADO.NET driver is now available for download.

Download
[cubrid-ado-net-driver-installation-guide|Installation Instructions]
[cubrid-ado-net-tutorials|Latest News, Guides and Tutorials]
Questions and Answers

Documentation
[cubrid-ado-net-release-notes|Release Notes]
[ADO.NET-driver-development-notes|Development Notes]
JIRA Issue Tracker
SVN

ADO.NET driver source code is distributed under the terms of BSD open source license.

cubrid-python-driver-8-4-3-release-note

2012-11-16T00:08:27-08:00

8.4.3.0004	Fixed bugs: APIS-522: Fix the date_format error in django_cubrid. APIS-523: Fix the 'LIMIT' format error in django_cubrid.
8.4.3.0003	Fixed bugs: APIS-428: Change the setup.py to fix the pip installation failure.. APIS-426: Remove free() in insert_id function for Windows platform: merge from trunk APIS-419: Fix Py_ssize_t undefined problem in Python-2.4. This bug causes 8.4.3.0002 fail to build in Python 2.4.
8.4.3.0002	Django backend Features: In this version, the django support is developed. Django_cubrid is the django backend for CUBRID Database. Overview Django_cubrid is the official Django backend for CUBRID Database. When using Django web framework with CUBRID database, the django_cubrid backend should be used. Prerequisites * Python Being a Python Web framework, Django requires Python. It works with any Python version from 2.5 to 2.7 (due to backwards incompatibilities in Python 3.0, Django does not currently work with Python 3.0). So, when using django_cubrid, the Python version should be from 2.5 to 2.7. * Django Now only supports Django-1.4. It's tested in Django-1.4.2. Known issues * The Django sqlflush command maybe failed because of the foreign constraints between database tables. * After using the Django loaddata command, the insert SQL manipulation in the application maybe failed, becuse of the auto_increment field. * Perhaps you may encounter the below warning: RuntimeWarning: DateTimeField received a naive datetime (2013-01-15 06:38:37.463000) while time zone support is active. The reason is that CUBRID dosen't support timezone. You can set "USE_TZ" to False in settings.py to avoid this warning. Refer to How to use Django with CUBRID for more infomation. Changed and Enhanced Features: support designated charset in the key-value arguments of connect() add the mult-byte character support for the data in CUBRID support bind NULL value to sql statement support bind unicode string to sql statement support bind integer to sql statement add the iteration feature for cursor object. update the samples update the README file move the unit test cases into tests/ Fixed bugs: APIS-423: Access the major version and minor version from sys.version_info by indexing. APIS-426: The unicode keyword isn't supported in cursor() when using Python-3.x APIS-419: Add break in the switch in the _cubrid_ConnectionObject_schema_to_pyvalue().
8.4.3.0001	Fixed bugs: APIS-181: A lot of error messages will appear when sql statements is "select * from db_user". APIS-232: added escape_string() to python driver. APIS-348:add set_autocommit() and get_autocommit() in CUBRIDdb. APIS-368: Add the DatabaseError and InterfaceError exception. APIS-369:deal with None object when binding None. APIS-373: Convert NUMERIC type in CUBRID to decimal.Decimal in Python.

CUBRID Python Driver 9.1.0 release note

2013-03-15T02:34:36-07:00

9.1.0.0002

Fixed bugs:

APIS-522: Fix the date_format error in django_cubrid.
APIS-523: Fix the 'LIMIT' format error in django_cubrid.

9.1.0.0001

Django backend Features:

In this version, the django support is developed. Django_cubrid is the django backend for CUBRID Database.

Overview
Prerequisites

* Python

* Django

Known issues

* The Django sqlflush command maybe failed because of the foreign constraints between database tables.

* After using the Django loaddata command, the insert SQL manipulation in the application maybe failed, becuse of the auto_increment field.

* Perhaps you may encounter the below warning:
RuntimeWarning: DateTimeField received a naive datetime (2013-01-15 06:38:37.463000) while time zone support is active.
The reason is that CUBRID dosen't support timezone. You can set "USE_TZ" to False in settings.py to avoid this warning.

Refer to How to use Django with CUBRID for more infomation.

Changed and Enhanced Features:

Support designated charset in the key-value arguments of connect()
Add the mult-byte character support for the data in CUBRID
Support bind NULL value to sql statement
Support bind unicode string to sql statement
Support bind integer to sql statement
Add the iteration feature for cursor object.
Update the samples
Update the README file
Move the unit test cases into tests/
Enable cci_connect_with_url_ex(), cci_escape_string() in Windows platfrom

Fixed bugs:

APIS-423: Access the major version and minor version from sys.version_info by indexing.
APIS-426: The unicode keyword isn't supported in cursor() when using Python-3.x
APIS-419: Add break in the switch in the _cubrid_ConnectionObject_schema_to_pyvalue().
APIS-428: Change the setup.py to fix the pip installation failure..
APIS-433: Fix the memory leak when using insert_id function in Windows platform
APIS-444: Fix Py_ssize_t undefined problem in Python-2.4. This bug causes 8.4.3.0002 fail to build in Python 2.4.
APIS-403: Improve the invoking of cci_disconnect().
APIS-419: Add break in the switch in the _cubrid_ConnectionObject_schema_to_pyvalue().
APIS-471: Check the parameter of set_autocommit() is or not a bool.
APIS-473: Remove as_sql() and create_test_db() in django_cubrid to support Django-1.5.
APIS-482: Fix the bug when reuse a closed connection to create a cursor.