Integrare Spanner con Liquibase

Questa pagina descrive come gestire le modifiche allo schema del database Spanner con Liquibase.

Liquibase è una libreria open source indipendente da database per il monitoraggio, la gestione e l'applicazione di modifiche allo schema dei database. Supporta SQL e i formati dichiarativi come XML, YAML e JSON.

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

  • Per visualizzare le limitazioni generali, vedi le limitazioni.
  • Per ulteriori informazioni sui database di dialetti PostgreSQL, come i requisiti di Liquibase, i tipi di modifica supportati e le limitazioni, consulta PGAdapter e Liquibase.

Installa Liquibase

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

GoogleSQL

  1. Segui le istruzioni nella documentazione di Liquibase per installare e configurare Liquibase e acquisire uno snapshot del tuo database. Nel file di configurazione liquibase.properties, imposta la proprietà url come segue.

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

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

  2. Vai alla pagina delle release dell'estensione Spanner Liquibase su GitHub e seleziona la release più recente.

  3. 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.

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

PostgreSQL

  1. Assicurati che PGAdapter sia avviato e in esecuzione sulla macchina in cui installerai Liquibase. Per maggiori informazioni, consulta Avviare PGAdapter.

  2. Segui le istruzioni nella documentazione di Liquibase per installare e configurare Liquibase e acquisire uno snapshot del tuo 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 assicura che le transazioni DDL vengano convertite automaticamente in batch DDL. Per ulteriori informazioni, consulta la sezione Opzioni DDL per PGAdapter.

Esamina i campioni di Liquibase

GoogleSQL

Il file di log delle modifiche di esempio changelog.yaml incluso nell'estensione GoogleSQL Liquibase dimostra 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 PGAdapter e Liquibase mostra 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.

  • Creare un'istanza di Spanner.

  • Crea un database con dialetti GoogleSQL o dialetti PostgreSQL.

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

  • Solo per i database di dialetti PostgreSQL, crea le tabelle di metadati databasechangeloglock e databasechangelog utilizzando lo script create_database_change_log.sql. Devi creare queste tabelle per eseguire l'override delle tabelle create automaticamente da Liquibase nel tuo database. Questo serve a garantire 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

  • Consenti all'estensione Spanner Liquibase l'utilizzo temporaneo delle tue credenziali utente Spanner per l'accesso API eseguendo questo comando gcloud:

    gcloud auth application-default login

Crea un changelog.yaml

  1. Inserisci il seguente 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 YAML definisce una tabella denominata Singers con una chiave primaria SingerId e una colonna denominata Name in cui memorizzare il nome del cantante.

    Per i database di dialetti PostgreSQL, consigliamo di utilizzare tutte lettere minuscole per i nomi di tabelle e colonne. Per maggiori informazioni, consulta Distinzione tra maiuscole e minuscole di PostgreSQL.

    Tieni presente che il set di modifiche createTable deve includere un vincolo di chiave primaria e il nome del vincolo di chiave primaria deve essere pk_table_name.

  2. Salva le modifiche come changelog.yaml.

Esegui Liquibase

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

liquibase --changeLogFile changelog.yaml update

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

--url URL

Verifica le modifiche

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

Puoi verificare l'esistenza di queste tabelle tramite la console Google Cloud o gcloud CLI. Ad esempio, la 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