machcli

Since v8.0.75

machcli 모듈은 JSH 애플리케이션에서 Machbase 데이터베이스를 사용할 수 있는 클라이언트 API를 제공합니다.

Client

데이터베이스 클라이언트를 생성합니다.

사용 형식

new Client(config)

설정 필드

host (기본값: 127.0.0.1)
port (기본값: 5656)
user (기본값: sys)
password (기본값: manager)
alternativeHost (선택)
alternativePort (선택)
database (선택): 멀티 데이터베이스 환경에서 연결에 사용할 대상 데이터베이스 (별칭: db) Since v8.7.0

사용 예시

1
2
const { Client } = require('machcli');
const db = new Client({ host: '127.0.0.1', port: 5656, user: 'sys', password: 'manager' });

멀티 데이터베이스 예시

클라이언트 생성 시 database를 지정하면 연결에 사용할 대상 데이터베이스를 선택할 수 있습니다. db는 database의 별칭입니다. Since v8.7.0

1
2
3
4
5
6
7
8
9
const { Client } = require('machcli');
const db = new Client({
    host: '127.0.0.1',
    port: 5656,
    user: 'sys',
    password: 'manager',
    db: 'MACHBASEDB',
});
const conn = db.connect();

Client.connect()

연결을 열고 Connection 객체를 반환합니다.

사용 형식

connect()

Client.close()

내부 데이터베이스 클라이언트를 종료합니다.

사용 형식

close()

Client.user()

설정된 사용자 이름(대문자)을 반환합니다.

사용 형식

user()

Client.normalizeTableName()

테이블 이름을 [database, user, table] 형식으로 정규화합니다.

사용 형식

normalizeTableName(tableName)

Client.tx()

Since v8.7.0

풀에서 가져온 연결로 트랜잭션을 열고 그 안에서 fn을 실행합니다. fn이 정상적으로 반환되면 트랜잭션을 커밋하고, fn이 예외를 던지면 트랜잭션을 롤백한 뒤 그 예외를 다시 던집니다. fn에는 해당 트랜잭션에 바인딩된 Connection이 전달되므로, 이 객체의 query()/queryRow()/exec() 호출은 같은 트랜잭션 안에서 수행됩니다.

⚠️

트랜잭션은 CREATE TABLE로 생성한 일반(트랜잭션) 테이블에서만 동작합니다. 로그 테이블(CREATE LOG TABLE)과 태그 테이블(CREATE TAG TABLE)은 트랜잭션을 지원하지 않으며, tx() 안에서 이런 테이블에 대해 exec()/query()를 실행하면 MACHCLI-ERR-2362와 같은 오류가 발생합니다.

사용 형식

tx(fn)

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
const { Client } = require('machcli');
const db = new Client({ host: '127.0.0.1', port: 5656, user: 'sys', password: 'manager' });
const conn = db.connect();
conn.exec('CREATE TABLE IF NOT EXISTS TX_SAMPLE (ID LONG, NAME VARCHAR(100))');

// fn이 정상적으로 반환되면 자동으로 커밋됩니다.
db.tx(function (tx) {
    tx.exec('INSERT INTO TX_SAMPLE VALUES(?, ?)', 1, 'committed');
});

// fn이 예외를 던지면 롤백 후 그 예외를 다시 던집니다.
try {
    db.tx(function (tx) {
        tx.exec('INSERT INTO TX_SAMPLE VALUES(?, ?)', 2, 'rolledback');
        throw new Error('abort');
    });
} catch (e) {
    console.println('rolled back:', e.message);
}
conn.close();
db.close();

Connection

Client.connect()가 반환하는 연결 객체입니다.

Connection.query()

조회 SQL을 실행하고 Rows 객체를 반환합니다. params에는 ? 위치 지정 파라미터를 위한 가변 인자를 전달합니다. 또는 :key 네임드 파라미터를 위한 { key: value, ... } 객체를 전달할 수 있습니다 Since v8.7.0 .

사용 형식

query(sql[, ...params])

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
const { Client } = require('machcli');
var db, conn, rows;
const conf = {
    host: '127.0.0.1',
    port: 5656,
    user: 'sys',
    password: 'manager' 
};
try {
    db = new Client(conf);
    conn = db.connect();

    // 위치 지정 파라미터
    rows = conn.query('SELECT NAME, TIME, VALUE FROM TAG LIMIT ?', 1);
    for (const row of rows) {
        console.println(row.NAME, row.TIME, row.VALUE);
    }
    rows.close();

    // 네임드 파라미터
    rows = conn.query('SELECT NAME, TIME, VALUE FROM TAG WHERE NAME = :name ORDER BY TIME LIMIT :one', { name: 'jsh', one: 1 });
    for (const row of rows) {
        console.println(row.NAME, row.TIME, row.VALUE);
    }
    rows.close();
} catch( e ) {
    console.println("ERROR", e.message);
}
db && db.close();

Connection.queryRow()

조회 SQL을 실행하고 단일 행 객체를 반환합니다.

반환 객체에는 _ROWNUM과 각 컬럼명이 프로퍼티로 포함됩니다.

사용 형식

queryRow(sql[, ...params])

Connection.exec()

DDL/DML을 실행하고 결과 객체를 반환합니다.

반환 필드:

rowsAffected
message

사용 형식

exec(sql[, ...params])

Connection.explain()

실행 계획 문자열을 반환합니다.

사용 형식

explain(sql[, ...params])

Connection.append()

대량 입력용 appender 객체를 생성합니다.

반환된 appender는 append(), flush(), close() 같은 메서드를 지원합니다.

사용 형식

append(tableName)

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const { Client } = require('machcli');
const db = new Client({ host: '127.0.0.1', port: 5656, user: 'sys', password: 'manager' });
const conn = db.connect();
const appender = conn.append('TAG');
appender.append('sensor-1', new Date(), 12.34);
appender.flush();
const result = appender.close();
console.println(result);
conn.close();
db.close();

Connection.tx()

Since v8.7.0

이 연결 위에서 트랜잭션을 열고 그 안에서 fn을 실행합니다. 커밋/롤백 동작은 Client.tx()와 동일합니다. 이미 확보해 둔 연결(예: Client.connect()가 반환한 연결) 위에서 트랜잭션을 실행해야 할 때 사용합니다.

⚠️

사용 형식

tx(fn)

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
const { Client } = require('machcli');
const db = new Client({ host: '127.0.0.1', port: 5656, user: 'sys', password: 'manager' });
const conn = db.connect();
conn.exec('CREATE TABLE IF NOT EXISTS TX_SAMPLE (ID LONG, NAME VARCHAR(100))');

conn.tx(function (tx) {
    tx.exec('INSERT INTO TX_SAMPLE VALUES(?, ?)', 1, 'committed');
});

conn.close();
db.close();

Connection.close()

연결을 종료합니다.

사용 형식

close()

Rows

Connection.query()가 반환하는 결과 집합 객체입니다.

Rows.message

조회 실행 결과 메시지입니다.

Rows.isFetchable()

행을 가져올 수 있는 결과인지 반환합니다.

사용 형식

isFetchable()

Rows.next()

이터레이터 결과 객체를 반환합니다.

행이 있으면 { value: Row, done: false }
완료되면 { done: true }

사용 형식

next()

Rows.close()

결과 집합을 닫습니다.

사용 형식

close()

Row

조회된 행을 나타내는 객체입니다.

각 컬럼은 row.COLUMN_NAME으로 접근할 수 있습니다.
for...of 반복을 지원합니다.

queryDatabaseId()

마운트된 데이터베이스의 backup tablespace ID를 반환합니다.

기본 DB('' 또는 MACHBASEDB)는 -1 반환
데이터베이스가 없으면 예외를 발생시킵니다.

사용 형식

queryDatabaseId(conn, dbName)

queryTableType()

정규화된 테이블 이름 토큰으로 테이블 타입 코드를 반환합니다.

사용 형식

queryTableType(conn, names)

TableType

stringTableType()

테이블 타입 상수와 문자열 변환 함수입니다.

TableType 값

Log, Fixed, Volatile, Lookup, KeyValue, Tag

사용 형식

stringTableType(type)

TableFlag

stringTableFlag()

테이블 플래그 상수와 문자열 변환 함수입니다.

TableFlag 값

None, Data, Rollup, Meta, Stat

사용 형식

stringTableFlag(flag)

stringTableDescription()

테이블 타입/플래그를 결합한 설명 문자열을 반환합니다.

사용 형식

stringTableDescription(type, flag)

ColumnType

stringColumnType()

컬럼 타입 상수와 문자열 변환 함수입니다.

주요 ColumnType 값

Short, UShort, Integer, UInteger, Long, ULong
Float, Double, Varchar, Text, Clob, Blob, Binary
Datetime, IPv4, IPv6, JSON

사용 형식

stringColumnType(columnType)

columnWidth()

컬럼 타입의 기본 표시 폭을 반환합니다.

사용 형식

columnWidth(columnType, length)

ColumnFlag

stringColumnFlag()

컬럼 플래그 상수와 문자열 변환 함수입니다.

ColumnFlag 값

TagName
Basetime
Summarized
MetaColumn

사용 형식

stringColumnFlag(flag)

최근 업데이트 Sep 9, 2026

http mqtt