Integrare Spanner con Liquibase

Questa pagina descrive come gestire le modifiche allo schema del database Spanner con Liquibase per i database con dialetto Google SQL e PostgreSQL.

Liquibase è una libreria open source indipendente dal database per monitorare, gestire e applicare le modifiche allo schema del database. Supporta SQL e formati dichiarativi come XML, YAML e JSON.

Liquibase può avere come target i database Spanner. Supporta tutte le funzionalità di Spanner, con alcune limitazioni.

  • Per conoscere le limitazioni generali, vedi limitazioni.
  • Per ulteriori informazioni sui database in dialetto PostgreSQL, ad esempio i requisiti di Liquibase, i tipi di modifiche supportati e le limitazioni, consulta PGAdapter e Liquibase.

Installa Liquibase

Per utilizzare Liquibase con i database in dialetto Google SQL, devi installare l'estensione Liquibase di Spanner. Per i database in dialetto PostgreSQL, Liquibase può utilizzare il proprio supporto PostgreSQL integrato in combinazione con PGAdapter.

GoogleSQL

  1. Segui le istruzioni riportate nella documentazione di Liquibase per installare e configurare Liquibase e acquisire uno snapshot del database. Nel file di configurazione liquibase.properties, imposta la proprietà url come segue.
 jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE
 
Your `liquibase.properties` configuration file can contain only this
property. Other properties are optional.

  1. Vai alla pagina delle release dell'estensione Liquibase di Spanner su GitHub e seleziona l'ultima release.

  2. Seleziona e scarica il file JAR con il nome liquibase-spanner-x.y.z-all.jar, dove x.y.z rappresenta il numero di versione dell'estensione. Ad esempio, liquibase-spanner-4.17.0-all.jar.

  3. Inserisci il file JAR scaricato nella directory lib di Liquibase. Il file JAR include l'estensione, l'SDK Spanner e il driver JDBC Spanner.

PostgreSQL

  1. Assicurati che PGAdapter sia avviato ed eseguito sulla macchina su cui installi Liquibase. Per ulteriori informazioni, consulta Avvia PGAdapter.

  2. Segui le istruzioni riportate nella documentazione di Liquibase per installare e configurare Liquibase e acquisire uno snapshot del database.

Nel file di configurazione liquibase.properties, imposta la proprietà url come segue.

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

Il file di configurazione liquibase.properties può contenere solo questa proprietà. Le altre proprietà sono facoltative.

La stringa url deve includere options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction perché Spanner non supporta le transazioni DDL e questo garantisce che le transazioni DDL vengano convertite in batch DDL. Per ulteriori informazioni, consulta Opzioni DDL per PGAdapter.

Esamina gli esempi di Liquibase

GoogleSQL

Il file di log delle modifiche di esempio changelog.yaml incluso con l'estensione Liquibase di GoogleSQL mostra molte delle funzionalità di Liquibase e come utilizzarle con Spanner.

PostgreSQL

Il file di log delle modifiche di esempio dbchangelog.xml disponibile nel repository GitHub di PGAdapter e Liquibase dimostra molte delle funzionalità di Liquibase e come utilizzarle con Spanner.

Guida rapida di Liquibase

Questa guida rapida mostra come utilizzare Liquibase per aggiungere una tabella Singers a un database.

Prima di iniziare

  • Assicurati di aver completato i passaggi precedenti per installare Liquibase.

  • Crea un'istanza di Spanner.

  • Crea un database con il dialetto Google SQL o PostgreSQL.

  • Solo per i database in dialetto PostgreSQL, assicurati che PGAdapter sia avviato e in esecuzione sulla stessa macchina dell'installazione di Liquibase. Per ulteriori informazioni, consulta Avvia PGAdapter.

  • Solo per i database in dialetto PostgreSQL, utilizza lo script create_database_change_log.sql per creare le tabelle di metadati databasechangeloglock e databasechangelog. Devi creare queste tabelle per sostituire quelle create automaticamente da Liquibase nel tuo database. Questo serve ad assicurarti che in queste tabelle vengano utilizzati i tipi di dati PostgreSQL corretti per Spanner.

    Puoi eseguire lo script con il seguente comando:

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

  • Concedi all'estensione Liquibase di Spanner l'utilizzo temporaneo delle tue credenziali utente Spanner per l'accesso all'API eseguendo il seguente comando gcloud:

    gcloud auth application-default login

Crea un file changelog.yaml

  1. Inserisci il seguente codice YAML nel tuo editor preferito.

    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)

    Questo file YAML definisce una tabella denominata Singers con una chiave primaria SingerId e una colonna denominata Name per memorizzare il nome del cantante.

    Per i database in dialetto PostgreSQL, consigliamo di utilizzare solo lettere minuscole per i nomi di tabelle e colonne. Per ulteriori informazioni, consulta la sezione sulla sensibilità alle maiuscole di PostgreSQL.

    Tieni presente che il set di modifiche createTable deve includere una limitazione della chiave principale e il nome della limitazione della chiave principale deve essere pk_table_name.

  2. Salva le modifiche come changelog.yaml.

Esegui Liquibase

Applica il set di modifiche in changelog.yaml eseguendo il seguente comando:

liquibase --changeLogFile changelog.yaml update

Liquibase utilizza l'URL definito nel file liquibase.properties. Puoi sovrascrivere il valore nel file aggiungendo il seguente argomento al comando precedente:

--url URL

Verificare le modifiche

Gli aggiornamenti nel passaggio precedente hanno causato l'aggiunta della tabella Singer al database. Inoltre, le tabelle DATABASECHANGELOG e DATABASECHANGELOGLOCK sono state aggiunte (database in dialetto GoogleSQL) o aggiornate (database in dialetto PostgreSQL).

Puoi verificare l'esistenza di queste tabelle tramite la console Google Cloud o gcloud CLI. Ad esempio, l'esecuzione della query SQL SELECT * FROM INFORMATION_SCHEMA.TABLES restituisce un elenco di tutte le tabelle del database.

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

Puoi visualizzare un record delle modifiche applicate eseguendo una query sui contenuti di DATABASECHANGELOG.

Passaggi successivi