编程语言接入

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

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

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

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

其中:

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

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


创建示例用户 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" \
              ")USING MARS3" \
              "DISTRIBUTED BY (tag_id)" \
              "ORDER 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:<password>@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 Ruby(高可用)

推荐使用 Ruby 3.3.3 或以上版本。

4.1 驱动安装

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

gem install pg -v 1.3.5 -- --with-pg-config=/opt/ymatrix/matrixdb5/bin/pg_config
Fetching pg-1.3.5.gem
Building native extensions with: '--with-pg-config=/opt/ymatrix/matrixdb5/bin/pg_config'
This could take a while...
Successfully installed pg-1.3.5
Parsing documentation for pg-1.3.5
Installing ri documentation for pg-1.3.5
Done installing documentation for pg after 1 seconds
1 gem installed

4.2 编程

require 'pg'
# 构建连接配置
dsn = "postgres://ymatrix:1234@172.16.100.81:5432,172.16.100.82:5432/ymatrixdb?sslmode=disable"
conn = PG.connect(dsn)
# 执行数据库操作
begin
  conn.exec('SELECT * FROM table_name') do |result|
    result.each do |row|
      # 处理每一行数据
      puts row.inspect
    end
  end
rescue PG::Error => e
  puts "执行数据库操作时发生错误:#{e.message}"
ensure
  # 关闭数据库连接
  conn.close if conn
end


5 Rust(高可用)

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

use postgres::{Client, Error, NoTls};
fn main() -> Result<(), Error> {
    let mut client = Client::connect(
        "postgresql://ymatrix:1234@172.16.100.81:5432,172.16.100.82:5432/ymatrixdb",
        NoTls,
    )?;
    for row in client.query("SELECT * FROM table_name", &[])? {
        let id: i32 = row.get(0);
        let name: String = row.get(1);
        println!("ID: {}, Name: {}", id, name);
        // 在这里可以进行你需要的数据处理操作
    }
    Ok(())
}


6 C#(高可用)

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

C#
using System;
using Npgsql;
class Program
{
    static void Main()
    {
        // 配置高可用 DSN
        var connectionString = "Host=sdw1, sdw2;Port=5432;Database=mydatabase;Username=myuser;Password=mypassword;Load Balance Hosts=true";
        // 创建数据库连接
        using var connection = new NpgsqlConnection(connectionString);
        try
        {
            // 打开数据库连接
            connection.Open();
            // 执行数据库操作
            using var command = new NpgsqlCommand("SELECT * FROM table_name", connection);
            using var reader = command.ExecuteReader();
            // 处理查询结果
            while (reader.Read())
            {
                // 处理每一行数据
                var column1Value = reader.GetString(0);
                var column2Value = reader.GetInt32(1);
                Console.WriteLine($"{column1Value}, {column2Value}");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An error occurred: {ex.Message}");
        }
    }
}


7 C / C++(高可用)

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

注意! 以下命令均需要使用 root 用户或通过 sudo 权限执行。

下载并安装 ODBC。

# yum install -y unixODBC.x86_64
# yum install -y postgresql-odbc.x86_64

编辑 ODBC 相关文件。

# cat /usr/local/etc/odbcinst.ini
[PostgreSQL]
Description = ODBC for PostgreSQL
Driver      = /usr/lib/psqlodbcw.so
Setup       = /usr/lib/libodbcpsqlS.so
Driver64    = /usr/lib64/psqlodbcw.so
Setup64     = /usr/lib64/libodbcpsqlS.so
FileUsage = 1

# cat /usr/local/etc/odbc.ini
[pg]
Description = Test to pg
Driver = PostgreSQL
Database = test
// “<>” 内内容需替换为实际集群信息,并去掉 “<>” 符号
Servername = <Master,Standby>
UserName = mxadmin
Password = mxadmin
Port = <Master Port,Standby Port>
ReadOnly = 0

编辑 C/C++ 相关文件。

# cat test.c

#include <stdio.h>
#include <sql.h>
#include <sqlext.h>
#include <string.h>
#include <sqltypes.h>

int main()
{
    SQLHENV henv;
    SQLHDBC hdbc;
    SQLHSTMT hstmt;
    SQLRETURN ret;

    // 分配环境句柄
    ret = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
    // 设置环境属性
    ret = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER)SQL_OV_ODBC3, 0);
    // 分配连接句柄
    ret = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
    // 连接到数据库
    ret = SQLConnect(hdbc, "pg", SQL_NTS, "mxadmin", SQL_NTS, "mxadmin", SQL_NTS);
    if (ret == SQL_SUCCESS || ret == SQL_SUCCESS_WITH_INFO)
    {
        printf("Connected to PostgreSQL database successfully.\n");

        // 创建表,需将 <tablename> 替换为实际信息
        ret = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
        ret = SQLExecDirect(hstmt, "CREATE TABLE <tablename> (id int) USING MARS3 DISTRIBUTED BY (id) ORDER BY (id)", SQL_NTS);
        if (ret == SQL_SUCCESS || ret == SQL_SUCCESS_WITH_INFO)
        {
                printf("成功创建表<tablename>.\n");
        }
        // 断开数据库连接
        SQLDisconnect(hdbc);
    }
    else
    {
        printf("Failed to connect to PostgreSQL database.\n");
    }
    // 释放句柄
    SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
    SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
    SQLFreeHandle(SQL_HANDLE_ENV, henv);

    return 0;
}

编译。

# gcc -lodbc -o test test.c

运行。

# ./test
Connected to PostgreSQL database successfully.

确认表已成功创建。

=#  \d <tablename>
              Table "public.test2"
 Column |  Type   | Collation | Nullable | Default
--------+---------+-----------+----------+---------
 id     | integer |           |          |
Distributed by: (id)


8 NodeJS(高可用)

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

const postgres = require('postgres')

async function query() {
  // 创建高可用数据库连接
  const conn = postgres(`postgres://username:password@master,stanby:port/database?sslmode=disable`)
  try {
    // 执行查询 SQL
    const rows = await conn`SELECT id, name FROM users`
    rows.forEach(row => {
      console.log(`id: ${row.id}, name: ${row.name}`)
    })
  } catch (err) {
    console.error(err)
  } finally {
    // 关闭连接
    await conn.end()
  }
}

query()


9 PHP(高可用)

推荐使用 PHP 7.4 或更高版本。

9.1 驱动安装

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

# 1. 生成 configure 文件
[root@ymatrix] cd /root/php-7.4.9/ext/pgsql
[root@ymatrix] /usr/local/php74/bin/phpize

Configuring for:
PHP Api Version:         20190902
Zend Module Api No:      20190902
Zend Extension Api No:   320190902

# 2. 添加环境变量,执行config,配置路径一定是目标 php 版本的路径,pgsql 的路径填写 YMatrix 的软件路径
[root@ymatrix] ./configure --with-php-config=/usr/local/php74/bin/php-config --with-pgsql=/opt/ymatrix/matrixdb5/

# 3. 编译安装
[root@ymatrix] make & make install

Installing shared extensions:     /usr/local/php74/lib/php/extensions/no-debug-non-zts-20190902/

# 4. 检查安装结果
[root@ymatrix] ls /usr/local/php74/lib/php/extensions/no-debug-non-zts-20190902/

pgsql.so

9.2 安装 pdo_pgsql

# 1. 生成 configure 文件
[root@ymatrix] cd /root/php-7.4.9/ext/pdo_pgsql
[root@ymatrix] /usr/local/php74/bin/phpize

Configuring for:
PHP Api Version:         20190902
Zend Module Api No:      20190902
Zend Extension Api No:   320190902

# 2. 添加环境变量,执行config,配置路径一定是目标 php 版本的路径,pgsql 的路径填写 YMatrix 的软件路径
[root@ymatrix] ./configure --with-php-config=/usr/local/php74/bin/php-config --with-pgsql=/opt/ymatrix/matrixdb5/

# 3. 编译安装
[root@ymatrix] make & make install

Installing shared extensions:     /usr/local/php74/lib/php/extensions/no-debug-non-zts-20190902/

# 4. 检查安装结果
[root@ymatrix] ls /usr/local/php74/lib/php/extensions/no-debug-non-zts-20190902/

pdo_pgsql.so  pgsql.so

9.3 配置并重启 php-fpm

[root@ymatrix] echo "extension=pgsql.so" >> /usr/local/php74/etc/php.ini
[root@ymatrix] echo "extension=pdo_pgsql.so" >> /usr/local/php74/etc/php.ini
[root@ymatrix] systemctl restart php-fpm

9.4 编程

<?php
  $host    = "host=172.16.100.81,172.16.100.82";
  $port    = "port=5432";
  $dbname   = "dbname=postgres";
  $credentials = "user=mxadmin password=mxadmin";
  $db = pg_connect( "$host $port $dbname $credentials" );
  if(!$db){
   echo "Error : Unable to open database\n";
  } else {
   echo "Opened database successfully\n";
  }
  $sql =<<<EOF
   CREATE TABLE COMPANY
   (ID INT PRIMARY KEY   NOT NULL,
   NAME      TEXT  NOT NULL,
   AGE      INT   NOT NULL,
   ADDRESS    CHAR(50),
   SALARY     REAL);
EOF;
  $ret = pg_query($db, $sql);
  if(!$ret){
   echo pg_last_error($db);
  } else {
   echo "Table created successfully\n";
  }
  pg_close($db);
?>


10 Perl(高可用)

推荐使用 Perl 5 的 5.40.0 或更高版本。

10.1 安装 Perl DBI 模块

# 1. 准备安装包
[root@ymatrix] wget http://search.cpan.org/CPAN/authors/id/T/TI/TIMB/DBI-1.625.tar.gz
[root@ymatrix] tar xvfz DBI-1.625.tar.gz
[root@ymatrix] cd DBI-1.625


# 2. 编译安装
[root@ymatrix] perl Makefile.PL
[root@ymatrix] make
[root@ymatrix] make install

10.2 安装 DBD-Pg 模块

# 1. 准备安装包
[root@ymatrix] wget http://search.cpan.org/CPAN/authors/id/T/TU/TURNSTEP/DBD-Pg-2.19.3.tar.gz
[root@ymatrix] tar xvfz DBD-Pg-2.19.3.tar.gz
[root@ymatrix] cd DBD-Pg-2.19.3

# 2. 编译安装
# 提示输入 major version number 时键入 12 并按回车键继续
# 提示输入 minor version number 时键入 0 并按回车键继续
# 提示输入 patch version number 时键入 0 并按回车键继续
[root@ymatrix] export POSTGRES_HOME="/opt/ymatrix/matrixdb5/"
[root@ymatrix] perl Makefile.PL
[root@ymatrix] make
[root@ymatrix] make install

10.3 编程

#!/usr/bin/perl

use DBI;
use strict;

my $driver   = "Pg";
my $database = "postgres";
my $dsn = "DBI:$driver:dbname=$database;host=172.16.100.107,172.16.100.108;port=5432";
my $userid = "mxadmin";
my $password = "mxadmin";
my $dbh = DBI->connect($dsn, $userid, $password, { RaiseError => 1 })
   or die $DBI::errstr;
print "Opened database successfully\n";

my $stmt = qq(CREATE TABLE COMPANY
      (ID INT PRIMARY KEY     NOT NULL,
      NAME           TEXT    NOT NULL,
      AGE            INT     NOT NULL,
      ADDRESS        CHAR(50),
      SALARY         REAL););
my $rv = $dbh->do($stmt);
if($rv < 0) {
   print $DBI::errstr;
} else {
   print "Table created successfully\n";
}
$dbh->disconnect();
Close menu