Update psql section (github#612)

* Index and About pages

* Install psql

* Add about psql page

* Other tools

* Index

* index

* Add link to psql cheat sheet + tyops

timescaledb/how-to-guides/connecting/about-connecting.md

@@ -0,0 +1,61 @@
+# Connecting to TimescaleDB
+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 in Timescale Cloud
+To retrieve your connection details from a running Timescale Cloud service:
+
+<procedure>
+
+### Finding connection details in Timescale Cloud
+1.  Sign in to the [Timescale Cloud 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 you want to connect to, to see the connection
+    information. Take a note of the `Service URL`. The URL contains all the
+    information you need to connect to your service, except for the password.
+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 Cloud to generate a secure password for you. Take a note of your
+    new password.
+
+<img class="main-content__illustration" src="https://s3.amazonaws.com/assets.timescale.com/docs/images/tsc-connection-info.png" alt="View Timescale Cloud connection info"/>
+
+</procedure>
+
+## Find connection details in Managed Service for TimescaleDB
+To retrieve your connection details from a running Managed Service for Timescale
+service:
+
+<procedure>
+
+### Finding connection details in Managed Service for TimescaleDB
+1.  Sign in to the [Managed Service for TimescaleDB portal][mst-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 you want to connect to, to see the connection
+    information. Take a note of the `host`, `port`, and `password`.
+
+<img class="main-content__illustration" src="https://s3.amazonaws.com/assets.timescale.com/docs/images/mst-connection-info.png" alt="View Managed Service for TimescaleDB connection info"/>
+
+</procedure>
+
+## Find connection details in self-hosted TimescaleDB
+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, we strongly recommend that you set up an
+additional user for accessing your database, and add additional authentication
+requirements.
+
+
+[about-psql]: /how-to-guides/connecting/about-psql/
+[tsc-portal]: https://console.cloud.timescale.com/
+[mst-portal]: https://portal.managed.timescale.com

timescaledb/how-to-guides/connecting/about-psql.md

@@ -0,0 +1,86 @@
+# About psql
+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 we give you 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 <HOSTNAME> -p <PORT> -U <USERNAME> -W -d <DATABASENAME>
+```
+
+Alternatively, you can use a service URL to provide the details, like this:
+```bash
+psql postgres://<USERNAME>@<HOSTNAME>:<PORT>/<DATABASENAME>?sslmode=require
+```
+
+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://<USERNAME>:<PASSWORD>@<HOSTNAME>:<PORT>/<DATABASENAME>?sslmode=require
+```
+
+## Common psql commands
+When you start using `psql`, these are the commands you are likely to use most
+frequently:
+
+|Command|Description|
+|-|-|
+|`\c <DB_NAME>`|Connect to a new database|
+|`\d <TABLE_NAME>`|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 <FUNCTION_NAME>`|Edit a function|
+|`\h`|Show help on syntax of SQL commands|
+|`\l`|List available databases|
+|`\password <USERNAME>`|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 be default.
+If you are running queries that have a lot fo 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]: /how-to-guides/connecting/about-connecting/
+[psql-cheat-sheet]: https://postgrescheatsheet.com/
+[psql-docs]: https://www.postgresql.org/docs/13/app-psql.html

timescaledb/how-to-guides/connecting/azure-data-studio.md

@@ -1 +1,9 @@
-# Azure Data Studio
+# Azure Data Studio
+Microsoft Azure Data Studio is a cross-platform database tool that is available
+for Microsoft Windows, Apple macOS, or various Linux flavors. You can try Azure
+Data Studio for free.
+
+For more information about Azure Data Studio, including download and
+installation instructions, see [azure.microsoft.com][ms-azure-data-studio].
+
+[ms-azure-data-studio]: https://azure.microsoft.com/en-us/services/developer-tools/data-studio/

timescaledb/how-to-guides/connecting/dbeaver.md

@@ -1 +1,9 @@
-# DBeaver
+# DBeaver
+DBeaver is a free database tool that is available for Microsoft Windows, Apple
+macOS, or various Linux flavors. You can also use it as a plugin to the Eclipse
+IDE platform.
+
+For more information about DBeaver, including download and installation
+instructions, see [dbeaver.io][dbeaver].
+
+[dbeaver]: https://dbeaver.io/

timescaledb/how-to-guides/connecting/index.md

@@ -1,28 +1,26 @@
 # Connecting to TimescaleDB
-
-TimescaleDB can work with any tool that connects to PostgreSQL. In this section,
-we provide some basic instructions on connecting with popular tools for running
-queries against PostgreSQL.
-
-In most cases, if you don't find instructions for a tool below or the instructions
-we provide don't seem to work in your scenario, the tooling website
-has up-to-date instructions for connecting.
-
-Generally, you'll need to know the following information to connect any tool
-to your TimescaleDB instance:
-
- * Hostname
- * Port
- * Username
- * Password
- * Database name
-
-With that information ready to go, you can connect using one of these tools.
-
-
-**[Connect with `psql`][connect-psql]**: `psql` is the standard command line interface for
-interacting with a PostgreSQL or TimescaleDB instance and used in most of our
-tutorials and documentation.
-
-
+When you have your TimescaleDB service up and running, either in the cloud or
+own your own self-hosted hardware, you need a way to talk to it from your local
+machine. Most of the instructions we give you assume you are using `psql`, but
+that's not the only connection tool available to you. In this section, we give
+you instructions for installing `psql`, as well as some other common tools.
+
+*   [Learn about connecting to your database][about-connecting] to understand
+    how it works before you begin.
+*   [Learn about using psql][about-psql].
+*   Install [psql][connect-psql].
+*   Install and use [Azure Data Studio][connect-azure].
+*   Install and use [DBeaver][connect-dbeaver].
+*   Install and use [pgAdmin][connect-pgadmin].
+
+<!----
+*   [Troubleshoot][connect-tshoot] connection issues.
+-->
+
+[about-connecting]: /how-to-guides/connecting/about-connecting/
+[about-psql]: /how-to-guides/connecting/about-psql/
 [connect-psql]: /how-to-guides/connecting/psql/
+[connect-azure]: /how-to-guides/connecting/azure-data-studio/
+[connect-dbeaver]: /how-to-guides/connecting/dbeaver/
+[connect-pgadmin]: /how-to-guides/connecting/pgadmin/
+[connect-tshoot]: /how-to-guides/connecting/troubleshooting/

timescaledb/how-to-guides/connecting/pgadmin.md

@@ -1 +1,10 @@
-# pgAdmin
+# pgAdmin
+The `pgAdmin` tool is a database administration tool that can be run on the
+desktop, or in your browser. It is available for Chrome, Firefox, Edge, and
+Safari browsers, or can be installed on Microsoft Windows, Apple macOS, or
+various Linux flavors.
+
+For more information about `pgAdmin`, including download and installation
+instructions, see [pgadmin.org][pgadmin].
+
+[pgadmin]: https://www.pgadmin.org/