diff --git a/_partials/_grafana-connect.md b/_partials/_grafana-connect.md index efd81e42c1..afca26fb25 100644 --- a/_partials/_grafana-connect.md +++ b/_partials/_grafana-connect.md @@ -1,11 +1,14 @@ ## Prerequisites -* [Create a target $SERVICE_LONG][create-service] -* Install [self-managed Grafana][grafana-self-managed], or sign up for [Grafana Cloud][grafana-cloud] +import IntegrationPrereqs from "versionContent/_partials/_integration-prereqs.mdx"; -## Add your $SERVICE_LONG as a data source + -To connect the data in your $SERVICE_LONG to Grafana: +* Install [self-managed Grafana][grafana-self-managed] or sign up for [Grafana Cloud][grafana-cloud]. + +## Add your $SERVICE_SHORT or database as a data source + +To connect the data in your $SERVICE_SHORT to Grafana: @@ -14,27 +17,16 @@ To connect the data in your $SERVICE_LONG to Grafana: In your browser, log in to either: - Self-hosted Grafana: at `http://localhost:3000/`. The default credentials are `admin`, `admin`. - Grafana Cloud: use the URL and credentials you set when you created your account. -1. **Add your $SERVICE_LONG as a data source** +1. **Add your $SERVICE_SHORT as a data source** 1. Open `Connections` > `Data sources`, then click `Add new data source`. 1. Select `PostgreSQL` from the list. - 1. Configure the following fields: - - `Host URL`: the host and port for your $SERVICE_SHORT, in this format: `:`. - - `Database name`: the name to use for the dataset. - - `Username`: `tsdbadmin`, or another privileged user. - - `Password`: the password for `User`. - - `Database`: `tsdb`. + 1. Configure the connection: + - `Host URL`, `Username`, `Password`, and `Database`: configure using your [connection details][connection-info]. + - `Database name`: provide the name for your dataset. - `TLS/SSL Mode`: select `require`. - `PostgreSQL options`: enable `TimescaleDB`. - Leave the default setting for all other fields. - Get the values for `Host URL` and `Password` from the connection string generated when you created your $SERVICE_LONG. For example, in the following connection string: - - ```bash - postgres://tsdbadmin:krifchuf3r8c5onn@s5pq0es2cy.vfbtkqzhtm.tsdb.cloud.timescale.com:39941/tsdb?sslmode=require - ``` - - `krifchuf3r8c5onn` is the password and `s5pq0es2cy.vfbtkqzhtm.tsdb.cloud.timescale.com:39941` is the host URL in the required format. - 1. **Click `Save & test`** Grafana checks that your details are set correctly. @@ -44,4 +36,5 @@ To connect the data in your $SERVICE_LONG to Grafana: [grafana-self-managed]: https://grafana.com/get/?tab=self-managed [grafana-cloud]: https://grafana.com/get/ [cloud-login]: https://console.cloud.timescale.com/ -[create-service]: /getting-started/:currentVersion:/services/ \ No newline at end of file +[create-service]: /getting-started/:currentVersion:/services/ +[connection-info]: /use-timescale/:currentVersion:/integrations/query-admin/find-connection-details/ \ No newline at end of file diff --git a/_partials/_integration-prereqs.md b/_partials/_integration-prereqs.md new file mode 100644 index 0000000000..069f0044f4 --- /dev/null +++ b/_partials/_integration-prereqs.md @@ -0,0 +1,9 @@ +Before integrating: + +* Create a [target $SERVICE_LONG][create-service]. You need [your connection details][connection-info] to follow this procedure. + + This procedure also works for [self-hosted $TIMESCALE_DB][enable-timescaledb]. + +[create-service]: /getting-started/:currentVersion:/services/ +[enable-timescaledb]: /self-hosted/:currentVersion:/install/ +[connection-info]: /use-timescale/:currentVersion:/integrations/query-admin/find-connection-details/ \ No newline at end of file diff --git a/mst/installation-mst.md b/mst/installation-mst.md index 7db99ce030..77fa20a4d8 100644 --- a/mst/installation-mst.md +++ b/mst/installation-mst.md @@ -122,7 +122,7 @@ You can always [contact us][contact] if you need help working something out, or if you want to have a chat. [contact]: https://www.timescale.com/contact -[install-psql]: /use-timescale/:currentVersion:/integrations/query-admin/about-psql/ +[install-psql]: /use-timescale/:currentVersion:/integrations/query-admin/psql/ [mst-docs]: /mst/:currentVersion:/ [tutorials]: /tutorials/:currentVersion:/ [mst-signup]: https://www.timescale.com/mst-signup diff --git a/mst/migrate-to-mst.md b/mst/migrate-to-mst.md index 79c80d6339..e8dcc38ed2 100644 --- a/mst/migrate-to-mst.md +++ b/mst/migrate-to-mst.md @@ -129,7 +129,7 @@ them. The migration still occurs successfully. [install-mst]: /mst/:currentVersion:/installation-mst/#create-your-first-service [pg_dump]: https://www.postgresql.org/docs/current/app-pgdump.html [pg_restore]: https://www.postgresql.org/docs/current/app-pgrestore.html -[psql]: /use-timescale/:currentVersion:/integrations/query-admin/about-psql/ +[psql]: /use-timescale/:currentVersion:/integrations/query-admin/psql/ [upgrading-postgresql]: https://kb-managed.timescale.com/en/articles/5368016-perform-a-postgresql-major-version-upgrade [upgrading-postgresql-self-hosted]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/ [upgrading-timescaledb]: /self-hosted/:currentVersion:/upgrades/major-upgrade/ \ No newline at end of file diff --git a/quick-start/ruby.md b/quick-start/ruby.md index aa8efc96f8..842a0f4b3d 100644 --- a/quick-start/ruby.md +++ b/quick-start/ruby.md @@ -720,7 +720,7 @@ page by page, or all pages together, and group by path or not: [add-performance]: #add-performance-and-path-attributes-to-pageload [explore]: #explore-aggregation-functions [install]: /getting-started/latest/ -[psql-install]: /use-timescale/:currentVersion:/integrations/query-admin/about-psql/ +[psql-install]: /use-timescale/:currentVersion:/integrations/query-admin/psql/ [rails-guide]: https://guides.rubyonrails.org/getting_started.html [ab]: https://httpd.apache.org/docs/2.4/programs/ab.html [active-record-query]: https://guides.rubyonrails.org/active_record_querying.html diff --git a/self-hosted/install/installation-macos.md b/self-hosted/install/installation-macos.md index 9c13ef1ee8..46df6334c7 100644 --- a/self-hosted/install/installation-macos.md +++ b/self-hosted/install/installation-macos.md @@ -80,7 +80,7 @@ And that is it! You have TimescaleDB running on a database on a self-hosted inst For the latest functionality, install MacOS 14 Sanoma. The oldest supported version is macOS 10.15 Catalina [homebrew]: https://docs.brew.sh/Installation -[install-psql]: /use-timescale/:currentVersion:/integrations/query-admin/about-psql/ +[install-psql]: /use-timescale/:currentVersion:/integrations/query-admin/psql/ [macports]: https://guide.macports.org/#installing.macports [install-from-source]: /self-hosted/:currentVersion:/install/installation-source/ [install-postgresql]: https://www.postgresql.org/download/macosx/ \ No newline at end of file diff --git a/self-hosted/install/installation-source.md b/self-hosted/install/installation-source.md index 374efd6bda..6d98665790 100644 --- a/self-hosted/install/installation-source.md +++ b/self-hosted/install/installation-source.md @@ -73,7 +73,7 @@ And that is it! You have TimescaleDB running on a database on a self-hosted inst -[install-psql]: /use-timescale/:currentVersion:/integrations/query-admin/about-psql/ +[install-psql]: /use-timescale/:currentVersion:/integrations/query-admin/psql/ [config]: /self-hosted/:currentVersion:/configuration/ [postgres-download]: https://www.postgresql.org/download/ [cmake-download]: https://cmake.org/download/ diff --git a/self-hosted/migration/entire-database.md b/self-hosted/migration/entire-database.md index b368da421b..66a135f041 100644 --- a/self-hosted/migration/entire-database.md +++ b/self-hosted/migration/entire-database.md @@ -118,7 +118,7 @@ information about compression and decompression, see [Compression][compression]. [migrate-separately]: /self-hosted/:currentVersion:/migration/schema-then-data/ [pg_dump]: https://www.postgresql.org/docs/current/app-pgdump.html [pg_restore]: https://www.postgresql.org/docs/current/app-pgrestore.html -[psql]: /use-timescale/:currentVersion:/integrations/query-admin/about-psql/ +[psql]: /use-timescale/:currentVersion:/integrations/query-admin/psql/ [timescaledb_pre_restore]: /api/:currentVersion:/administration/#timescaledb_pre_restore [timescaledb_post_restore]: /api/:currentVersion:/administration/#timescaledb_post_restore [upgrading-postgresql-self-hosted]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/ diff --git a/self-hosted/migration/schema-then-data.md b/self-hosted/migration/schema-then-data.md index 056b29c168..0091cec014 100644 --- a/self-hosted/migration/schema-then-data.md +++ b/self-hosted/migration/schema-then-data.md @@ -210,7 +210,7 @@ the [compression section](https://docs.timescale.com/use-timescale/latest/compre [install-selfhosted]: /self-hosted/:currentVersion:/install/ [pg_dump]: https://www.postgresql.org/docs/current/app-pgdump.html [pg_restore]: https://www.postgresql.org/docs/current/app-pgrestore.html -[psql]: /use-timescale/:currentVersion:/integrations/query-admin/about-psql/ +[psql]: /use-timescale/:currentVersion:/integrations/query-admin/psql/ [timescaledb-parallel-copy]: https://github.com/timescale/timescaledb-parallel-copy [upgrading-postgresql]: https://kb-managed.timescale.com/en/articles/5368016-perform-a-postgresql-major-version-upgrade [upgrading-postgresql-self-hosted]: /self-hosted/:currentVersion:/upgrades/upgrade-pg/ diff --git a/tutorials/OLD-financial-candlestick-tick-data/index.md b/tutorials/OLD-financial-candlestick-tick-data/index.md index 4b339e733c..4d0dea5a07 100644 --- a/tutorials/OLD-financial-candlestick-tick-data/index.md +++ b/tutorials/OLD-financial-candlestick-tick-data/index.md @@ -73,4 +73,4 @@ Follow this tutorial and see how to set up your TimescaleDB database to consume [create]: /tutorials/:currentVersion:/financial-candlestick-tick-data/create-candlestick-aggregates [query]: /tutorials/:currentVersion:/financial-candlestick-tick-data/query-candlestick-views [manage]: /tutorials/:currentVersion:/financial-candlestick-tick-data/advanced-data-management -[psql]: /use-timescale/:currentVersion:/integrations/query-admin/about-psql/ +[psql]: /use-timescale/:currentVersion:/integrations/query-admin/psql/ diff --git a/use-timescale/integrations/observability-alerting/grafana.md b/use-timescale/integrations/observability-alerting/grafana.md index 933d528fe0..4d41851c54 100644 --- a/use-timescale/integrations/observability-alerting/grafana.md +++ b/use-timescale/integrations/observability-alerting/grafana.md @@ -7,11 +7,11 @@ keywords: [Grafana, visualizations, analytics, monitoring] import GrafanaConnect from "versionContent/_partials/_grafana-connect.mdx"; -# Integrate Grafana and Timescale Cloud +# Grafana -You can use [Grafana](https://grafana.com/docs/) to monitor, visualize and perform analytics on data stored in your $SERVICE_LONG. +[Grafana](https://grafana.com/docs/) enables you to query, visualize, alert on, and explore your metrics, logs, and traces wherever they’re stored. -This page shows you how to connect Grafana with a $SERVICE_LONG, create a dashboard and panel, then visualize geospatial data. +This page shows you how to integrate Grafana with a $SERVICE_LONG, create a dashboard and panel, then visualize geospatial data. @@ -30,7 +30,7 @@ that system. 1. **Select the data source** - Select your $SERVICE_LONG from the list of pre-configured data sources or configure a new one. + Select your $SERVICE_SHORT from the list of pre-configured data sources or configure a new one. 1. **Configure your panel** @@ -124,11 +124,11 @@ tutorial as a starting point. 1. In your Grafana dashboard, click `Add` > `Visualization`. - 1. Select `Geomap` in the visualization type drop-down. + 1. Select `Geomap` in the visualization type drop-down at the top right. 1. **Configure the data format** - 1. In the `Queries` tab, select your data source. + 1. In the `Queries` tab below, select your data source. 1. In the `Format` drop-down, select `Table`. @@ -155,7 +155,7 @@ tutorial as a starting point. With default settings, the visualization uses green circles of the fixed size. Configure at least the following for a more representative view: - -`Map layers` > `Styles` > `Size` > `value`. + - `Map layers` > `Styles` > `Size` > `value`. This changes the size of the circle depending on the value, with bigger circles representing bigger values. diff --git a/use-timescale/integrations/query-admin/about-connecting.md b/use-timescale/integrations/query-admin/about-connecting.md deleted file mode 100644 index 12ba4d6c0c..0000000000 --- a/use-timescale/integrations/query-admin/about-connecting.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Connecting to Timescale -excerpt: How to connect to a Timescale instance -products: [cloud, mst, self_hosted] -keywords: [connect, Managed Service for TimescaleDB, Timescale] ---- - - -# Connecting to Timescale - -Regardless of the tool you use to connect to your database, you need to make -sure you have these details: - -* Hostname -* Port -* Username -* Password -* Database name - -For more information about using these details to connect with `psql`, see the -[About psql][about-psql] section. - -## Find connection details - - - - - - - -### Finding connection details in Timescale - -1. Sign in to the [Timescale portal][tsc-portal]. -1. In the `Services` tab, find the service you want to connect to, and check - it is marked as `Running`. -1. Click the name of the service to see its connection information. Copy the - `Service URL`. -1. If you don't know the password for the service, navigate to the `Operations` - tab, and click `Reset password`. You can choose your own password or allow - Timescale to generate a secure password for you. Keep a copy of your - new password. - - - - - - - - - - - -### Finding connection details in Managed Service for TimescaleDB - -1. Sign in to your Managed Service for TimescaleDB portal. -1. In the `Services` tab, find the service you want to connect to, and check - it is marked as `Running`. -1. Click the name of the service to see its connection information. Copy the - `host`, `port`, and `password`. You need these to connect. - - - - - - - - - -If you have installed your database on your local system, you can use the -`localhost` hostname to log in as the PostgreSQL root user `postgres`. When you -have connected using these details, make sure that you set up an additional user -for accessing your database, and add additional authentication requirements. - - - - - -[about-psql]: /use-timescale/:currentVersion:/integrations/query-admin/about-psql/ -[tsc-portal]: https://console.cloud.timescale.com/ diff --git a/use-timescale/integrations/query-admin/about-psql.md b/use-timescale/integrations/query-admin/about-psql.md deleted file mode 100644 index a6dbe65897..0000000000 --- a/use-timescale/integrations/query-admin/about-psql.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: About psql -excerpt: Connect to your database with the psql command line tool -products: [cloud, mst, self_hosted] -keywords: [connect, psql] ---- - -# About psql - -The `psql` command line tool is widely used for interacting with a PostgreSQL or -Timescale instance, and it is available for all operating systems. Most of -the instructions in the Timescale documentation assume you are using `psql`. - -To use `psql` to connect to your database, you need the connection details for -your PostgreSQL server. For more information about how to retrieve your -connection details, see the [about connecting][about-connecting] section. - -## Connecting to your database with psql - -There are two different ways you can use `psql` to connect to your database. - -You can provide the details using parameter flags, like this: - -```bash -psql -h -p -U -W -d -``` - -Alternatively, you can use a service URL to provide the details, like this: - -```bash -psql postgres://@:/?sslmode=require -``` - -If you configured your Timescale service to connect using -[SSL mode][ssl-mode], use: - -```bash -psql "postgres://tsdbadmin@/tsdb?sslmode=verify-full" -``` - -When you run one of these commands, you are prompted for your password. If you -don't want to prompted, you can supply your password directly within the service -URL instead, like this: - -```bash -psql "postgres://:@:/?sslmode=require" -``` - -## Common psql commands - -When you start using `psql`, these are the commands you are likely to use most -frequently: - -|Command|Description| -|-|-| -|`\c `|Connect to a new database| -|`\d `|Show the details of a table| -|`\df`|List functions in the current database| -|`\df+`|List all functions with more details| -|`\di`|List all indexes from all tables| -|`\dn`|List all schemas in the current database| -|`\dt`|List available tables| -|`\du`|List PostgreSQL database roles| -|`\dv`|List views in current schema| -|`\dv+`|List all views with more details| -|`\dx`|Show all installed extensions| -|`ef `|Edit a function| -|`\h`|Show help on syntax of SQL commands| -|`\l`|List available databases| -|`\password `|Change the password for the user| -|`\q`|Quit `psql`| -|`\set`|Show system variables list| -|`\timing`|Show how long a query took to execute| -|`\x`|Show expanded query results| -|`\?`|List all `psql` slash commands| - -* For a more comprehensive list of `psql` commands, see the - [Timescale psql cheat sheet][psql-cheat-sheet]. -* For more information about all `psql` commands, see the - [psql documentation][psql-docs]. - -### Save query results to a file - -When you run queries in `psql`, the results are shown in the console by default. -If you are running queries that have a lot of results, you might like to save -the results into a comma-separated `.csv` file instead. You can do this using -the `COPY` command. For example: - -```sql -\copy (SELECT * FROM ...) TO '/tmp/output.csv' (format CSV); -``` - -This command sends the results of the query to a new file called `output.csv` in -the `/tmp/` directory. You can open the file using any spreadsheet program. - -### Edit queries in a text editor - -Sometimes, queries can get very long, and you might make a mistake when you try -typing it the first time around. If you have made a mistake in a long query, -instead of retyping it, you can use a built-in text editor, which is based on -`Vim`. Launch the query editor with the `\e` command. Your previous query is -loaded into the editor. When you have made your changes, press `Esc`, then type -`:`＋`w`＋`q` to save the changes, and return to the command prompt. Access the -edited query by pressing `↑`, and press `Enter` to run it. - -[about-connecting]: /use-timescale/:currentVersion:/integrations/query-admin/about-connecting/ -[psql-cheat-sheet]: https://www.timescale.com/learn/postgres-cheat-sheet -[psql-docs]: https://www.postgresql.org/docs/13/app-psql.html -[ssl-mode]: /use-timescale/:currentVersion:/security/strict-ssl/ diff --git a/use-timescale/integrations/query-admin/find-connection-details.md b/use-timescale/integrations/query-admin/find-connection-details.md new file mode 100644 index 0000000000..3fbfac432b --- /dev/null +++ b/use-timescale/integrations/query-admin/find-connection-details.md @@ -0,0 +1,57 @@ +--- +title: Find your connection details +excerpt: How to connect to a Timescale instance +products: [cloud, mst, self_hosted] +keywords: [connect, Managed Service for TimescaleDB, Timescale] +--- + +# Find your connection details + +To connect to your $SERVICE_SHORT or self-hosted database, you need at least the following: + +- Hostname +- Port +- Username +- Password +- Database name + +Find the connection details based on your installation type. + + + + + +Retrieve the connection details for your $SERVICE_LONG: + +- **In `-credentials.txt`**: + + All connection details are supplied in the configuration file you download when you create a new $SERVICE_SHORT. + +- **In $CONSOLE**: + + Open the [`Services`][console-services] page and select your $SERVICE_SHORT. The connection details, except the password, are available in the `Connect to your service` widget. If necessary, click `Forgot your password?` to get a new one. + + ![Timescale service connection details](https://assets.timescale.com/docs/images/timescale-service-connection-details.png) + + + + + +Find the connection details in the [PostgreSQL configuration file][postgres-config] or by asking your database administrator. + + + + + +In the `Services` page of the $MST_CONSOLE_LONG, click the service you want to connect to. You see the connection details: + +![MST connection details](https://assets.timescale.com/docs/images/mst-connection-info.png) + + + + + +[about-psql]: /use-timescale/:currentVersion:/integrations/query-admin/psql/ +[tsc-portal]: https://console.cloud.timescale.com/ +[console-services]: https://console.cloud.timescale.com/dashboard/services +[postgres-config]: https://www.postgresql.org/docs/current/runtime-config-file-locations.html diff --git a/use-timescale/integrations/query-admin/psql.md b/use-timescale/integrations/query-admin/psql.md index 1ca4a0190d..9a5680aab7 100644 --- a/use-timescale/integrations/query-admin/psql.md +++ b/use-timescale/integrations/query-admin/psql.md @@ -1,224 +1,261 @@ --- -title: Install the psql connection tool -excerpt: How to install the psql client for PostgreSQL +title: Connect to a Timescale Cloud service with psql +excerpt: Install the psql client for PostgreSQL and connect to your service products: [cloud, mst, self_hosted] keywords: [connect, psql] --- -# Install the psql connection tool +import IntegrationPrereqs from "versionContent/_partials/_integration-prereqs.mdx"; -The `psql` command line tool is widely used for interacting with a PostgreSQL or -Timescale instance, and it is available for all operating systems. Most of -the instructions in the Timescale documentation assume you are using `psql`. +# Connect with 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: +`psql` is a terminal-based front-end to PostgreSQL that enables you to type in queries interactively, issue them to Postgres, and see the query results. - +This page shows you how to use the `psql` command line tool to interact with your $SERVICE_LONG. + +## Prerequisites + + - +## Check for an existing installation + +On many operating systems, `psql` is installed by default. To use the functionality described in this page, best practice is to use the latest version of `psql`. To check the version running on your system: + + + + + ```bash psql --version ``` - + + + - - + ```powershell wmic /output:C:\list.txt product get name, version ``` - + -## Install PostgreSQL package on macOS +If you already have the latest version of `psql` installed, proceed to the [Connect to your $SERVICE_SHORT][connect-database] section. -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. +## Install psql - +If there is no existing installation, take the following steps to install `psql`: + + + + - +Install using Homebrew. `libpqxx` is the official C++ client API for PostgreSQL. -### Installing PostgreSQL package using Homebrew - -1. Install Homebrew, if you don't already have it: +1. Install Homebrew, if you don't already have it: ```bash /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][homebrew]. -1. Make sure your Homebrew repository is up to date: + For more information about Homebrew, including installation instructions, see the [Homebrew documentation][homebrew]. + +1. Make sure your Homebrew repository is up to date: ```bash brew doctor brew update ``` -1. Install PostgreSQL: +1. Install `psql`: ```bash - brew install postgresql + brew install libpq ``` - - - - - - - - -### 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][macports]. -1. Install the latest version of Postgresql: +1. Update your path to include the `psql` tool: ```bash - sudo port install postgresql + brew link --force libpq ``` - For example, to install version *14* replace `postgresql` with `postgresql14`. -1. View the files that were installed: - - ```bash - port contents postgresql - ``` +On Intel chips, the symbolic link is added to `/usr/local/bin`. On Apple Silicon, the symbolic link is added to `/opt/homebrew/bin`. - - -## Install 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. - - + - +Install using MacPorts. `libpqxx` is the official C++ client API for PostgreSQL. -### Installing psql using Homebrew +1. [Install MacPorts][macports] by downloading and running the package installer. -1. Install Homebrew, if you don't already have it: +1. Install the latest version of `libpqxx`: ```bash - /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][homebrew]. -1. Make sure your Homebrew repository is up to date: - - ```bash - brew doctor - brew update - ``` - -1. Install `psql`: - - ```bash - brew install libpq - ``` - -1. Update your path to include the `psql` tool. - - ```bash - brew link --force libpq + sudo port install libpqxx ``` + +1. View the files that were installed by `libpqxx`: - On Intel chips, the symbolic link is added to `/usr/local/bin`. On Apple - Silicon, the symbolic link is added to `/opt/homebrew/bin`. - + ```bash + port contents libpqxx + ``` + + + - +Install `psql` on Debian and Ubuntu with the `apt` package manager. -### 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][macports]. -1. Install the latest version of libpqxx: +1. Make sure your `apt` repository is up to date: ```bash - sudo port install libpqxx + sudo apt-get update ``` -1. View the files that were installed by libpqxx: +1. Install the `postgresql-client` package: ```bash - port contents libpqxx + sudo apt-get install postgresql-client ``` - - -## Install psql on Debian and Ubuntu + -You can use the `apt` package manager on Debian and Ubuntu systems to install -the `psql` tool. +`psql` is installed by default when you install PostgreSQL. This procedure uses the interactive installer provided by PostgreSQL and EnterpriseDB. -### Installing psql using the apt package manager +1. Download and run the PostgreSQL installer from [www.enterprisedb.com][windows-installer]. + +1. In the `Select Components` dialog, check `Command Line Tools`, along with any other components you want to install, and click `Next`. -1. Make sure your `apt` repository is up to date: +1. Complete the installation wizard to install the package. - ```bash - sudo apt-get update - ``` + -1. Install the `postgresql-client` package: + - ```bash - sudo apt-get install postgresql-client - ``` + - +## Connect to your $SERVICE_SHORT + +To use `psql` to connect to your $SERVICE_SHORT, you need the connection details. See [Find your connection details][connection-info]. + +Connect to your $SERVICE_SHORT with either: + +- The parameter flags: + + ```bash + psql -h -p -U -W -d + ``` + +- The $SERVICE_SHORT URL: + + ```bash + psql "postgres://@:/?sslmode=require" + ``` + + You are prompted to provide the password. + +- The $SERVICE_SHORT URL with the password already included and [a stricter SSL mode][ssl-mode] enabled: + + ```bash + psql "postgres://:@:/?sslmode=verify-full" + ``` + +## Useful psql commands + +When you start using `psql`, these are the commands you are likely to use most frequently: + +|Command|Description| +|-|-| +|`\c `|Connect to a new database| +|`\d `|Show the details of a table| +|`\df`|List functions in the current database| +|`\df+`|List all functions with more details| +|`\di`|List all indexes from all tables| +|`\dn`|List all schemas in the current database| +|`\dt`|List available tables| +|`\du`|List PostgreSQL database roles| +|`\dv`|List views in current schema| +|`\dv+`|List all views with more details| +|`\dx`|Show all installed extensions| +|`ef `|Edit a function| +|`\h`|Show help on syntax of SQL commands| +|`\l`|List available databases| +|`\password `|Change the password for the user| +|`\q`|Quit `psql`| +|`\set`|Show system variables list| +|`\timing`|Show how long a query took to execute| +|`\x`|Show expanded query results| +|`\?`|List all `psql` slash commands| + +For more on `psql` commands, see the [Timescale psql cheat sheet][psql-cheat-sheet] and [psql documentation][psql-docs]. + +## Save query results to a file + +When you run queries in `psql`, the results are shown in the console by default. +If you are running queries that have a lot of results, you might like to save +the results into a comma-separated `.csv` file instead. You can do this using +the `COPY` command. For example: + +```sql +\copy (SELECT * FROM ...) TO '/tmp/output.csv' (format CSV); +``` -## Install psql on Windows +This command sends the results of the query to a new file called `output.csv` in +the `/tmp/` directory. You can open the file using any spreadsheet program. -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. +## Run long queries - +To run multi-line queries in `psql`, use the `EOF` delimiter. For example: -### Installing psql on Windows +```sql +psql -d $TARGET -f -v hypertable= - <<'EOF' +SELECT public.alter_job(j.id, scheduled=>true) +FROM _timescaledb_config.bgw_job j +JOIN _timescaledb_catalog.hypertable h ON h.id = j.hypertable_id +WHERE j.proc_schema IN ('_timescaledb_internal', '_timescaledb_functions') +AND j.proc_name = 'policy_compression' +AND j.id >= 1000 +AND format('%I.%I', h.schema_name, h.table_name)::text::regclass = :'hypertable'::text::regclass; +EOF +``` -1. Download and run the PostgreSQL installer from - [www.enterprisedb.com][windows-installer]. -1. In the `Select Components` dialog, check `Command Line Tools`, along with - any other components you want to install, and click `Next`. -1. Complete the installation wizard to install the package. +## Edit queries in a text editor - +Sometimes, queries can get very long, and you might make a mistake when you try +typing it the first time around. If you have made a mistake in a long query, +instead of retyping it, you can use a built-in text editor, which is based on +`Vim`. Launch the query editor with the `\e` command. Your previous query is +loaded into the editor. When you have made your changes, press `Esc`, then type +`:`＋`w`＋`q` to save the changes, and return to the command prompt. Access the +edited query by pressing `↑`, and press `Enter` to run it. +[psql-cheat-sheet]: https://www.timescale.com/learn/postgres-cheat-sheet +[psql-docs]: https://www.postgresql.org/docs/13/app-psql.html +[ssl-mode]: /use-timescale/:currentVersion:/security/strict-ssl/ [homebrew]: https://docs.brew.sh/Installation [macports]: https://guide.macports.org/#installing.macports [windows-installer]: https://www.postgresql.org/download/windows/ +[connect-database]:/use-timescale/:currentVersion:/integrations/query-admin/psql/#connect-to-your-service +[connection-info]: /use-timescale/:currentVersion:/integrations/query-admin/find-connection-details/ + diff --git a/use-timescale/metrics-logging/service-metrics.md b/use-timescale/metrics-logging/service-metrics.md index 0be8320552..72be7c5ce2 100644 --- a/use-timescale/metrics-logging/service-metrics.md +++ b/use-timescale/metrics-logging/service-metrics.md @@ -136,4 +136,4 @@ performance bottlenecks with `pg_stat_statements`][blog-pg_stat_statements]. [metrics-dashboard]: /use-timescale/:currentVersion:/metrics-logging/service-metrics/ [pg-stat]: /use-timescale/:currentVersion:/metrics-logging/service-metrics/#query-level-statistics-with-pg_stat_statements [blog-pg_stat_statements]: -[psql]: /use-timescale/:currentVersion:/integrations/query-admin/about-psql/ +[psql]: /use-timescale/:currentVersion:/integrations/query-admin/psql/ diff --git a/use-timescale/page-index/page-index.js b/use-timescale/page-index/page-index.js index 8eb412c40c..b95a8b4e0f 100644 --- a/use-timescale/page-index/page-index.js +++ b/use-timescale/page-index/page-index.js @@ -780,17 +780,12 @@ module.exports = [ children: [ { - title: "About connecting to Timescale", - href: "about-connecting", + title: "Find your connection details", + href: "find-connection-details", excerpt: "Learn about using connecting to your Timescale database", }, { - title: "About psql", - href: "about-psql", - excerpt: "Learn about using psql to connect to Timescale", - }, - { - title: "Install psql", + title: "Connect with psql", href: "psql", excerpt: "Install psql to connect to Timescale", },