编程语言接入

本文档介绍了如何使用编程语言连接 YMatrix 并进行查询。将给出高可用连接与非高可用连接两种方式。

高可用指的是 YMatrix 的故障自动转移机制，主节点（Master）发生故障后，由主节点备用节点（Standby）对外提供服务。

高可用连接是指 YMatrix 发生故障自动转移后，程序自动连接到故障转移后的节点。

高可用连接字符串（Connection URLs / DSN）提供了一种标准化的格式，可以在不同的应用程序中使用，而无需重新输入完整的连接信息。
它通常由多个字段组成，每个字段表示不同的连接信息，例如：
postgres://username:password@master_ip:master_port,standby_ip:standby_port/database?sslmode=disable

其中：

username 和 password 分别是登录数据库的用户名和密码。
master_ip:master_port 与 standby_ip:standby_port 为 Master 和 Standby 的连接信息。
database 表示要连接的数据库名。
sslmode 表示是否启用 SSL 连接。

注意！
YMatrix 支持通过 MatrixGate API 接口高速写入数据，详见编程语言写入 MatrixGate。

编程语言接入示例有如下几种：

JAVA（高可用）
Python（高可用）
Golang（高可用）
C/C++（非高可用）

创建示例用户 ymatrix，密码为 1234。

=# CREATE USER ymatrix PASSWORD '1234';

Master IP：172.16.100.81；Port：5432
Standby IP：172.16.100.82；Port：5432
Database：ymatrixdb

1 JAVA（高可用）

推荐使用官方的驱动 PostgreSQL JDBC Driver 作为数据库连接驱动程序。

package com.postgresqltutorial;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
public class App{
    private final String url = "jdbc:postgres://ymatrix:1234@172.16.100.81:5432,172.16.100.82:5432/ymatrixdb?sslmode=disable"; 
    private final String user = "ymatrix";
    private final String password = "1234";
    /**
     * Connect to the YMatrix database
     *
     * @return a Connection object
     */
    public Connection connect() {
        Connection conn = null;
        try {
            conn = DriverManager.getConnection(url, user, password);
            System.out.println("Connected to the YMatrix server successfully.");
        } catch (SQLException e) {
            System.out.println(e.getMessage());
        }
        return conn;
    }
    /**
     * @param args the command line arguments
     */
    public static void main(String[] args) {
        App app = new App();
        app.connect();
    }
}

2 Python（高可用）

推荐使用 psycopg 2/3 作为数据库连接驱动程序。

# -*- coding: utf-8 -*-
import psycopg2

class YMatrix(object):
    def __init__(self):
        self.dsn = "postgres://ymatrix:1234@172.16.100.81:5432,172.16.100.82:5432/ymatrixdb?sslmode=disable"

    def get_conn(self):
        conn = psycopg2.connect(dsn=self.dsn)
        return conn

    def create_table(self):
        conn = self.get_conn()
        cursor = conn.cursor()
        sql = "CREATE TABLE data(" \
              "time timestamp," \
              "tag_id int," \
              "metrics1 float8," \
              "metrics2 float8," \
              "metrics3 float8" \
              ")Distributed by(tag_id)"
        cursor.execute(sql)
        conn.commit()
        conn.close()

    def insert(self):
        conn = self.get_conn()
        cursor = conn.cursor()
        sql = "INSERT INTO data VALUES(now(), 1, 1.1, 1.2, 1.3)"
        cursor.execute(sql)
        conn.commit()
        conn.close()

    def select(self):
        conn = self.get_conn()
        cursor = conn.cursor()
        sql = "SELECT * FROM data"
        cursor.execute(sql)
        data = cursor.fetchone()
        conn.commit()
        conn.close()
        return data

if __name__ == '__main__':
    mxdb = YMatrix()
    mxdb.create_table()
    mxdb.insert()
    print(mxdb.select())

3 Golang（高可用）

推荐使用 pgx 作为数据库连接驱动程序。

package main

import (
    "context"
    "fmt"
    "github.com/jackc/pgx/v4"
)

func main() {
    // 构建连接配置
    dsn := "postgres://ymatrix:1234@172.16.100.81:5432,172.16.100.82:5432/ymatrixdb?sslmode=disable"
    config, err := pgx.ParseConfig(dsn)
    if err != nil {
        fmt.Println("Unable to parse config:", err)
        return
    }
    // 连接数据库
    conn, err := pgx.ConnectConfig(context.Background(), config)
    if err != nil {
        fmt.Println("Unable to connect to database:", err)
        return
    }
    defer conn.Close(context.Background())
}

4 C / C++（非高可用）

YMatrix 支持 C / C++ 编程语言接入数据库，但不支持高可用的连接方式。

在此给出两种常用的驱动接入说明。

4.1 ODBC

ODBC 是基于 LGPL（GNU Lesser General Public License）协议的开源版本，可以在PostgreSQL 官网下载。

应用连接 ODBC 请参照这里和 C# 连接到 PostgreSQL。

4.2 libpq

libpq 是 YMatrix 的 C 语言接口，在 C 程序中通过 libpq 库访问 YMatrix 并进行数据库操作。在安装了 YMatrix 之后，在 lib 目录下可以找到其静态库和动态库。