---
title: "Accéder à sa base de données"
description: "Comment se connecter à une base de données PostgreSQL (CNPG) hébergée sur votre cluster via kubectl ou Freelens."
source_url:
  html: https://docs.blackswift.cloud/deployer/se-connecter-a-une-bdd/
  md: https://docs.blackswift.cloud/deployer/se-connecter-a-une-bdd.md
---

# Accéder à sa base de données

> Comment se connecter à une base de données PostgreSQL (CNPG) hébergée sur votre cluster via kubectl ou Freelens.

Vos bases de données PostgreSQL sont gérées par [CloudNativePG](https://cloudnative-pg.io/) (CNPG — voir [PostgreSQL managé](https://docs.blackswift.cloud/deployer/postgresql-manage.md) pour en créer une) et ne sont **pas exposées publiquement** par défaut. Pour vous y connecter depuis votre poste, vous devez utiliser un **port-forward** — soit en ligne de commande avec `kubectl`, soit via l'interface graphique de **Freelens**.

<Aside type="tip">
Cette procédure nécessite d'avoir [récupéré votre kubeconfig](https://docs.blackswift.cloud/demarrer/recuperer-votre-kubeconfig.md) au préalable.
</Aside>

## Prérequis

Choisir un client au choix parmi ceux ci-dessous pour se connecter à votre environnement Kubernetes :

- `kubectl`, un CLI (ligne de commande) pour interagir avec Kubernetes — [guide d'installation](https://kubernetes.io/fr/docs/tasks/tools/install-kubectl/)
- `Freelens`, un IDE (interface graphique) pour interagir avec Kubernetes — [guide d'installation](https://freelensapp.github.io/)
- `k9s` un hybride (cli + interface graphique) pour interagir avec Kubernetes [guide d'installation](https://k9scli.io/topics/install/)

Pour se connecter à votre base de données :

- Votre fichier `kubeconfig` configuré (variable `KUBECONFIG` ou `~/.kube/config`)
- Un client PostgreSQL : `psql`, [DBeaver](https://dbeaver.io/), [TablePlus](https://tableplus.com/), [pgAdmin](https://www.pgadmin.org/), DataGrip, etc.

## Identifier votre cluster CNPG

<Tabs>
  <TabItem label="kubectl">

Listez les clusters PostgreSQL disponibles dans votre namespace :

```bash
kubectl get clusters.postgresql.cnpg.io -n <votre-namespace>
```

Vous obtiendrez une sortie similaire à :

```
NAME              AGE   INSTANCES   READY   STATUS                     PRIMARY
my-app-database   30d   2           2       Cluster in healthy state   my-app-database-1
```

  </TabItem>
  <TabItem label="Freelens">

1. Ouvrez Freelens et sélectionnez votre cluster dans la barre latérale.
2. Naviguez vers **Custom Resources** dans le menu de gauche.
3. Recherchez le groupe `postgresql.cnpg.io` puis cliquez sur **Cluster**.
4. Sélectionnez votre namespace dans le filtre en haut de la vue.

Vous verrez la liste de vos clusters CNPG avec leur statut et le nom de l'instance primaire.

  </TabItem>
</Tabs>

<Aside>
Le nom sous la colonne **PRIMARY** correspond au pod qui accepte les connexions en lecture/écriture. Les autres instances sont des réplicas en lecture seule.
</Aside>

## Récupérer les identifiants de connexion

Les identifiants sont stockés dans un **Secret** Kubernetes généré automatiquement par CNPG. Le nom du secret suit la convention `<nom-du-cluster>-app`.

<Tabs>
  <TabItem label="kubectl">

Lisez uniquement la clé dont vous avez besoin, plutôt que le secret entier :

```bash
# le mot de passe
kubectl get secret <nom-du-cluster>-app -n <votre-namespace> \
  -o jsonpath='{.data.password}' | base64 -d && echo

# ou l'URI de connexion complète
kubectl get secret <nom-du-cluster>-app -n <votre-namespace> \
  -o jsonpath='{.data.uri}' | base64 -d && echo
```

Pour voir les autres champs sans afficher leur valeur :

```bash
kubectl get secret <nom-du-cluster>-app -n <votre-namespace> \
  -o go-template='{{range $k,$v := .data}}{{$k}}{{"\n"}}{{end}}'
```

<Aside type="caution">
Évitez `kubectl describe secret` et `kubectl get secret -o yaml` : le premier affiche
certaines valeurs en clair, le second les expose en base64, qui n'est pas un
chiffrement. Dans les deux cas le mot de passe finit dans votre historique de
terminal, et dans les journaux si la commande tourne en CI.
</Aside>

  </TabItem>
  <TabItem label="Freelens">

1. Dans le menu de gauche, naviguez vers **Config** → **Secrets**.
2. Sélectionnez votre namespace dans le filtre.
3. Cliquez sur le secret nommé `<nom-du-cluster>-app`.
4. Les valeurs sont masquées par défaut — cliquez sur l'icône **œil** à côté de chaque champ pour les révéler.

  </TabItem>
</Tabs>

Vous y trouverez notamment :

| Clé        | Description                          |
|------------|--------------------------------------|
| `host`     | Nom du service interne (cluster DNS) |
| `port`     | Port PostgreSQL (généralement 5432)  |
| `dbname`   | Nom de la base de données            |
| `username` | Utilisateur applicatif               |
| `password` | Mot de passe                         |
| `uri`      | URI de connexion complète            |

## Lancer le port-forward

<Tabs>
  <TabItem label="kubectl">

<Steps>

1. **Ouvrez un terminal** et lancez la commande suivante :

   ```bash
   kubectl port-forward -n <votre-namespace> svc/<nom-du-cluster>-rw 5432:5432
   ```

   Vous devriez voir :

   ```
   Forwarding from 127.0.0.1:5432 -> 5432
   Forwarding from [::1]:5432 -> 5432
   ```

   <Aside type="caution">
   Si le port 5432 est déjà utilisé sur votre poste (par exemple par un PostgreSQL local), choisissez un autre port local :

   ```bash
   kubectl port-forward -n <votre-namespace> svc/<nom-du-cluster>-rw 15432:5432
   ```

   Vous vous connecterez alors sur `localhost:15432`.
   </Aside>

2. **Gardez ce terminal ouvert** — le port-forward reste actif tant que la commande tourne.

3. **Connectez-vous** depuis un autre terminal ou votre client graphique.

</Steps>

  </TabItem>
  <TabItem label="Freelens">

<Steps>

1. Dans le menu de gauche, naviguez vers **Network** → **Services**.

2. Sélectionnez votre namespace dans le filtre.

3. Repérez le service `<nom-du-cluster>-rw` et cliquez dessus.

4. Dans le détail du service, cliquez sur le bouton **Forward Port** (ou faites un clic droit → **Forward Port**).

5. Configurez le port-forward :
   - **Port local** : `5432` (ou `15432` si le port est déjà utilisé)
   - **Port distant** : `5432`

6. Cliquez sur **Start** — un indicateur vert confirme que le tunnel est actif.

</Steps>

<Aside type="tip">
Freelens affiche les port-forwards actifs en bas de la fenêtre. Vous pouvez les arrêter à tout moment en cliquant sur la croix.
</Aside>

  </TabItem>
</Tabs>

## Se connecter à la base

<Tabs>
  <TabItem label="psql">

```bash
psql -h localhost -p 5432 -U <username> -d <dbname>
```

Le mot de passe vous sera demandé interactivement.

  </TabItem>
  <TabItem label="URI de connexion">

Pour les clients qui acceptent une URI (DBeaver, TablePlus, etc.) :

```
postgresql://<username>:<password>@localhost:5432/<dbname>
```

<Aside type="caution">
Si votre mot de passe contient des caractères spéciaux (`@`, `#`, `%`, etc.), pensez à les encoder en URL — ou utilisez plutôt les champs séparés dans votre client.
</Aside>

  </TabItem>
  <TabItem label="DBeaver / pgAdmin">

Remplissez les champs de connexion comme suit :

| Champ              | Valeur                              |
|--------------------|-------------------------------------|
| **Hôte**           | `localhost`                         |
| **Port**           | `5432` (ou le port local choisi)    |
| **Base de données**| La valeur `dbname` du secret        |
| **Utilisateur**    | La valeur `username` du secret      |
| **Mot de passe**   | La valeur `password` du secret      |
| **SSL**            | Désactivé (le tunnel est local)     |

  </TabItem>
</Tabs>

## Connexion en lecture seule (réplica)

Pour vous connecter à un réplica en lecture seule (utile pour des requêtes lourdes sans impacter la production), il suffit de cibler le service `-ro` au lieu de `-rw` :

<Tabs>
  <TabItem label="kubectl">

```bash
kubectl port-forward -n <votre-namespace> svc/<nom-du-cluster>-ro 5432:5432
```

  </TabItem>
  <TabItem label="Freelens">

Suivez la même procédure que pour le port-forward principal, mais sélectionnez le service `<nom-du-cluster>-ro` au lieu de `<nom-du-cluster>-rw`.

  </TabItem>
</Tabs>

<Aside>
Les services CNPG suivent cette convention :

- `<nom>-rw` → instance primaire (lecture/écriture)
- `<nom>-ro` → réplicas (lecture seule)
- `<nom>-r`  → toutes les instances (round-robin)
</Aside>

## Résolution de problèmes

### Le port-forward se coupe régulièrement

C'est un comportement normal lors de périodes d'inactivité. Relancez simplement le port-forward. Freelens gère automatiquement la reconnexion dans la plupart des cas ; avec `kubectl`, vous pouvez utiliser un wrapper comme [kubefwd](https://github.com/txn2/kubefwd) pour les reconnexions automatiques.

### `error: unable to forward port because pod is not running`

Vérifiez l'état de votre cluster CNPG :

<Tabs>
  <TabItem label="kubectl">

```bash
kubectl get pods -n <votre-namespace> -l cnpg.io/cluster=<nom-du-cluster>
```

Si les pods ne sont pas en état `Running`, consultez les événements :

```bash
kubectl describe cluster <nom-du-cluster> -n <votre-namespace>
```

  </TabItem>
  <TabItem label="Freelens">

1. Naviguez vers **Workloads** → **Pods**.
2. Filtrez par votre namespace et recherchez les pods dont le nom commence par `<nom-du-cluster>`.
3. Vérifiez que leur statut est **Running**. Si ce n'est pas le cas, cliquez sur un pod pour consulter les **Events** en bas de la page de détail.

  </TabItem>
</Tabs>

### `connection refused` sur localhost

Assurez-vous que le port-forward est toujours actif — vérifiez votre terminal (`kubectl`) ou la barre de statut en bas de Freelens.