Intégrer Spanner à Liquibase

Cette page explique comment gérer les modifications du schéma de base de données Spanner avec Liquibase.

Liquibase est une bibliothèque Open Source indépendante de la base de données pour le suivi, la gestion et l'application des modifications de schéma de base de données. Elle est compatible avec le langage SQL ainsi qu'avec les formats déclaratifs tels que XML, YAML et JSON.

Liquibase peut cibler des bases de données Spanner. Il est compatible avec toutes les fonctionnalités de Spanner, avec certaines limitations.

  • Pour connaître les limites générales, consultez la section Limites.
  • Pour en savoir plus sur les bases de données en dialecte PostgreSQL, telles que les exigences de Liquibase, les types de modifications compatibles et les limites, consultez PGAdapter et Liquibase.

Installer Liquibase

Pour utiliser Liquibase avec des bases de données de dialecte GoogleSQL, vous devez installer Extension Liquibase de Spanner. Pour les bases de données de dialecte PostgreSQL, Liquibase peut utiliser la prise en charge intégrée de PostgreSQL PGAdapter :

GoogleSQL

  1. Suivez les instructions de la documentation de Liquibase pour installer et configurer Liquibase, et pour créer un instantané de votre base de données. Dans le fichier de configuration liquibase.properties, définissez la propriété url comme suit : suit.

    jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE

    Votre fichier de configuration liquibase.properties ne peut contenir que cette propriété. Les autres propriétés sont facultatives.

  2. Accédez à la page "Versions de l'extension Liquibase" de Spanner sur GitHub et sélectionnez la dernière version.

  3. Sélectionnez et téléchargez le fichier JAR nommé liquibase-spanner-x.y.z-all.jar, où xyz représente le numéro de version de l'extension. Exemple :liquibase-spanner-4.17.0-all.jar

  4. Placez le fichier JAR téléchargé dans le répertoire lib de Liquibase. Fichier JAR inclut l'extension, le SDK Spanner et le pilote JDBC Spanner pilote.

PostgreSQL

  1. Assurez-vous que PGAdapter est démarré et en cours d'exécution sur la machine sur laquelle vous allez installer Liquibase. Pour en savoir plus, consultez Démarrez PGAdapter.

  2. Suivez les instructions de la documentation de Liquibase pour installer et configurer Liquibase, et pour créer un instantané de votre base de données. Dans le fichier de configuration liquibase.properties, définissez la propriété url comme suit : suit.

    jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction

    Votre fichier de configuration liquibase.properties ne peut contenir que cette propriété. Les autres propriétés sont facultatives.

    La chaîne url doit inclure options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction. car Spanner n'accepte pas les transactions LDD. Les transactions LDD sont automatiquement converties en lots LDD. Pour plus pour en savoir plus, consultez Options LDD pour PGAdapter

Examiner les exemples Liquibase

GoogleSQL

L'exemple de fichier journal des modifications changelog.yaml inclus dans le fichier L'extension GoogleSQL Liquibase illustre de nombreuses fonctionnalités Liquibase et comment les utiliser avec Spanner

PostgreSQL

L'exemple de fichier de journal des modifications dbchangelog.xml disponible dans le dépôt GitHub de PGAdapter et Liquibase illustre de nombreuses fonctionnalités de Liquibase et explique comment les utiliser avec Spanner.

Guide de démarrage rapide de Liquibase

Ce guide de démarrage rapide explique comment utiliser Liquibase pour ajouter une table Singers à une base de données.

Avant de commencer

  • Assurez-vous d'avoir effectué les étapes précédentes pour installer Liquibase.

  • Créer une instance Spanner

  • Créez une base de données en dialecte GoogleSQL ou en dialecte PostgreSQL.

  • Pour les bases de données en dialecte PostgreSQL uniquement, assurez-vous que PGAdapter est démarré et en cours d'exécution sur la même machine que votre installation de Liquibase. Pour en savoir plus, consultez la section Démarrer PGAdapter.

  • Pour les bases de données en dialecte PostgreSQL uniquement, créez les tables de métadonnées databasechangeloglock et databasechangelog à l'aide du script create_database_change_log.sql. Vous devez créer ces tables pour remplacer les tables que Liquibase crée automatiquement dans votre base de données. Cela permet de s'assurer que les types de données PostgreSQL appropriés pour Spanner sont utilisés dans ces tables.

    Vous pouvez exécuter le script avec la commande suivante :

    psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql

  • Accordez à l'extension Spanner Liquibase l'utilisation temporaire de vos propres identifiants utilisateur Spanner pour l'accès à l'API en exécutant la commande gcloud suivante :

    gcloud auth application-default login

Créer un fichier changelog.yaml

  1. Saisissez le code YAML suivant dans votre éditeur favori.

    databaseChangeLog:
  - preConditions:
     onFail: HALT
     onError: HALT

  - changeSet:
     id: create-singers-table
     author: spanner-examples
     changes:
       - createTable:
          tableName: Singers
          columns:
            -  column:
                name:    SingerId
                type:    BIGINT
                constraints:
                  primaryKey: true
                  primaryKeyName: pk_Singers
            -  column:
                name:    Name
                type:    VARCHAR(255)

    Ce code YAML définit une table Singers avec une clé primaire SingerId et une colonne appelée Name pour stocker le nom du chanteur.

    Pour les bases de données en dialecte PostgreSQL, nous vous recommandons d'utiliser des noms de table et de colonne en minuscules. Pour en savoir plus, consultez Sensibilité à la casse de PostgreSQL.

    Notez que l'ensemble de modifications createTable doit inclure une contrainte de clé primaire, et le nom de la contrainte de clé primaire doit être pk_table_name.

  2. Enregistrez vos modifications sous le nom changelog.yaml.

Exécuter Liquibase

Appliquez le jeu de modifications dans changelog.yaml en exécutant la commande suivante:

liquibase --changeLogFile changelog.yaml update

Liquibase utilise l'URL que vous avez définie dans le fichier liquibase.properties. Toi peut remplacer la valeur contenue dans le fichier en ajoutant l'argument suivant à la précédente:

--url URL

Vérifier vos modifications

Les mises à jour de l'étape précédente ont entraîné l'ajout de la table Singer à votre base de données. De plus, les tables DATABASECHANGELOG et DATABASECHANGELOGLOCK ont été ajoutées (base de données en dialecte GoogleSQL) ou mises à jour (base de données en dialecte PostgreSQL).

Vous pouvez vérifier l'existence de ces tables via la console Google Cloud ou la gcloud CLI. Par exemple, l'exécution de la requête SQL SELECT * FROM INFORMATION_SCHEMA.TABLES renvoie la liste de toutes les tables de votre base de données.

gcloud spanner databases execute-sql DATABASE_NAME --instance=INSTANCE \
    --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'

Vous pouvez consulter un enregistrement des modifications appliquées en interrogeant le contenu de DATABASECHANGELOG.

Étape suivante