diff --git a/_partials/_grafana-connect.md b/_partials/_grafana-connect.md index 268a33c127..afca26fb25 100644 --- a/_partials/_grafana-connect.md +++ b/_partials/_grafana-connect.md @@ -4,11 +4,11 @@ import IntegrationPrereqs from "versionContent/_partials/_integration-prereqs.md -* Install [self-managed Grafana][grafana-self-managed], or sign up for [Grafana Cloud][grafana-cloud]. +* Install [self-managed Grafana][grafana-self-managed] or sign up for [Grafana Cloud][grafana-cloud]. -## Add your $SERVICE_LONG as a data source +## Add your $SERVICE_SHORT or database as a data source -To connect the data in your $SERVICE_LONG to Grafana: +To connect the data in your $SERVICE_SHORT to Grafana: @@ -17,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. @@ -47,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 index 5d6945c09e..069f0044f4 100644 --- a/_partials/_integration-prereqs.md +++ b/_partials/_integration-prereqs.md @@ -1,5 +1,9 @@ -Before integrating with $CLOUD_LONG: +Before integrating: -* [Create a target $SERVICE_LONG][create-service]. +* Create a [target $SERVICE_LONG][create-service]. You need [your connection details][connection-info] to follow this procedure. -[create-service]: /getting-started/:currentVersion:/services/ \ No newline at end of file + 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/use-timescale/integrations/about-connecting.md b/use-timescale/integrations/about-connecting.md deleted file mode 100644 index 16cc6e75ea..0000000000 --- a/use-timescale/integrations/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/psql/ -[tsc-portal]: https://console.cloud.timescale.com/ diff --git a/use-timescale/integrations/find-connection-details.md b/use-timescale/integrations/find-connection-details.md new file mode 100644 index 0000000000..3fbfac432b --- /dev/null +++ b/use-timescale/integrations/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/grafana.md b/use-timescale/integrations/grafana.md index b5fd6459fe..4d41851c54 100644 --- a/use-timescale/integrations/grafana.md +++ b/use-timescale/integrations/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 -[Grafana](https://grafana.com/docs/) is an open-source analytics and monitoring solution. You can use it 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/psql.md b/use-timescale/integrations/query-admin/psql.md new file mode 100644 index 0000000000..9a5680aab7 --- /dev/null +++ b/use-timescale/integrations/query-admin/psql.md @@ -0,0 +1,261 @@ +--- +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] +--- + +import IntegrationPrereqs from "versionContent/_partials/_integration-prereqs.mdx"; + +# Connect with psql + +`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 +``` + + + + + +If you already have the latest version of `psql` installed, proceed to the [Connect to your $SERVICE_SHORT][connect-database] section. + +## 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. + + + +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: + + ```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 + ``` + +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 using MacPorts. `libpqxx` is the official C++ client API for PostgreSQL. + + + +1. [Install MacPorts][macports] by downloading and running the package installer. + +1. Install the latest version of `libpqxx`: + + ```bash + sudo port install libpqxx + ``` + +1. View the files that were installed by `libpqxx`: + + ```bash + port contents libpqxx + ``` + + + + + + + +Install `psql` on Debian and Ubuntu with the `apt` package manager. + + + +1. Make sure your `apt` repository is up to date: + + ```bash + sudo apt-get update + ``` + +1. Install the `postgresql-client` package: + + ```bash + sudo apt-get install postgresql-client + ``` + + + + + + + +`psql` is installed by default when you install PostgreSQL. This procedure uses the interactive installer provided by PostgreSQL and EnterpriseDB. + + + +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. + + + + + + + +## 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); +``` + +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. + +## Run long queries + +To run multi-line queries in `psql`, use the `EOF` delimiter. For example: + +```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 +``` + +## 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/page-index/page-index.js b/use-timescale/page-index/page-index.js index 8c5e0cd9c2..85e290571f 100644 --- a/use-timescale/page-index/page-index.js +++ b/use-timescale/page-index/page-index.js @@ -774,9 +774,9 @@ module.exports = [ excerpt: "Integrate third-party solutions with Timescale Cloud", children: [ { - title: "About connecting to Timescale", - href: "about-connecting", - excerpt: "Learn about using connecting to your Timescale database", + title: "Find your connection details", + href: "find-connection-details", + excerpt: "Learn about connecting to your Timescale database", }, { title: "Azure Data Studio",