Skip to content
Learni
View all tutorials
Bases de données

Comment intégrer Cloud Spanner à une API Node.js en 2026

14 minBEGINNER
Node.jsGoogle CloudCloud Spanner

Introduction

Cloud Spanner est la base de données distribuée globalement cohérente de Google. Elle combine la scalabilité horizontale des bases NoSQL avec la cohérence transactionnelle des bases relationnelles. Ce tutoriel vous guide pas à pas pour l'intégrer dans une API Node.js. Vous apprendrez à configurer le client, créer un schéma et exécuter des opérations CRUD. Idéal pour les applications qui nécessitent une haute disponibilité mondiale.

Prérequis

  • Compte Google Cloud avec facturation activée
  • Node.js 18 ou supérieur
  • Connaissances de base en TypeScript et SQL
  • CLI gcloud installée et authentifiée

Initialisation du projet

terminal
mkdir spanner-api && cd spanner-api
npm init -y
npm install @google-cloud/spanner express typescript @types/express ts-node

Cette commande crée le projet et installe le client officiel Cloud Spanner ainsi qu'Express pour l'API REST.

Configuration du client Spanner

src/spanner.ts
import { Spanner } from '@google-cloud/spanner';

const spanner = new Spanner({
  projectId: 'votre-projet-id',
  keyFilename: './service-account.json'
});

export const instance = spanner.instance('spanner-instance');
export const database = instance.database('ma-base-de-donnees');

Le client est initialisé avec les identifiants du compte de service. Utilisez toujours un fichier JSON dédié et jamais de clés en dur dans le code.

Création de la base et du schéma

src/create-database.ts
import { database } from './spanner';

async function createDatabase() {
  const schema = [
    `CREATE TABLE Users (
      UserId INT64 NOT NULL,
      Email STRING(255) NOT NULL,
      CreatedAt TIMESTAMP NOT NULL OPTIONS (allow_commit_timestamp=true)
    ) PRIMARY KEY (UserId)`
  ];
  const [operation] = await database.create({ schema });
  await operation.promise();
  console.log('Base de données créée');
}
createDatabase();

Ce script crée la base et la table Users. Spanner exige une clé primaire et utilise des types spécifiques comme INT64 et TIMESTAMP.

Insertion de données

src/insert-user.ts
import { database } from './spanner';

async function insertUser(userId: number, email: string) {
  const table = database.table('Users');
  await table.insert({
    UserId: userId,
    Email: email,
    CreatedAt: 'spanner.commit_timestamp()'
  });
  console.log('Utilisateur inséré');
}
insertUser(1, 'test@example.com');

L'insertion utilise la méthode insert du client. Le commit timestamp est géré automatiquement par Spanner pour la cohérence.

Requête de données

src/query-users.ts
import { database } from './spanner';

async function getUsers() {
  const [rows] = await database.run({
    sql: 'SELECT UserId, Email FROM Users WHERE UserId = @id',
    params: { id: 1 }
  });
  console.log(rows.map(row => row.toJSON()));
}
getUsers();

Les requêtes paramétrées évitent les injections SQL et sont la méthode recommandée sur Spanner.

API Express complète

src/server.ts
import express from 'express';
import { database } from './spanner';

const app = express();
app.use(express.json());

app.get('/users/:id', async (req, res) => {
  const [rows] = await database.run({
    sql: 'SELECT * FROM Users WHERE UserId = @id',
    params: { id: parseInt(req.params.id) }
  });
  res.json(rows.map(r => r.toJSON()));
});

app.listen(3000, () => console.log('API démarrée sur 3000'));

Ce serveur expose une route GET simple qui interroge Spanner. Compilez avec tsc avant déploiement.

Bonnes pratiques

  • Utilisez toujours des requêtes paramétrées
  • Gérez les sessions et transactions explicitement pour les opérations complexes
  • Activez le monitoring via Cloud Monitoring
  • Séparez les environnements avec des instances distinctes
  • Activez le chiffrement au repos par défaut

Erreurs courantes à éviter

  • Oublier d'activer l'API Spanner dans le projet Google Cloud
  • Utiliser des types SQL incorrects (INT au lieu de INT64)
  • Ne pas configurer de compte de service avec les bons rôles
  • Ignorer la latence des opérations de création de base

Pour aller plus loin

Approfondissez vos compétences avec nos formations Cloud Spanner.