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

# Connect to Neki

> Postgres clients, roles, router groups, and replica routing

Neki uses the Postgres wire protocol, so you can connect with `psql` or any
standard Postgres driver. Your applications connect to a Neki router instead
of connecting to each shard's primary or replicas. The router plans each statement and sends it to
the required Postgres shards.

Create a role for each application or permission boundary. The same role can
be reused by that application's connection pool and other connections that
need the same permissions.

## Get connection details

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step>
        Open the database in the PlanetScale dashboard and click **Connect**.
      </Step>

      <Step>
        Optionally, select the branch you want to connect to.
      </Step>

      <Step>
        Select an existing role, or create a [user-defined role](/docs/neki/connecting/roles) with the permissions your application needs.
      </Step>

      <Step>
        Under **Connection target**, choose a router group. The `default`
        router group is selected by default.
      </Step>

      <Step>
        To send queries to read-only replicas, select **Route queries to a
        replica**. This option is separate from the router-group target.
      </Step>

      <Step>
        Select your framework, language, or **Postgres CLI**, then copy the generated connection details.
      </Step>
    </Steps>

    The generated `psql` command has this form:

    ```bash theme={null}
    psql 'host=<HOST> port=5432 user=<USERNAME> password=<PASSWORD> dbname=postgres sslnegotiation=direct sslmode=verify-full sslrootcert=system'
    ```

    Replace the placeholders with the values from the dashboard. Generated connections use the `postgres` logical database within a cluster.
  </Tab>

  <Tab title="CLI">
    Install and authenticate the [PlanetScale CLI](/docs/cli/planetscale-environment-setup) first.

    <Steps>
      <Step>
        Open a `psql` session. `pscale shell` creates temporary credentials, so you do not need a saved role for this step.

        ```bash theme={null}
        pscale shell <DATABASE> <BRANCH> --org <ORGANIZATION>
        ```
      </Step>

      <Step>
        To target a router group other than the default, add `--router`.

        ```bash theme={null}
        pscale shell <DATABASE> <BRANCH> \
          --org <ORGANIZATION> \
          --router <ROUTER_GROUP>
        ```
      </Step>
    </Steps>

    For a persistent role that your application can reuse, create one with `pscale role`. See [Roles and credentials](/docs/neki/connecting/roles).
  </Tab>
</Tabs>

## Connection parameters

| Parameter | Value                                                                                |
| :-------- | :----------------------------------------------------------------------------------- |
| Host      | The hostname shown on the **Connect** page                                           |
| Port      | `5432`                                                                               |
| Username  | The complete generated username, including any suffix for a non-default router group |
| Password  | The password shown when the role is created or reset                                 |
| Database  | logical database, `postgres` by default                                              |
| TLS       | Required; use the verification settings generated for your client                    |

All connections to Neki databases use port `5432`.

## Secure connections

Neki requires TLS. Your client should verify both the certificate chain and the
server hostname instead of only encrypting the connection.

The generated `psql` command uses `sslmode=verify-full` and the system CA store.
Other drivers use different names for the same settings. Select your framework
or language on the **Connect** page to get the correct TLS configuration for
that client.

## Private connections

Keep traffic between your cloud network and Neki off the public internet with
[AWS PrivateLink](/docs/neki/connecting/private-connections/aws-privatelink) or
[GCP Private Service Connect](/docs/neki/connecting/private-connections/gcp-private-service-connect).
Private connections use the same roles, router groups, and required TLS
settings as public connections.

## Primary and replica routing

By default, Neki sends work to shard primaries. Use that for writes and for reads that need the latest committed data.

Set `__neki.target` to send reads to replicas.

Selecting **Route queries to a replica** on the **Connect** page adds this
setting to the generated connection options. It does not change the username.

```sql theme={null}
SET __neki.target = 'replica';
```

Or set it when the connection starts. For `psql`, use `PGOPTIONS`:

```bash theme={null}
PGOPTIONS='-c __neki.target=REPLICA' \
  psql 'host=<HOST> port=5432 user=<USERNAME> password=<PASSWORD> dbname=postgres sslnegotiation=direct sslmode=verify-full sslrootcert=system'
```

For a connection URI, add it as the Postgres `options` parameter:

```text theme={null}
postgresql://<USERNAME>:<PASSWORD>@<HOST>:5432/postgres?sslmode=verify-full&sslrootcert=system&options=-c%20__neki.target%3DREPLICA
```

For `pscale shell`, add `--replica`. That sets `__neki.target=REPLICA` for the session.

See [Choosing where reads run](/docs/neki/query-planning#choosing-where-reads-run) for Neki's replica selection settings and lag behavior.

## Need help?

Get help from [the PlanetScale Support team](https://planetscale.com/contact?initial=support), or join our [Discord community](https://pscale.link/community) to see how others are using PlanetScale.