> ## Documentation Index
> Fetch the complete documentation index at: https://www.propeldata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect & SDKs

> Connect using ClickHouse or PostgreSQL clients and SDKs.

<div />

## Connection details

<Tabs>
  <Tab title="ClickHouse">
    | Parameter | Value                                         |
    | --------- | --------------------------------------------- |
    | Host      | `https://clickhouse.us-east-2.propeldata.com` |
    | Port      | 8443                                          |
    | Database  | propel                                        |
    | user      | Your Propel Application ID                    |
    | password  | Your Propel Application secret                |
  </Tab>

  <Tab title="PostgreSQL">
    | Parameter | Value                                 |
    | --------- | ------------------------------------- |
    | Host      | `postgresql.us-east-2.propeldata.com` |
    | Port      | 5432                                  |
    | Database  | propel                                |
    | user      | Your Propel Application ID            |
    | password  | Your Propel Application secret        |
  </Tab>
</Tabs>

***

To connect a client, you must [create a Propel Application](/docs/applications) and give it the `DATAPOOL_QUERY` scope.

## ClickHouse clients and SDKs

<CardGroup cols={2}>
  <Card title="ClickHouse HTTPS interface" icon="bolt-lightning" href="#clickhouse-https-interface">
    The official HTTPS interface.
  </Card>

  <Card title="Python" icon="python" href="#python">
    The official Python client.
  </Card>

  <Card title="JavaScript" icon="js" href="#javascript">
    The official JavaScript client.
  </Card>

  <Card title="Go" icon="golang" href="#go">
    The official Golang client.
  </Card>

  <Card title="Java" icon="java" href="#java">
    The official Java client.
  </Card>

  <Card title="Rust" icon="rust" href="#rust">
    The official Rust client.
  </Card>
</CardGroup>

### ClickHouse HTTPS interface

The ClickHouse HTTPS interface provides a simple way to query Propel's Serverless ClickHouse using HTTP requests. Since it uses standard HTTP, you can use it with:

* Any programming language with HTTP support
* Command line tools like cURL
* API testing tools like Postman

To connect, send POST requests to this endpoint:

```bash theme={"system"}
echo 'SELECT 1' | \
curl https://clickhouse.us-east-2.propeldata.com:8443 \
  --user "$APPLICATION_ID:$APPLICATION_SECRET" \
  --data-binary @-
```

### Python

To get started with the ClickHouse Python client:

<Steps>
  <Step title="Install the package">
    ```bash theme={"system"}
    pip install clickhouse-driver
    ```
  </Step>

  <Step title="Import and create a client">
    ```python theme={"system"}
    from clickhouse_driver import Client

    client = Client(
        host='clickhouse.us-east-2.propeldata.com',
        port=8443,
        secure=True,
        user=os.environ['APPLICATION_ID'],
        password=os.environ['APPLICATION_SECRET'],
        database='default'
    )
    ```
  </Step>

  <Step title="Execute queries">
    ```python theme={"system"}
    result = client.execute('SELECT 1')
    for row in result:
        print(row)
    ```
  </Step>
</Steps>

Make sure to set the `APPLICATION_ID` and `APPLICATION_SECRET` environment variables before running the application.

For more detailed documentation, refer to the [ClickHouse Python client documentation](https://clickhouse-driver.readthedocs.io/).

### JavaScript

The official JS client. It's written in TypeScript and provides type definitions and has zero dependencies. Two versions are available:

* `@clickhouse/client` for Node.js
* `@clickhouse/client-web` for browsers and Cloudflare workers

To get started with the ClickHouse JS client:

<Steps>
  <Step title="Install the package">
    <Tabs>
      <Tab title="JavaScript">
        <CodeGroup>
          ```bash npm theme={"system"}
           npm install @clickhouse/client
          ```

          ```bash yarn theme={"system"}
          yarn add @clickhouse/client
          ```

          ```bash pnpm theme={"system"}
          pnpm add @clickhouse/client
          ```
        </CodeGroup>
      </Tab>

      <Tab title="JavaScript (web)">
        <CodeGroup>
          ```bash npm theme={"system"}
          npm install @clickhouse/client-web
          ```

          ```bash yarn theme={"system"}
          yarn add @clickhouse/client-web
          ```

          ```bash pnpm theme={"system"}
            pnpm add @clickhouse/client-web
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Import and create a client">
    <Tabs>
      <Tab title="JavaScript">
        ```javascript theme={"system"}
        import { createClient } from '@clickhouse/client'

        const client = createClient({
          host: 'https://clickhouse.us-east-2.propeldata.com',
          username: process.env.APPLICATION_ID,
          password: process.env.APPLICATION_SECRET
        })
        ```

        If your environment doesn't support ESM modules, you can use CommonJS syntax:

        ```javascript theme={"system"}
        const { createClient } = require('@clickhouse/client')

        const client = createClient({
          host: 'https://clickhouse.us-east-2.propeldata.com',
          username: process.env.APPLICATION_ID,
          password: process.env.APPLICATION_SECRET
        })
        ```
      </Tab>

      <Tab title="JavaScript (web)">
        ```javascript theme={"system"}
        import { createClient } from '@clickhouse/client-web'

        const client = createClient({
          host: 'https://clickhouse.us-east-2.propeldata.com',
          username: process.env.APPLICATION_ID,
          password: process.env.APPLICATION_SECRET
        })
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Execute queries">
    ```javascript theme={"system"}
    const result = await client.query({
      query: 'SELECT 1'
    })

    console.log(result.rows)
    ```
  </Step>
</Steps>

<Note>
  When using TypeScript, at least version 4.5+ is required.
</Note>

Make sure to set the `APPLICATION_ID` and `APPLICATION_SECRET` environment variables before running the application.

ClickHouse JS supports various query formats, data streaming, and advanced features like query cancellation and custom settings. For more detailed documentation, refer to the [ClickHouse JS client documentation](https://clickhouse.com/docs/en/integrations/language-clients/javascript).

### Go

To get started with the ClickHouse Go client:

<Steps>
  <Step title="Install the ClickHouse Go driver">
    ```bash theme={"system"}
    go get -u github.com/ClickHouse/clickhouse-go/v2
    ```
  </Step>

  <Step title="Import and create a connection">
    ```go theme={"system"}
    package main

    import (
        "context"
        "fmt"
        "log"
        "github.com/ClickHouse/clickhouse-go/v2"
    )

    func main() {
        conn, err := clickhouse.Open(&clickhouse.Options{
            Addr: []string{"clickhouse.us-east-2.propeldata.com:8443"},
            Auth: clickhouse.Auth{
                Database: "default",
                Username: os.Getenv("APPLICATION_ID"),
                Password: os.Getenv("APPLICATION_SECRET"),
            },
            TLS: &tls.Config{
                InsecureSkipVerify: true,
            },
        })
        if err != nil {
            log.Fatal(err)
        }
        defer conn.Close()

        // Check if the connection is alive
        if err := conn.Ping(context.Background()); err != nil {
            log.Fatal(err)
        }
    }
    ```
  </Step>

  <Step title="Execute queries">
    ```go theme={"system"}
    ctx := context.Background()
    rows, err := conn.Query(ctx, "SELECT 1")
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    for rows.Next() {
        var (
            col1 int
            // Add more variables for each column in your table
        )
        if err := rows.Scan(&col1); err != nil {
            log.Fatal(err)
        }
        fmt.Printf("col1: %s: %d\n", col1)
    }

    if err := rows.Err(); err != nil {
        log.Fatal(err)
    }
    ```
  </Step>
</Steps>

Make sure to set the `APPLICATION_ID` and `APPLICATION_SECRET` environment variables before running the application.

For more detailed documentation, refer to the [ClickHouse Go driver documentation](https://github.com/ClickHouse/clickhouse-go).

### Java

To get started with the ClickHouse Java client:

<Steps>
  <Step title="Add the dependency">
    ```xml theme={"system"}
    <dependency>
        <groupId>com.clickhouse</groupId>
        <artifactId>clickhouse-client</artifactId>
        <version>0.4.6</version>
    </dependency>
    ```
  </Step>

  <Step title="Connect to the database">
    ```java theme={"system"}
    import com.clickhouse.client.*;
    import com.clickhouse.data.ClickHouseFormat;

    public class ClickHouseExample {
        public static void main(String[] args) {
            String url = "https://clickhouse.us-east-2.propeldata.com:8443";
            String database = "propel";
            String user = System.getenv("APPLICATION_ID");
            String password = System.getenv("APPLICATION_SECRET");

            try (ClickHouseClient client = ClickHouseClient.newInstance(url);
                 ClickHouseNode server = ClickHouseNode.builder()
                     .host(url)
                     .database(database)
                     .credentials(ClickHouseCredentials.fromUserAndPassword(user, password))
                     .build()) {

                System.out.println("Connected successfully");
            } catch (Exception e) {
                System.err.println("Connection failed: " + e.getMessage());
            }
        }
    }
    ```
  </Step>

  <Step title="Execute queries">
    ```java theme={"system"}
    String query = "SELECT 1";
    try (ClickHouseClient client = ClickHouseClient.newInstance(url);
         ClickHouseResponse response = client.read(server)
             .format(ClickHouseFormat.RowBinaryWithNamesAndTypes)
             .query(query)
             .execute()) {

        for (ClickHouseRecord record : response.records()) {
            String col1 = record.getValue("column1").asString();
            int col2 = record.getValue("column2").asInteger();
            // Add more variables for each column in your table
            System.out.printf("col1: %s, col2: %d%n", col1, col2);
        }
    } catch (Exception e) {
        System.err.println("Query execution failed: " + e.getMessage());
    }
    ```
  </Step>
</Steps>

Make sure to set the `APPLICATION_ID` and `APPLICATION_SECRET` environment variables before running the application.

For more detailed documentation, refer to the [ClickHouse Java client documentation](https://github.com/ClickHouse/clickhouse-java).

### Rust

To get started with the ClickHouse Rust client:

<Steps>
  <Step title="Add the dependency">
    ```toml theme={"system"}
    [dependencies]
    clickhouse = "0.13.1"
    ```
  </Step>

  <Step title="Create a client instance">
    ```rust theme={"system"}
    use clickhouse::Client;

    let client = Client::default()
        // should include both protocol and port
        .with_url("https://clickhouse.us-east-2.propeldata.com:8443")
        .with_user(os.getenv("APPLICATION_ID"))
        .with_password(os.getenv("APPLICATION_SECRET"))
        .with_database("propel");
    ```
  </Step>

  <Step title="Execute queries">
    ```rust theme={"system"}
    use serde::Deserialize;
    use clickhouse::Row;
    use clickhouse::sql::Identifier;

    #[derive(Row, Deserialize)]
    struct MyRow<'a> {
        no: u32,
        name: &'a str,
    }

    let table_name = "some";
    let mut cursor = client
        .query("SELECT ?fields FROM ? WHERE no BETWEEN ? AND ?")
        .bind(Identifier(table_name))
        .bind(500)
        .bind(504)
        .fetch::<MyRow<'_>>()?;

    while let Some(row) = cursor.next().await? { .. }
    ```

    For more details about query execution:

    * The `?fields` placeholder is replaced with the fields specified in the Row struct (`no, name` in the example above).
    * The `?` placeholders are replaced with values from subsequent `bind()` calls in order.
    * Convenience methods `fetch_one::<Row>()` and `fetch_all::<Row>()` are available to get a single row or all rows.
    * Use `sql::Identifier` to safely bind table names.
  </Step>
</Steps>

For more detailed documentation, refer to the [ClickHouse Rust client documentation](https://github.com/ClickHouse/clickhouse-rs).

## PostgreSQL clients and SDKs

<CardGroup cols={2}>
  <Card title="psql" icon="database" href="#psql-postgresql-cli">
    The official PostgreSQL CLI.
  </Card>

  <Card title="Postgres.js" icon="database" href="#postgres-js">
    A full-featured client for Node.js.
  </Card>
</CardGroup>

### `psql` (PostgreSQL CLI)

To get started with the PostgreSQL CLI, `psql`, follow the steps below.

```bash theme={"system"}
PGPASSWORD=$APPLICATION_SECRET \
psql -h postgresql.us-east-2.propeldata.com \
  -d propel \
  -U $APPLICATION_ID
```

After a successful connection, you can make the query below.

```bash theme={"system"}
propel=> SELECT 1;
```

### Postgres.js

To get started with the Postgres.js client:

<Steps>
  <Step title="Install the package">
    ```bash theme={"system"}
    npm i postgres
    ```
  </Step>

  <Step title="Create connection file">
    ```javascript theme={"system"}
    // db.js
    import postgres from 'postgres'

    const sql = postgres({
      host: 'postgresql.us-east-2.propeldata.com',
      port: 5432,
      database: 'propel',
      username: process.env.APPLICATION_ID,
      password: process.env.APPLICATION_SECRET
    })

    export default sql
    ```
  </Step>

  <Step title="Set environment variables">
    Create `APPLICATION_ID` and `APPLICATION_SECRET` environment variables with your actual credentials.
  </Step>

  <Step title="Execute queries">
    ```javascript theme={"system"}
    import sql from './db.js'

    async function select() {
      try {
        const result = await sql`
          SELECT 1
        `
        console.log(result)
        return result
      } catch (error) {
        console.error('Error executing query:', error)
      } finally {
        sql.end()
      }
    }
    ```
  </Step>
</Steps>