---
title: How to connect to a Serverless SQL Database
description: Step-by-step guide to connect to a Scaleway Serverless SQL Database.
tags: database serverless-sql-database serverless-db serverless-database postgresql 
dates:
  validation: 2025-09-02
  posted: 2023-08-11
---
import Requirements from '@macros/iam/requirements.mdx'

This page shows you how to set up the connection to a Serverless SQL Database using the Scaleway console.

## Overview

To connect to a Serverless SQL Database, you can either use a **connection string**, or **connection parameters**.

- A connection string provides the necessary information and parameters to establish a connection between an [IAM user](/iam/concepts/#user) or [application](/iam/concepts/#application), and the database. The string is written as follows:
    ```bash
    postgres://[user-or-application-id]:[api-secret-key]@[database-hostname]:5432/[database-name]?sslmode=require
    ```
    <Message type="note">
    The `?sslmode=require` parameter is mandatory to connect to your database. Refer to the [dedicated documentation](/serverless-sql-databases/api-cli/secure-connection-ssl-tls/) for more information about SSL connection to Serverless SQL Databases.
    </Message>

- Connection parameters provide the necessary information and parameters to connect an [IAM user](/iam/concepts/#user) or [application](/iam/concepts/#application) to a database. The parameters are expressed in the `KEY="value"` format, as follows:

    ```bash
    PGUSER="user-or-application-id"
    PGPASSWORD="api-secret-key"
    PGHOST="database-hostname"
    PGPORT="5432"
    PGDATABASE="database-name"
    ```

    <Message type="note">
    The `PGSSLMODE="require"` parameter is required to connect to your database, but can be omitted as it is provided by default by most SQL clients. Refer to the [dedicated documentation](/serverless-sql-databases/api-cli/secure-connection-ssl-tls/) for more information about SSL connection to Serverless SQL Databases.
    </Message>

<Requirements />

- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
- Created a [Serverless SQL Database](/serverless-sql-databases/how-to/create-a-database/)

## How to connect to a database

1. From the **Overview** tab of your database, click the **Connect application** button. The setup wizard displays.

2. Select the [principal](/iam/concepts/#principal) to connect to the database, who can be either:
    - Yourself, as an [IAM user](/iam/concepts/#user), or
    - An [IAM application](/iam/concepts/#application) you [previously created](/iam/how-to/create-application/) in the IAM section of the console.
    <Message type="note">
        Refer to the [IAM documentation](/iam/reference-content/overview/) for more information on identities and access rights.
    </Message>
3. Set up the **connection string** or **connection parameters**.
    <Tabs>
        <TabsTab label="With an existing API key">
        <br/>
        If you already have an [API secret key](/iam/concepts/#api-key), replace the `[INSERT_SECRET_KEY_HERE]` placeholder with your **secret key** as shown below.
        - Connection string:
            ```
            postgresql://example-user-4052-8739-2017c3d9c0d9:example-secret-key-3fd8f53210ec@example-host-4d89-8e7d-g56vb754.pg.sdb.fr-par.scw.cloud:5432/serverless-sqldb-example-db?sslmode=require
            ```
        - Connection parameters:
            ```bash
            PGUSER="example-user-4052-8739-2017c3d9c0d9"
            PGPASSWORD="example-secret-key-3fd8f53210ec"
            PGHOST="example-host-4d89-8e7d-g56vb754.pg.sdb.fr-par.scw.cloud"
            PGPORT="5432"
            PGDATABASE="serverless-sqldb-example-db"
            ```
        </TabsTab>
        <TabsTab label="Without an existing API key">
        <br/>
        If you do not have an [API key](/iam/concepts/#api-key), click **Generate new secret key**.
        
        A new secret key is created, and inserted directly into the connection string and parameters.

        The newly created API key can be found in the [API keys section](https://console.scaleway.com/iam/api-keys) of the Scaleway Console.
        </TabsTab>
    </Tabs>
4. Copy your connection string or parameters and store them securely, as they will only be shown once.

### Connect a user to a database

1. Run the following command in a terminal (including the `"` characters):

    ```bash
    psql "[YOUR_CONNECTION_STRING]"
    ```

    An output similar to the following response displays:

    ```sql
    psql (15.3, server 14.8 (Debian 14.8-1pgsg120+1))
    SSL connection (protocol: TLSv1.3, cipher: TLS_AES_128_GCM_SHA256, compression: off)
    Type "help" for help.
    ```

2. Run the following command to see the version of your Serverless SQL Database:

    ```sql
    SELECT version();
    ```

    An output similar to the following displays:

    ```
    PostgreSQL 14.8 (Debian 14.8-1.pgdg120+1) on x86_64-pc-linux-gnu,
    compiled by gcc (Debian 12.2.0-14) 12.2.0, 64-bit
    ```

3. Press `q` to quit the version overview.

You can now perform the authorized actions in the database.

### Connect an application to a database

Use the connection parameters (host, port, user, password, and database name) previously saved to connect your application to the database.

<Message type="note">
  Connection methods may vary depending on the framework or library used in your application. Refer to our [dedicated documentation](/serverless-sql-databases/api-cli/secure-connection-ssl-tls/) on securing connections with SSL/TLS, and to the corresponding official documentation for more information.
</Message>

## Troubleshooting

Refer to the [dedicated troubleshooting page](/serverless-sql-databases/troubleshooting/connection-errors/) to solve connection issues with Serverless SQL Databases.