Install the psql connection tool

The psql command line tool is widely used for interacting with a PostgreSQL or TimescaleDB instance, and it is available for all operating systems. Most of the instructions in the Timescale documentation assume you are using psql.

Before you start, check that you don’t already have psql installed. It is sometimes installed by default, depending on your operating system and other packages you have installed over time:

Install psql on macOS

The psql tool is installed by default on macOS systems when you install PostgreSQL, and this is the most effective way to install the tool. On macOS you can use Homebrew or MacPorts to install the PostgreSQL package or just the psql tool.

Installing PostgreSQL package using Homebrew

  1. Install Homebrew, if you don’t already have it:

    1. /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    For more information about Homebrew, including installation instructions, see the Homebrew documentation.

  2. Make sure your Homebrew repository is up to date:

    1. brew doctor
    3. brew update

  3. Install PostgreSQL:

    1. brew install postgres

Installing PostgreSQL package using MacPorts

  1. Install MacPorts by downloading and running the package installer.. For more information about MacPorts, including installation instructions, see the MacPorts documentation.

  2. Install the latest version of Postgresql:

    1. sudo port install postgresql<xx>

    For example, to install version 14 replace postgresql<xx> with postgresql14.

  3. OptionalView the files that were installed:

    1. port contents postgresql<xx>

Installing psql on macOS

If you do not want to install the entire PostgreSQL package, you can install the psql tool on its own. libpqxx is the official C++ client API for PostgreSQL.

Installing psql using Homebrew

  1. Install Homebrew, if you don’t already have it:

    1. /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    For more information about Homebrew, including installation instructions, see the Homebrew documentation.

  2. Make sure your Homebrew repository is up to date:

    1. brew doctor
    3. brew update

  3. Install psql:

    1. brew install libpq

  4. Update your path to include the psql tool.

    1. brew link --force libpq

    On Intel chips, the symbolic link is added to /usr/local/bin. On Apple Silicon, the symbolic link is added to /opt/homebrew/bin.

Installing psql using MacPorts

  1. Install MacPorts by downloading and running the package installer. For more information about MacPorts, including installation instructions, see the MacPorts documentation.

  2. Install the latest version of libpqxx:

    1. sudo port install libpqxx

  3. OptionalView the files that were installed by libpqxx:

    1. port contents libpqxx

Install psql on Debian and Ubuntu

You can use the apt package manager on Debian and Ubuntu systems to install the psql tool.

Installing psql using the apt package manager

  1. Make sure your apt repository is up to date:

    1. sudo apt-get update

  2. Install the postgresql-client package:

    1. sudo apt-get install postgresql-client

Install psql on Windows

The psql tool is installed by default on Windows systems when you install PostgreSQL, and this is the most effective way to install the tool. These instructions use the interactive installer provided by PostgreSQL and EnterpriseDB.

Installing psql on Windows

  1. Download and run the PostgreSQL installer from www.enterprisedb.com.
  2. In the Select Components dialog, check Command Line Tools, along with any other components you want to install, and click Next.
  3. Complete the installation wizard to install the package.