connect-to-a-database.mdx

meta	content	tags	dates	categories
title description How to connect to a Serverless SQL Database Step-by-step guide to connect to a Scaleway Serverless SQL Database.	h1 paragraph How to connect to a Serverless SQL Database Step-by-step guide to connect to a Scaleway Serverless SQL Database.	database serverless-sql-database serverless-db serverless-database postgresql	validation posted 2025-03-25 2023-08-11	serverless

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 or application, and the database. The string is written as follows:

  postgres://[user-or-application-id]:[api-secret-key]@[database-hostname]:5432/[database-name]?sslmode=require

  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.

• Connection parameters provide the necessary information and parameters to connect an IAM user or application to a database. The parameters are expressed in the KEY="value" format, as follows:

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

  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.

• A Scaleway account logged into the console
• Owner status or IAM permissions allowing you to perform actions in the intended Organization
• Created a Serverless SQL Database

How to set up credentials

1. From the Overview tab of your database, click the Set up credentials button. The setup wizard displays.

2. Select the principal to connect to the database, who can be either:

   • Yourself, as an IAM user, or
   • An IAM application you previously created in the IAM section of the console.
   Refer to the [IAM documentation](/iam/reference-content/overview/) for more information on identities and access rights.

3. Set up the connection string or connection parameters.
   If you already have an API secret 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: sh 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"
   If you do not have an 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>
   

4. Copy your connection string or parameters and store them securely, as they will only be shown once.

How to connect to a database as a user

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

   psql "[YOUR_CONNECTION_STRING]"

   An output similar to the following response displays:

   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:

   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.

How to 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.

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.

Troubleshooting

Refer to the dedicated troubleshooting page to solve connection issues with Serverless SQL Databases.