English

Client Access

This document describes how to connect to YMatrix and run queries using clients other than psql. Both high-availability (HA) and non-high-availability connection methods are covered.

The term high availability in this document refers to YMatrix's automatic failover mechanism. When the primary master node fails, service is automatically taken over by the standby master node.

A high-availability connection means that after a failover event in YMatrix, the application automatically reconnects to the new active master node.

High-availability connection strings (Connection URLs / DSN) provide a standardized format for use across different applications without re-entering full connection details.
A typical connection string consists of multiple fields, each representing specific connection information, for example:
postgres://username:password@master_ip:master_port,standby_ip:standby_port/database

Where:

username and password are the username and password used to log in to the database.
master_ip:master_port and standby_ip:standby_port contain connection information for the Master and Standby nodes.
database specifies the target database name.

1 DBeaver

Download and install the DBeaver Community or Enterprise edition from the links in the table below.

Community Edition

Operating System	CPU Architecture	Client Version
Mac	x86_64	23.0.2
Mac	AArch64	23.0.2
Linux Linux(nojdk)	x86_64	23.0.2
Linux(nojdk)	AArch64	23.0.2
Windows	x86_64	23.0.2

Enterprise Edition

Operating System	CPU Architecture	Client Version
Mac	x86_64	24.0
Mac	AArch64	24.0
Linux	x86_64	24.0
Windows	x86_64	24.0

Example environment used in this document:

macOS X (Apple Silicon chip)
DBeaver 23.0.2

Launch the DBeaver client.

Create a sample database (optional).

Click the top menu: File → New.

Select "New Database Connection".

Choose PostgreSQL.

Download required drivers.

When configuring the connection, you can choose to enable high availability as described in Enable High Availability, or not:

High-Availability Connection:
Select Connect by URL. In the URL field, enter jdbc:postgresql://<master_ip>:<master_port>,<standby_ip>:<standby_port>/<database> (replace content within < >). Enter the database administrator username mxadmin and the admin password set during YMatrix initialization to complete the setup.
Non-High-Availability Connection:
Select Connect by Host. Enter the Master node IP address, port number, administrator username mxadmin, and the password set during initialization to complete the setup.

Connection successful.

Create a new SQL script.

Write a SQL statement and click Run.

2 DbVisualizer

Download and install DbVisualizer from the links in the table below.

Operating System	CPU Architecture	Client Version
Mac	x86_64	23.1
Mac	AArch64	23.1
Linux	x86_64	23.1
Windows	x86_64	23.1
Windows	AArch64	23.1

Example environment used in this document:

macOS X (Apple Silicon chip)
DbVisualizer 23.1

Launch the DbVisualizer client.

Create a PostgreSQL connection.

During connection setup, choose whether to enable high availability:

High-Availability Connection:
First, set Settings Format to Database URL.

In Database URL, enter jdbc:postgresql://<master_ip>:<master_port>,<standby_ip>:<standby_port>/<database> (replace content within < >). Provide the database administrator username mxadmin and the password set during YMatrix initialization.

Click Connect to complete the connection.
Non-High-Availability Connection:
Enter the Master node IP, port number, administrator username mxadmin, and the password set during initialization.

Test network connectivity.

Connection successful.

Create an SQL editor.

Write and execute SQL statements successfully.

3 DataGrip

Download and install DataGrip from the links in the table below.

Operating System	CPU Architecture	Client Version
Mac	x86_64	2023.1.1
Mac	AArch64	2023.1.1
Linux	x86_64	2023.1.1
Linux	AArch64	2023.1.1
Windows	x86_64	2023.1.1
Windows	AArch64	2023.1.1

Example environment used in this document:

macOS X (Apple Silicon chip)
DataGrip 2023.1.1

Launch the DataGrip client.

Create a new project.

Select PostgreSQL as the data source.

During connection setup, choose whether to enable high availability:

High-Availability Connection:
In URL, enter jdbc:postgresql://<master_ip>:<master_port>,<standby_ip>:<standby_port>/<database> (replace content within < >). Enter the Master node IP, port number, administrator username mxadmin, and the password set during initialization to complete the setup.
Non-High-Availability Connection:
Fill in all required fields except URL, leaving it unmodified.