Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Cette page explique comment gérer les modifications du schéma de base de données Spanner avec Liquibase pour les bases de données au dialecte GoogleSQL et les bases de données au dialecte PostgreSQL.
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 en dialecte GoogleSQL, vous devez installer l'extension Liquibase Spanner. Pour les bases de données en dialecte PostgreSQL, Liquibase peut utiliser sa prise en charge intégrée de PostgreSQL avec PGAdapter.
GoogleSQL
Suivez les instructions de la documentation de Liquibase pour installer et configurer Liquibase, et pour prendre un instantané de votre base de données. Dans le fichier de configuration liquibase.properties, définissez la propriété url comme suit.
Accédez à la page "Versions de l'extension Liquibase" de Spanner sur GitHub et sélectionnez la dernière version.
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
Placez le fichier JAR téléchargé dans le répertoire lib de Liquibase. Le fichier JAR inclut l'extension, le SDK Spanner et le pilote JDBC Spanner.
PostgreSQL
Assurez-vous que PGAdapter est démarré et en cours d'exécution sur la machine sur laquelle vous installez Liquibase. Pour en savoir plus, consultez la section Démarrer PGAdapter.
Suivez les instructions de la documentation de Liquibase pour installer et configurer Liquibase, et pour prendre un instantané de votre base de données.
Dans le fichier de configuration liquibase.properties, définissez la propriété url comme suit.
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'est pas compatible avec les transactions DDL. Cela garantit que les transactions DDL sont converties en lots DDL. Pour en savoir plus, consultez la section Options de DDL pour PGAdapter.
Examiner les exemples Liquibase
GoogleSQL
L'exemple de fichier de journal des modifications changelog.yaml inclus avec l'extension Liquibase GoogleSQL illustre de nombreuses fonctionnalités de Liquibase et explique 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éez 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, utilisez le script create_database_change_log.sql pour créer les tables de métadonnées databasechangeloglock et databasechangelog. 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:
Accordez à l'extension Spanner Liquibase l'utilisation temporaire de vos 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
Saisissez le code YAML suivant dans votre éditeur favori.
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 la section Sensibilité à la casse PostgreSQL.
Notez que l'ensemble de modifications createTable doit inclure une contrainte de clé primaire, et que le nom de la contrainte de clé primaire doit être pk_table_name.
Enregistrez les modifications sous le nom changelog.yaml.
Exécuter Liquibase
Appliquez le changement 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. Vous pouvez remplacer la valeur du fichier en ajoutant l'argument suivant à la commande 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.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/05 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 2025/09/05 (UTC)."],[],[],null,["# Integrate Spanner with Liquibase\n\nThis page describes how to manage Spanner database schema changes\nwith [Liquibase](https://www.liquibase.org/) for GoogleSQL-dialect databases and PostgreSQL-dialect databases.\n\nLiquibase is an open-source database-independent library for tracking, managing,\nand applying database schema changes. It supports SQL as well as declarative\nformats such as XML, YAML, and JSON.\n\nLiquibase can target Spanner databases. It supports all\nSpanner features, with some limitations.\n\n- To see general limitations, see [limitations](https://github.com/cloudspannerecosystem/liquibase-spanner/blob/master/limitations.md).\n- To see additional information for PostgreSQL-dialect databases, such as Liquibase requirements, supported change types, and limitations, see [PGAdapter and Liquibase](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/samples/java/liquibase).\n\nInstall Liquibase\n-----------------\n\nTo use Liquibase with GoogleSQL-dialect databases, you have to install the\nSpanner Liquibase extension. For PostgreSQL-dialect databases, Liquibase can use\nits built-in PostgreSQL support in conjunction with\n[PGAdapter](/spanner/docs/pgadapter). \n\n### GoogleSQL\n\n1. Follow the instructions in the [Liquibase documentation](https://www.liquibase.org/get-started/quickstart) to install and configure Liquibase, and to take a snapshot of your database. In the `liquibase.properties` configuration file, set the `url` property as follows.\n\n```\n jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE\n \n``` \n\n Your `liquibase.properties` configuration file can contain only this\n property. Other properties are optional.\n\n1. Navigate to the Spanner Liquibase Extension releases page\n on GitHub and select the [latest release](https://github.com/cloudspannerecosystem/liquibase-spanner/releases/latest).\n\n2. Select and download the JAR file with the name\n `liquibase-spanner-x.y.z-all.jar`, where x.y.z represents the extension\n version number. For example, `liquibase-spanner-4.17.0-all.jar`.\n\n3. Place the downloaded JAR file in the Liquibase lib directory. The JAR\n file includes the extension, the Spanner SDK, and the\n Spanner JDBC driver driver.\n\n### PostgreSQL\n\n1. Ensure that PGAdapter is started and running on the machine\n where you install Liquibase. For more information, see [Start\n PGAdapter](/spanner/docs/pgadapter-start).\n\n2. Follow the instructions in the [Liquibase documentation](https://www.liquibase.org/get-started/quickstart)\n to install and configure Liquibase, and to take a snapshot of your database.\n\nIn the `liquibase.properties` configuration file, set the `url` property as\nfollows. \n\n```\n jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction\n \n```\n\nYour `liquibase.properties` configuration file can contain only this\nproperty. Other properties are optional.\n\nThe `url` string must include\n`options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction`\nbecause Spanner doesn't support DDL transactions, and this\nensures that DDL transactions are converted to DDL batches. For more\ninformation, see [DDL Options for PGAdapter](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/docs/ddl.md).\n\nReview the Liquibase samples\n----------------------------\n\n### GoogleSQL\n\nThe sample change log file [changelog.yaml](https://github.com/cloudspannerecosystem/liquibase-spanner/blob/master/example/changelog.yaml) included with\nthe GoogleSQL Liquibase extension demonstrates many of the\nfeatures of Liquibase and how to use them with Spanner.\n\n### PostgreSQL\n\nThe sample change log file `dbchangelog.xml` available in the\n[PGAdapter and Liquibase GitHub repository](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/samples/java/liquibase)\ndemonstrates many of the features of Liquibase and how to use them with\nSpanner.\n\nLiquibase quickstart\n--------------------\n\nThis quickstart shows you how to use Liquibase to add a `Singers` table to a\ndatabase.\n\n### Before you begin\n\n- Make sure that you have completed the preceding steps to [install](#install-liq)\n Liquibase.\n\n- Create a Spanner instance.\n\n- Create a GoogleSQL-dialect database or PostgreSQL-dialect database.\n\n- For PostgreSQL-dialect databases only, ensure that PGAdapter is started and running\n on the same machine as your Liquibase installation. For more information, see\n [Start PGAdapter](/spanner/docs/pgadapter-start).\n\n- For PostgreSQL-dialect databases only, use the [create_database_change_log.sql](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/samples/java/liquibase/create_database_change_log.sql)\n script to create the `databasechangeloglock` and `databasechangelog` metadata\n tables. You must create these tables to override the tables that Liquibase\n creates automatically in your database. This is to ensure that the correct\n PostgreSQL data types for Spanner are used in these\n tables.\n\n You can run the script with the following command: \n\n ```\n psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql\n ```\n- Give the Spanner Liquibase extension temporary use of your\n Spanner user credentials for API access by running the\n following `gcloud` command:\n\n ```\n gcloud auth application-default login\n ```\n\n### Create a changelog.yaml\n\n1. Enter the following YAML into your favorite editor.\n\n databaseChangeLog:\n - preConditions:\n onFail: HALT\n onError: HALT\n\n - changeSet:\n id: create-singers-table\n author: spanner-examples\n changes:\n - createTable:\n tableName: Singers\n columns:\n - column:\n name: SingerId\n type: BIGINT\n constraints:\n primaryKey: true\n primaryKeyName: pk_Singers\n - column:\n name: Name\n type: VARCHAR(255)\n\n This YAML defines a table called `Singers` with a primary key `SingerId` and a\n column called `Name` to store the singer's name.\n\n For PostgreSQL-dialect databases, we recommend using all lower case for table and column\n names. For more information, see\n [PostgreSQL case sensitivity](/spanner/docs/reference/postgresql/lexical#case-sensitivity).\n\n Note that the `createTable` change set must include a primary key constraint,\n and the name of the primary key constraint must be pk_\u003cvar translate=\"no\"\u003etable_name\u003c/var\u003e.\n2. Save your changes as `changelog.yaml`.\n\n### Run Liquibase\n\nApply the changeset in `changelog.yaml` by executing the following command: \n\n```\nliquibase --changeLogFile changelog.yaml update\n```\n\nLiquibase uses the URL that you defined in the `liquibase.properties` file. You\ncan override the value in the file by adding the following argument to the\npreceding command: \n\n```\n--url URL\n```\n\n### Verify your changes\n\nThe updates in the preceding step caused the `Singer` table to be added to your\ndatabase. Also, the `DATABASECHANGELOG` and `DATABASECHANGELOGLOCK` tables were\nadded (GoogleSQL-dialect database) or updated (PostgreSQL-dialect database).\n\nYou can verify the existence of these tables through the Google Cloud console\nor gcloud CLI. For example, running the SQL query `SELECT * FROM\nINFORMATION_SCHEMA.TABLES` returns a list of all tables in your database. \n\n```\ngcloud spanner databases execute-sql DATABASE_NAME --instance=INSTANCE \\\n --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'\n```\n\nYou can see a record of the changes that were applied by querying the contents\nof `DATABASECHANGELOG`.\n\nWhat's next\n-----------\n\n- For more documentation, visit the [Spanner Liquibase Extension](https://github.com/cloudspannerecosystem/liquibase-spanner)\n GitHub repository.\n\n- To learn more about Liquibase, see [Getting Started with Liquibase](https://www.liquibase.org/get-started)."]]
