Skip to main content

Connect with the SingleStore Client

Note

When using the SingleStore client, or a third-party SQL client, you must first add a database user to log into a SingleStoreDB Cloud database.

The SingleStore client, similar to the MySQL client, is a lightweight Linux application that allows you to connect to SingleStoreDB Cloud and run SQL queries directly from a terminal session.

Use singlestore --help to for help and to view additional connection options.

Install SingleStore Client

Red Hat Distribution

Online Installation

For online installations where the target host can access the SingleStore YUM repository, perform the following steps.

  1. Add the SingleStore repository to your repository list.

    sudo yum-config-manager --add-repo https://release.memsql.com/production/rpm/x86_64/repodata/memsql.repo

  2. Verify that the SingleStore repo information is listed under repolist.

    sudo yum repolist

  3. Verify that the which package installed. This is used during the install process to identify the correct package type for your installation.

    rpm -q which

    If which is not installed, it must be installed before proceeding.

    sudo yum install -y which

  4. Install the SingleStore client.

    sudo yum install -y singlestore-client

Offline Installation

Download the SingleStore client package onto a host that can access your SingleStoreDB Cloudworkspace.

singlestore-client

Install the SingleStore client.

sudo rpm -ivh /tmp/singlestore-client-<version>-<commit-hash>.x86_64.rpm

Debian Distribution

Online Installation

For online installations where the target host can access the SingleStore APT repository, perform the following steps.

  1. SingleStore packages are signed to ensure integrity, so the GPG key needs to be added to this host. When done, verify that the SingleStore signing key has been added using apt-key list.

    wget -O - 'https://release.memsql.com/release-aug2018.gpg'  2>/dev/null | sudo apt-key add - && apt-key list

  2. Verify that apt-transport-https is installed.

    apt-cache policy apt-transport-https

    If apt-transport-https is not installed, it must be installed before proceeding.

    user-shell sudo apt -y install apt-transport-https

  3. Add the SingleStore repository to retrieve its packages.

    echo "deb [arch=amd64] https://release.memsql.com/production/debian memsql main" | sudo tee /etc/apt/sources.list.d/memsql.list

  4. Install the SingleStore client.

    sudo apt update && sudo apt -y install singlestore-client

Offline Installation

Download the SingleStore client package onto a host that can access your SingleStoreDB Cloudworkspace.

singlestore-client

Install the SingleStore client.

sudo dpkg -i /tmp/singlestore-client_<version>_<commit-hash>_amd64.deb

Tarball

Download the SingleStore Client

Download the SingleStore client tarball file onto a host that can access your SingleStoreDB Cloudworkspace.

singlestore-client

Unpack the SingleStore Client

Unpack the SingleStore client into a directory of your choice, such as /home/<user>/singlestore or /opt/singlestore.

tar xzvf singlestore-client-<version>-<commit-hash>.x86_64.tar.gz

Using symbolic links (or "symlinks") can make using and upgrading the SingleStore client easier. Performing the following steps will allow the singlestore command to be run from anywhere on the filesystem, even after an upgrade by updating the symlink.

  1. Navigate to the directory that contains the unpacked SingleStore client tarball file and create a singlestore-client symlink that points to the SingleStore client directory.

    ln -s singlestore-client-<version>-<commit-hash> singlestore-client

  2. Verify that the symlink has been created.

    ls -l
****
singlestore-client -> singlestore-client-1.0.6-c3803db03b

  3. Update the PATH environment variable with the path to the new singlestore-client directory. This path can also be added to your shell startup file so you won't have to run this command each time you log in.

    export PATH=/home/<user>/singlestore/singlestore-client:$PATH

  4. You may now run the singlestore command from anywhere on the filesystem.

    singlestore

Connect to Your SingleStoreDB Cloud Workspace

The singlestore_bundle.pem file is required to configure an SSL connection. Once downloaded, this file can be used to connect to all of your SingleStoreDB Cloud workspaces via SSL.

  1. Download the singlestore_bundle.pem file.

    1. Log into the SingleStore portal.

    2. Click on your workspace.

    3. Click the Connect button in the top right-hand corner of your workspace's dashboard.

    4. Under TLS/SSL Certificate, click the Download link. This will download the singlestore_bundle.pem file to your computer.

  2. To confirm that the connection is using SSL, run the following command to check the connection status.

    singlestore -h <client-endpoint> -P <port> -u <database-user> -p<database-user-password> --ssl-ca=singlestore_bundle.pem \ 
-e status

    where:

    • client-endpoint is the SingleStoreDB Cloud endpoint for your workspace

    • port is the port number to connect on (typically 3306)

    • database-user is either the database user to connect as, or the default admin user (which was created with the workspace)

    • database-user-password is the database user password.

      You may receive the following message when including the database user password on the command line:

      singlestore-client: [Warning] Using a password on the command line interface can be insecure.

      To prevent this message, leave the database user password blank and you will be prompted for the password.

    From the output, review the SSL line for the cipher in use.

    --------------
/usr/lib/singlestore-client/singlestore-client  Ver 14.14 Distrib 5.7.17, for Linux (x86_64) using  EditLine wrapper

Connection id:          17323
Current database:
Current user:           admin@
SSL:                    Cipher in use is AES128-GCM-SHA256
Current pager:          stdout
Using outfile:          ''
Using delimiter:        ;
Server version:         5.7.32 MemSQL source distribution (compatible; MySQL Enterprise & MySQL Commercial)
Protocol version:       10
Connection:             <your-workspace-endpoint> via TCP/IP
Server characterset:    utf8
Db     characterset:    utf8
Client characterset:    utf8
Conn.  characterset:    utf8
TCP port:               3306
--------------

  3. Run the following command to connect to your SingleStoreDB Cloud workspace.

    Note that this is the same command and parameters from Step 2, only without the -e status flag.

    singlestore -h <client-endpoint> -P <port> -u <database-user> -p<database-user-password> --ssl-ca=singlestore_bundle.pem

    When connected, the following (or similar) output will be displayed.

    Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 7168
Server version: 5.7.32 MemSQL source distribution (compatible; MySQL Enterprise & MySQL Commercial)

Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

singlestore>

Upgrade SingleStore Client

Red Hat Distribution

To upgrade the SingleStore client, use the same steps for upgrading any RPM package.

Online

sudo yum update -y singlestore-client

Offline

  1. Download the SingleStore client package.

    singlestore-client

  2. Upgrade the SingleStore client.

    sudo rpm -Uvh /tmp/singlestore-client-<version>-<commit-hash>.x86_64.rpm

Debian Distribution

To upgrade the SingleStore client, use the sane steps for upgrading any Debian package.

Online

sudo apt update && sudo apt install -y singlestore-client

Offline

  1. Download the SingleStore client package.

    singlestore-client

  2. Upgrade the SingleStore client.

    sudo dpkg -i /tmp/singlestore-client_<version>_<commit-hash>_amd64.deb

Tarball

To upgrade the SingleStore client, you must manually replace the existing SingleStore client with a new one.

  1. Obtain the latest version of the SingleStore client.

    curl https://release.memsql.com/production/index/memsqlclient/latest.json

    The JSON returned contains a relative path to the singlestore-client-tar file in the following format. 

    "Path": "production/tar/x86_64/singlestore-client-<version>-<commit-hash>.x86_64.tar.gz"

  2. Use wget to download the file by copying, pasting, and appending the path to https://release.memsql.com/. For example:

    wget https://release.memsql.com/production/tar/x86_64/singlestore-client-<version>-<commit-hash>.x86_64.tar.gz

    As an alternative, you may download the latest version of the SingleStore client tarball file using the following link.

    singlestore-client

  3. Place this SingleStore client tarball file on your device where the existing SingleStore client has been installed.

  4. Unpack the SingleStore client tarball file. This directory will now contain two versions of the SingleStore client: the existing version, and the new version.

    tar xzvf singlestore-client-<version>-<commit-hash>.x86_64.tar.gz

Using symbolic links (or "symlinks") can make using and upgrading the SingleStore client easier. Performing the following steps will allow the singlestore command to be run from anywhere on the filesystem, even after an upgrade.

  1. Check if a singlestore-client symlink already exists within the current directory.

    ls -l

    If so, remove the existing singlestore-client symlink.

    rm singlestore-client

  2. Create a singlestore-client symlink by pointing it to the new version of the SingleStore client directory.

    ln -s singlestore-client-<version>-<commit-hash> singlestore-client

  3. Verify that the symlink has been created.

    ls -l
****
singlestore-client -> singlestore-client-1.0.6-c3803db03b

  4. Update the PATH environment variable with the path to the new singlestore-client directory. This path can also be added to your shell startup file so you won't have to run this command each time you log in.

    export PATH=/home/<user>/singlestore/singlestore-client:$PATH

  5. You may now run the singlestore command from anywhere on the filesystem.

    singlestore

The upgrade is now complete.

Should you encounter any issues with the new SingleStore client, you can simply point the singlestore-client symlink back to the previous version.

After validating that the new version of the SingleStore client is working as expected, you may remove the previous version.

rm -rf singlestore-client-<version>-<commit-hash>

Uninstall SingleStore Client

Red Hat Distribution

Important

The remove command and -e flag will only remove the binaries in the package and not remove any configuration files.

Run the following command to uninstall the SingleStore client.

Online

sudo yum remove singlestore-client

Offline

sudo rpm -e singlestore-client

Debian Distribution

Run the following command to uninstall the SingleStore client.

Important

The purge command and -P flag will remove the binaries in the package as well as any configuration files.

To keep the configuration files, use the remove command or -r flag instead.

Online

sudo apt purge singlestore-client

Offline

sudo dpkg -P /tmp/singlestore-client_<version>_<commit-hash>_amd64.deb

Tarball

Run the following commands to uninstall the SingleStore client.

  1. Change to the directory where the SingleStore client has been installed.

    cd /home/<user>/singlestore

  2. Remove the SingleStore client directory (or directories, if more than one version has been installed).

    rm -rf singlestore-client-<version>-<commit-hash>
In this section: