Integrare Spanner con Liquibase

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

Liquibase è una libreria open source indipendente dal database per monitorare, gestire e applicare modifiche allo schema del database. Supporta SQL e 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 conoscere le limitazioni generali, consulta le limitazioni.
Per ulteriori informazioni per i 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 dialetti GoogleSQL, devi installare l'estensione Spanner Liquibase. Per i database dialetti PostgreSQL, Liquibase può utilizzare il supporto PostgreSQL integrato in combinazione con PGAdapter.

GoogleSQL

Segui le istruzioni nella documentazione di Liquibase per installare e configurare Liquibase e per creare 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.
Vai alla pagina delle release dell'estensione Liquibase di Spanner su GitHub e seleziona la release più recente.
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.
Inserisci il file JAR scaricato nella directory Liquibase lib. Il file JAR include l'estensione, l'SDK Spanner e il driver del driver JDBC di Spanner.

PostgreSQL

Assicurati che PGAdapter sia avviato e in esecuzione sulla macchina su cui installerai Liquibase. Per maggiori informazioni, consulta la sezione Avviare PGAdapter.
Segui le istruzioni nella documentazione di Liquibase per installare e configurare Liquibase e per creare 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 poiché Spanner non supporta le transazioni DDL, garantendo che le transazioni DDL vengano automaticamente convertite in batch DDL. Per saperne di più, 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 GoogleSQL Liquibase 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 mostra molte delle funzionalità di Liquibase e come utilizzarle con Spanner.

Guida rapida di Liquibase

Questa guida rapida illustra 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 Spanner.
Crea un database di dialetti GoogleSQL o PostgreSQL.
Solo per i database dialetto PostgreSQL, assicurati che PGAdapter sia avviato e in esecuzione sulla stessa macchina dell'installazione di Liquibase. Per maggiori informazioni, consulta la sezione Avviare PGAdapter.
Solo per i database PostgreSQL dialetto, 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 che Liquibase crea automaticamente 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 comando seguente:
```
psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql
```
Per concedere all'estensione Spanner Liquibase l'utilizzo temporaneo delle tue credenziali utente di Spanner per l'accesso all'API, esegui questo comando gcloud:
```
gcloud auth application-default login
```

Creare un file changelog.yaml

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 YAML definisce una tabella denominata Singers con una chiave primaria SingerId e una colonna denominata Name per archiviare il nome del cantante.

Per i database dialetti PostgreSQL, consigliamo di utilizzare solo lettere minuscole per i nomi delle tabelle e delle colonne. Per maggiori informazioni, consulta Sensibilità alle maiuscole di PostgreSQL.

Tieni presente che il set di modifica createTable deve includere un vincolo di chiave primaria e il nome del vincolo di chiave primaria deve essere pk_table_name.
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 che hai definito nel file liquibase.properties. Puoi eseguire l'override del 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, sono state aggiunte o aggiornate le tabelle DATABASECHANGELOG e DATABASECHANGELOGLOCK (database dialetto SQL di Google) o aggiornate (database 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

Per ulteriore documentazione, visita il repository GitHub Spanner Liquibase Extensions.
Per ulteriori informazioni su Liquibase, consulta la Guida introduttiva a Liquibase.