1.5. Accessing a Database #
As Postgres Pro Shardman is a distributed system, it is sufficient to connect to one cluster node to connect to entire cluster. See connection details. Once you have created a database, you can access it by:
Running the Postgres Pro interactive terminal program, called psql, which allows you to interactively enter, edit, and execute SQL commands.
Writing a custom application, using one of the several available language bindings. These possibilities are discussed further in Part IV.
You probably want to start up psql
to try the examples in this tutorial. It can be activated for the mydb
database by typing the command:
$
psql mydb
If you do not supply the database name then it will default to your user account name. You already discovered this scheme in the previous section using createdb
.
In psql
, you will be greeted with the following message:
psql (17.5.1) Type "help" for help. mydb=>
mydb=#
That would mean you are a database superuser, which is most likely the case if you installed the Postgres Pro instance yourself. Being a superuser means that you are not subject to access controls. For the purposes of this tutorial that is not important.
If you encounter problems starting psql
then go back to the previous section. The diagnostics of createdb
and psql
are similar, and if the former worked the latter should work as well.
The last line printed out by psql
is the prompt, and it indicates that psql
is listening to you and that you can type SQL queries into a work space maintained by psql
. Try out these commands:
mydb=>
SELECT pgpro_version();
version ------------------------------------------------------------------------------------------ Postgres Pro Shardman 17.5.1 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0, 64-bit (1 row)mydb=>
SELECT current_date;
date ------------ 2016-01-07 (1 row)mydb=>
SELECT 2 + 2;
?column? ---------- 4 (1 row)
The psql
program has a number of internal commands that are not SQL commands. They begin with the backslash character, “\
”. For example, you can get help on the syntax of various Postgres Pro SQL commands by typing:
mydb=>
\h
To get out of psql
, type:
mydb=>
\q
and psql
will quit and return you to your command shell. (For more internal commands, type \?
at the psql
prompt.) The full capabilities of psql
are documented in psql. In this tutorial we will not use these features explicitly, but you can use them yourself when it is helpful.
Note that to connect to a Postgres Pro Shardman cluster and successfully work with it, it is sufficient to connect to one cluster node.
1.5.1. psql/libpq #
To connect to a Postgres Pro Shardman cluster, first get the connection string with psql or libpq. For more information on libpq, refer to libpq — C Library.
The value of target_session_attrs
must be set to read-write
. Only connections that allow read/write transactions are acceptable. If the connection to a cluster node is a success, the request “SHOW transaction_read_only;” is sent. If it returns on
, the connection is closed. If several servers are specified in the connection string, other servers will be iterated through, the same way as with the failed connection attempt. The target_session_attrs
parameter allows you to specify both masters and replicas of the Postgres Pro Shardman cluster.
The following examples illustrate the connection:
psql -d "dbname=postgres host=node3,node4,node2,node1 port=5432,5432,5432,5432 user=username password=password target_session_attrs=read-write"
psql postgres://username:password@node1:5432,node2:5432,node3:5432,node4:5432/postgres?target_session_attrs=read-write
1.5.2. Python #
Connection to a Postgres Pro Shardman cluster using the psycopg2 library looks like this:
import psycopg2 from psycopg2 import pool pool = psycopg2.pool.SimpleConnectionPool( min_size=1, max_size=5, user="pguser", password="*****", host="node1,node2,node3,node4", port="5432,5432,5432,5432", database="postgres", target_session_attrs="read-write") connection = pool.getconn()
A connection pool with the following parameters is created: the minimum and maximum number of connections min_size
=1 and max_size
=5. Then a specific connection to the cluster is selected, the user login and password are specified, as well as the list of nodes and TCP ports, database and connection parameters (see Section 1.5.1 for more information).
1.5.3. Java #
Connection to a Postgres Pro Shardman cluster using JDBC looks like this:
String url = "jdbc:postgresql://node1:5432,node2:5432,node3:5432,node4:5432/postgres?loadBalanceHosts=true&targetServerType=primary"; Properties props = new Properties(); props.setProperty("user","postgres"); props.setProperty("password","********"); Connection conn = DriverManager.getConnection(url, props);
url
contains the connection string, where all the available shard masters are listed. If no additional connection parameters of the JDBC driver are specified, connection to the cluster is performed through the first node available for connection. This is not always convenient. Therefore, connection string settings are added that allow using different cluster shards for different connections.
loadBalanceHosts=true
allows iterating through nodes connecting to one of them, and targetServerType=primary
indicates a need to only choose masters, then replicas can be added to the connection string.
1.5.4. Go #
Ways to connect to a Postgres Pro Shardman cluster for Go are pretty much the same as those accepted in Java or Python. You need to specify lists of nodes, their TCP ports, as well as connection parameters and choose a suitable driver.
One of these drivers for Go is pgx version 4 or 5.
The following is an example of a connection string and creation of a pool for connecting to a cluster:
dbURL := "postgres://username:password@node1:5432,node2:5432,node3:5432,node4:5432/postgres?target_session_attrs=read-write") dbPool, err := pgxpool.New(context.Background(), dbURL)
Also pay attention to the description of the target_session_attrs
parameter.