This topic describes how to download and install polartools.

Background information

polartools is a collection of PolarDB client tools for Linux. polartools includes the following tools:

  • polarplus: the tool used by clients to connect to PolarDB databases that are compatible with Oracle syntax.

    For more information, see polarplus.

  • psql: the tool used by clients to connect to native PostgreSQL databases.

    For more information, visit the documentation of PostgreSQL psql.

  • pg_basebackup: the physical backup tool for PostgreSQL.

    For more information, visit the documentation of PostgreSQL pg_basebackup.

  • pg_dump: the logical backup tool of PostgreSQL. You can use this tool to back up one database of a cluster at a time.

    For more information, visit the documentation of PostgreSQL pg_pgdump.

  • pg_dumpall: the logical backup tool of PostgreSQL. You can use this tool to back up all the databases of a cluster at a time.

    For more information, visit the documentation of PostgreSQL pg_pgdumpall.

  • pg_restore: the tool used to restore PostgreSQL databases based on backup files. The backup files are created by pg_dump and pg_dumpall.

    For more information, visit the documentation of PostgreSQL pg_restore.

This topic describes how to use polarplus. For more information about other tools, visit the PostgreSQL documentation.

Download polartools

To use polartools, download the polartools package and uncompress the package. Client tools of PolarDB-O and PolarDB for PostgreSQL are available.

  • Client tools of PolarDB-O are stored in the ora/bin directory.
  • Client tools of PolarDB for PostgreSQL are stored in the pg/bin directory.

polartools has the following directory structure:

polartools
├── ora
│   ├── bin
│   ├── etc
│   │   └── sysconfig
│   ├── help
│   └── lib
└── pg
    ├── bin
    └── lib

If you want to use a tool, you must add the path of the tool to the PATH environment variable.

bin
├── pg_basebackup
├── pg_dump
├── pg_dumpall
├── pg_restore
├── polarplusLauncher.sh
├── polarplus.sh
└── psql

polarplus

polarplus is a utility that provides a command-line interface (CLI) for PolarDB. polarplus supports Structured Query Language (SQL) statements, Stored Procedure Language (SPL) anonymous blocks, and polarplus commands.

polarplus provides the following features:

  • Queries a specified database object.
  • Executes a stored procedure.
  • Formats SQL statement outputs.
  • Runs multiple scripts in a query.
  • Runs operating system commands.
  • Retains output logs.

To download and configure polarplus, follow these steps:

Note polarplus is dependent on the following items:
  • Java Development Kit (JDK) 1.8 (x64)
  • OpenSSL 1.1 (x64)
  1. In the CLI, run the wget command to download polartools. For more information about the download address, see Download polartools.
  2. Uncompress the polartools-linux.zip file.
    tar -zxf polartools.tar.gz
    The following figure shows the uncompressed file.Uncompressed polartools
  3. Go to the bin folder in the ora directory.
  4. Open the polarplus.sh file.
  5. Modify export base="/home/adger.lj/polartools/ora" by replacing /home/adger.lj with the absolute path where the polartools folder is located.
    polartools
  6. To start polarplus, run the following command on the Elastic Compute Service (ECS) instance or the server that connects to a PolarDB database:
    polarplus [ -S[ILENT ] ] [ login | /NOLOG ] [ @scriptfile[.ext ] ]
    Parameter Description
    -S[ILENT ] If you specify this parameter, the polarplus logon banner and all relevant messages are disabled.
    login The logon information that is used to connect to the database server and the database.

    Enter the logon information in the following format:

    username[/password][@{connectstring | variable } ]

    For more information, see Table 1.

    The variable parameter specifies a variable that is defined in the login.sql file. This file contains a database connection string.

    /NOLOG If you specify /NOLOG when you start polarplus, no database connection is established. If you need to connect to a database to execute SQL statements or run polarplus commands, do not use this mode.
    Note After you start polarplus by specifying / NOLOG, you can execute the CONNECT statement to connect to a database.
    scriptfile[.ext ] scriptfile specifies the name of the file that is located in the current directory. This file contains SQL statements that are automatically executed and polarplus commands that automatically run after you start polarplus.
    .ext specifies the file name extension. If the file name extension is .sql, you can omit the .sql extension when you specify a script file. When you create a script file, name the file with the extension. Otherwise, polarplus cannot access the file.
    Note polarplus processes the files whose names do not contain file name extensions as .sql files.
    Table 1. Logon information
    Parameter Description
    username The username used to connect to a database.
    password The password associated with the specified username.
    connectstring The database connection string is provided in the following format:
    host[:port][/dbname][? ssl={true | false}]
    • The host parameter specifies the hostname or the IP address of a database server.
      Note If you do not specify connectstring, variable, or NOLOG, the default host is the on-premises host.
    • If you use an Internet Protocol version 6 (IPv6) address to connect to a database, you must place the IP address in brackets ([]).

      The following example shows how to use an IPv6 address to connect to a database:

      polarplus  polardb/password@[fe80::20c:29ff:fe7c:78b2]:5444/polardb
    • The port parameter specifies the port number on the database server to receive connection requests.
      Note If the port number is not specified, the default value is 5444.
    • The dbname parameter specifies the name of the database to connect to.
    • If you require secure sockets layer (SSL) connections, the connection string must include ? ssl = true and host:port. If the SSL parameter is not specified, the default value is false.

    The following example shows how to use polarplus to connect to a PolarDB database:

    polarplus  polardb/password@pc-bp1zxxxxxxxxxxx.o.polardb.rds.aliyuncs.com:1521/polardb