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 delle modifiche allo schema del database. Supporta SQL e le richieste 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, vedi limitazioni.
  • Per ulteriori informazioni sui database di dialetti PostgreSQL, ad esempio i requisiti di Liquibase, i tipi di modifica supportati e le limitazioni, consulta PGAdapter e Liquibase.

Installa Liquibase

Per utilizzare Liquibase con i database di dialetti GoogleSQL, devi installare Estensione Spanner Liquibase. Per i database di dialetti PostgreSQL, Liquibase può utilizzare il supporto integrato di PostgreSQL, PGAdapter.

GoogleSQL

  1. Segui le istruzioni 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 .

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

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

  2. Accedi a Spanner Liquibase la pagina delle release delle estensioni su GitHub e seleziona l'ultima release.

  3. Seleziona e scarica il file JAR con il nome liquibase-spanner-x.y.z-all.jar, dove x.y.z rappresenta la versione dell'estensione numero. 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 conducente.

PostgreSQL

  1. Assicurati che PGAdapter sia avviato e in esecuzione sulla macchina in cui installerai 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 questo 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 automaticamente in batch DDL. Per ulteriori informazioni, consulta Opzioni DDL per PGAdapter.

Esamina i campioni di Liquibase

GoogleSQL

Il file di log delle modifiche di esempio changelog.yaml incluso nella L'estensione GoogleSQL Liquibase dimostra molte delle funzionalità Liquibase e come utilizzarlo con Spanner.

PostgreSQL

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

Guida rapida di Liquibase

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

Prima di iniziare

  • Assicurati di aver completato i passaggi precedenti per l'installazione. Liquibase.

  • Creare un'istanza di Spanner.

  • Crea un database con dialetti GoogleSQL o dialetti PostgreSQL.

  • Solo per database con dialetti 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 di dialetti PostgreSQL, crea databasechangeloglock e databasechangelog tabelle di metadati utilizzando create_database_change_log.sql. Devi creare queste tabelle esegue l'override delle tabelle create automaticamente da Liquibase nel tuo database. Questo serve a garantire che i tipi di dati PostgreSQL corretti per In queste tabelle viene utilizzato Spanner.

    Puoi eseguire lo script con il seguente comando:

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

  • Concedi all'estensione Spanner Liquibase l'utilizzo temporaneo del tuo Credenziali utente Spanner per l'accesso all'API eseguendo questo comando 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 un Name per memorizzare il nome del cantante.

    Per i database di dialetti PostgreSQL, consigliamo di utilizzare tutte lettere minuscole per tabelle e colonne i nomi degli utenti. Per ulteriori informazioni, vedi 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 eseguire l'override del 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 tuo per configurare un database. Inoltre, le tabelle DATABASECHANGELOG e DATABASECHANGELOGLOCK sono state aggiunto (database di dialetti GoogleSQL) o aggiornato (database di dialetti PostgreSQL).

Puoi verificare l'esistenza di queste tabelle tramite la console Google Cloud con 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