Gestire i database

Questa pagina descrive come creare, aggiornare ed eliminare i database Cloud Firestore. Puoi creare più database Cloud Firestore per progetto. Puoi utilizzare più database per configurare ambienti di produzione e test, per isolare i dati dei clienti e per la regionalizzazione dei dati.

Il database (default)

Se non specifichi un database, le librerie client Cloud Firestore e Google Cloud CLI si connettono al database (default) per impostazione predefinita.

Ruoli obbligatori

Per creare e gestire i database, devi disporre del ruolo Identity and Access Management Owner o Datastore Owner. Questi ruoli concedono le autorizzazioni richieste.

Autorizzazioni obbligatorie

Per gestire i database, devi disporre delle seguenti autorizzazioni:

• Crea un database: datastore.databases.create
• Leggi la configurazione del database: datastore.databases.getMetadata
• Configura un database: datastore.databases.update
• Elimina un database: datastore.databases.delete
• Clona un database: datastore.databases.clone

Crea un database

Per creare un database, utilizzare uno dei seguenti metodi:

Console

1. Nella console Firebase, vai alla pagina Database Firestore.

   Vai al database Firestore

2. Se questo è il tuo primo database denominato, fai clic su Aggiungi database.
3. Altrimenti, fai clic su (predefinito), quindi su Aggiungi database.
4. Configura il tuo database. Inserisci un ID database. Seleziona una località. Fai clic su Crea database.

gcloud

Utilizzare il comando gcloud firestore databases create.

gcloud firestore databases create \
--database=DATABASE_ID \
--location=LOCATION \
--type=DATABASE_TYPE \
[--delete-protection]

Sostituisci quanto segue:

• DATABASE_ID: un ID database valido.
• LOCATION: il nome di una regione o di una multiregione Cloud Firestore.
• DATABASE_TYPE: firestore-native per la modalità nativa o datastore-mode per la modalità Datastore.

--delete-protection è un flag facoltativo per abilitare la protezione dall'eliminazione. Non puoi eliminare un database con la protezione da eliminazione abilitata finché non disattivi questa impostazione. Questa impostazione è disattivata per impostazione predefinita.

Per aggiungere tag al database, utilizzare il flag --tags. Ad esempio:

• --tags=123/environment=production,123/costCenter=marketing
• --tags=tagKeys/333=tagValues/444

Interfaccia a riga di comando di Firebase

firebase firestore:databases:create DATABASE_ID \
--location=LOCATION \
[--delete-protection DELETE_PROTECTION_ENABLEMENT]

Sostituisci quanto segue:

• DATABASE_ID: un ID database valido.
• LOCATION: il nome di una regione o di una multiregione Cloud Firestore.
• DELETE_PROTECTION_ENABLEMENT: ENABLED o DISABLED.
Il database creato è sempre in modalità Firestore Native.

--delete-protection è un argomento facoltativo per abilitare la protezione da eliminazione. Non è possibile eliminare un database con la protezione da eliminazione abilitata finché non si disabilita questa impostazione. Questa impostazione è disattivata per impostazione predefinita.

Terraform

resource "google_firestore_database" "database" {
  project     = "project-id"
  name        = DATABASE_ID
  location_id = LOCATION
  type        = DATABASE_TYPE

  // Optional
  delete_protection_state = DELETE_PROTECTION_STATE
}

Sostituisci quanto segue:

• DATABASE_ID: un ID database valido.
• LOCATION: il nome di una Cloud Firestore multi-regione o regione.
• DATABASE_TYPE: FIRESTORE_NATIVE per la modalità nativa o DATASTORE_MODE per la modalità Datastore.
• DELETE_PROTECTION_ENABLEMENT: DELETE_PROTECTION_ENABLED o DELETE_PROTECTION_DISABLED.

delete_protection_state è un argomento facoltativo per abilitare la protezione da eliminazione. Non puoi eliminare un database con la protezione da eliminazione abilitata finché non disattivi questa impostazione. Questa impostazione è disattivata per impostazione predefinita.

ID database

Gli ID di database validi includono (default) e gli ID conformi a quanto segue:

• Include solo lettere, numeri e trattini (-).
• Le lettere devono essere minuscole.
• Il primo carattere deve essere una lettera.
• L'ultimo carattere deve essere una lettera o un numero.
• Minimo 4 caratteri.
• Massimo 63 caratteri.
• Non deve essere un UUID o assomigliare a un UUID. Ad esempio, non utilizzare un ID come f47ac10b-58cc-0372-8567-0e02b2c3d479.

Se elimini un database, non puoi riutilizzare immediatamente l'ID database finché non sono trascorsi 5 minuti.

Elimina protezione

Utilizzare la protezione contro l'eliminazione per impedire l'eliminazione accidentale di un database. Non puoi eliminare un database con la protezione da eliminazione abilitata finché non la disabiliti. La protezione da eliminazione è disattivata per impostazione predefinita. Puoi attivare la protezione da eliminazione quando crei il database oppure puoi aggiornare una configurazione del database per attivare la protezione da eliminazione.

Imposta Cloud Firestore Security Rules per i tuoi database

Utilizza la CLI Firebase per distribuire Cloud Firestore Security Rules su ciascuno dei tuoi database. Consulta la guida per la gestione e la distribuzione di Cloud Firestore Security Rules.

Accedi a un database denominato con una libreria client

Un database denominato include qualsiasi database non denominato (default). Per impostazione predefinita, gli SDK Firebase e le librerie client API di Google si connettono al database (default) Cloud Firestore in un progetto. Per creare un client connesso a un database denominato, imposta l'ID database quando crei un'istanza di un client.

Nota :per lavorare con più database, assicurati di eseguire l'aggiornamento agli SDK client Firebase e alle librerie client delle API di Google più recenti.

Elenco database

Utilizza uno dei seguenti metodi per elencare i database:

Console

Nella console di Google Cloud, vai alla pagina Database.

Vai a Database

Nota: puoi visualizzare ed elencare i tuoi database nella console di Google Cloud. Puoi creare il database (default) utilizzando la console Google Cloud, ma devi utilizzare Google Cloud CLI o un altro metodo per creare un database denominato. Per eliminare un database utilizza Google Cloud CLI.

gcloud

Utilizza il comando gcloud firestore databases list per elencare tutti i database nel tuo progetto.

gcloud firestore databases list

Interfaccia a riga di comando di Firebase

Utilizzare il comando firebase firestore:databases:list per elencare tutti i database nel progetto.

firebase firestore:databases:list

Visualizzare i dettagli del database

Per visualizzare i dettagli di un singolo database, utilizza uno dei seguenti metodi:

gcloud

Utilizza il comando gcloud firestore databases describe:

gcloud firestore databases describe --database=DATABASE_ID

Interfaccia a riga di comando di Firebase

Utilizzare il comando firebase firestore:databases:get:

firebase firestore:databases:get DATABASE_ID

Sostituisci DATABASE_ID con un ID database.

Aggiorna la configurazione del database

Per aggiornare le impostazioni di configurazione di un database, utilizzare il comando gcloud firestore databases update. Utilizza questo comando per attivare o disattivare la protezione da eliminazione.

Aggiorna l'impostazione di protezione da eliminazione

Per attivare la protezione dall'eliminazione su un database, utilizza il comando gcloud firestore databases update con il flag --delete-protection. Ad esempio:

gcloud

gcloud firestore databases update --database=DATABASE_ID --delete-protection

Sostituisci DATABASE_ID con un ID database.

Per disattivare la protezione dall'eliminazione su un database, utilizza il comando gcloud firestore databases update con il flag --no-delete-protection. Ad esempio:

gcloud

gcloud firestore databases update --database=DATABASE_ID --no-delete-protection

Sostituisci DATABASE_ID con un ID database.

Eliminare un database

Per eliminare un database, utilizza la console o lo strumento a riga di comando.

Se per il database è abilitata l'impostazione di protezione da eliminazione, devi prima disabilitare la protezione da eliminazione.

Se il database contiene dati di ricercaApp Engine o entità blob, devi prima eliminare questi dati.

L'eliminazione di un database non comporta l'eliminazione automatica di eventuali Eventarc trigger� per quel database. Il trigger smette di fornire eventi ma continua a esistere finché non elimini il trigger.

L'eliminazione di un database non comporta addebiti per le operazioni di eliminazione.

Console

1. Nella console Firebase, vai alla pagina Database Firestore.

   Vai al database Firestore

2. Nella scheda Dati, sopra la visualizzazione della tabella dei dati per il database, fai clic su , quindi seleziona Elimina database.
3. Seguire le istruzioni per eliminare il database.

gcloud

Utilizza il comando `gcloud firestore databases delete`.

gcloud firestore databases delete --database=DATABASE_ID

Sostituisci DATABASE_ID con l'ID del database da eliminare. Per eliminare il database predefinito, utilizza l'ID '(default)'.

Clona un database

Puoi clonare un database esistente in un nuovo database in un timestamp selezionato:

• Il database clonato è un nuovo database che verrà creato nella stessa posizione del database di origine.

  Per creare un clone, Cloud Firestore utilizza i dati di recupero point-in-time (PITR) del database di origine. Il database clonato include tutti i dati e gli indici.

• Per impostazione predefinita, il database clonato verrà criptato nello stesso modo del database di origine, utilizzando la crittografia predefinita di Google o la crittografia CMEK. Puoi specificare un tipo di crittografia diverso o utilizzare una chiave diversa per la crittografia CMEK.

• Il timestamp ha una granularità di un minuto e specifica un punto nel tempo nel passato, nel periodo definito dalla finestra PITR:

  • Se il PITR è abilitato per il tuo database, puoi selezionare qualsiasi minuto degli ultimi 7 giorni (o meno se il PITR è stato abilitato meno di 7 giorni fa).
  • Se il PITR non è abilitato, puoi selezionare un minuto qualsiasi dell'ultima ora.
  • Puoi controllare il timestamp meno recente che puoi scegliere nella descrizione del database.

Nota: per clonare i database, il tuo Account Google deve disporre dell'autorizzazione IAM datastore.databases.clone.

Console

La console Firebase non supporta la clonazione del database. Per clonare i database è possibile utilizzare le istruzioni di Google Cloud CLI.

gcloud

Utilizza il comando gcloud firestore databases clone per clonare un database:

gcloud firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'

Sostituisci quanto segue:

• SOURCE_DATABASE: il nome del database di un database esistente che vuoi clonare. Il nome utilizza il formato projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

• PITR_TIMESTAMP: un timestamp PITR nel formato RFC 3339, con granularità al minuto. Ad esempio: 2025-06-01T10:20:00.00Z o 2025-06-01T10:30:00.00-07:00.

• DESTINATION_DATABASE_ID: un ID database per un nuovo database clonato. Questo ID database non deve essere associato a un database esistente.

Esempio:

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

Se vuoi eseguire il binding di alcuni tag durante la clonazione di un database, utilizza il comando precedente con il flag --tags, che è un elenco facoltativo di coppie KEY=VALUE di tag da associare.

Esempio:

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

Per impostazione predefinita, il database clonato avrà la stessa configurazione di crittografia del database di origine. Per modificare la configurazione della crittografia, utilizza l'argomento --encryption-type:

• (Predefinito) use-source-encryption: utilizza la stessa configurazione di crittografia del database di origine.
• google-default-encryption: utilizza la crittografia predefinita di Google.
• customer-managed-encryption: utilizza la crittografia CMEK. Specifica un ID chiave nell'argomento --kms-key-name.

L'esempio seguente mostra come configurare la crittografia CMEK per il database clonato:

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

Interfaccia a riga di comando di Firebase

Utilizza il comando firebase firestore:databases:clone per clonare un database:

firebase firestore:databases:clone \
'SOURCE_DATABASE' \
'DESTINATION_DATABASE' \
--snapshot-time 'PITR_TIMESTAMP'

Sostituisci quanto segue:

• SOURCE_DATABASE: il nome del database di un database esistente che vuoi clonare. Il nome utilizza il formato projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

• DESTINATION_DATABASE: un nome di database per un nuovo database clonato. Il nome utilizza il formato projects/PROJECT_ID/databases/DESTINATION_DATABASE_ID. Il nome del database non deve essere associato a un database esistente.

• PITR_TIMESTAMP: un timestamp PITR nel formato RFC 3339, con granularità al minuto. Ad esempio: 2025-06-01T10:20:00.00Z o 2025-06-01T10:30:00.00-07:00. Se non specificato, l'istantanea scelta sarà l'ora corrente, arrotondata al minuto.

Per impostazione predefinita, il database clonato avrà la stessa configurazione di crittografia del database di origine. Per modificare la configurazione della crittografia, utilizza l'argomento --encryption-type:

• (Predefinito) USE_SOURCE_ENCRYPTION: utilizza la stessa configurazione di crittografia del database di origine.
• GOOGLE_DEFAULT_ENCRYPTION: utilizza la crittografia predefinita di Google.
• CUSTOMER_MANAGED_ENCRYPTION: utilizza la crittografia CMEK. Specifica un ID chiave nell'argomento --kms-key-name.

Configurare le autorizzazioni di accesso per database

Puoi utilizzare le condizioni di Identity and Access Management per configurare le autorizzazioni di accesso a livello di database. Gli esempi riportati di seguito utilizzano Google Cloud CLI per assegnare l'accesso condizionale a uno o più database. Puoi anche definire le condizioni IAM nella console Google Cloud.

Avviso: la console Google Cloud non consente/nega l'accesso ai database in base alle condizioni IAM configurate a livello di database. Questo vale solo per l'accesso ai database tramite la console Google Cloud. Le condizioni IAM vengono applicate quando si accede ai database al di fuori della console Google Cloud, ad esempio con l'API REST o le librerie client.

Visualizza le policy IAM esistenti

gcloud projects get-iam-policy PROJECT_ID

Imposta PROJECT_ID sull'ID progetto.

Concedere l'accesso a un database

gcloud projects add-iam-policy-binding PROJECT_ID \
--member='user:EMAIL' \
--role='roles/datastore.user' \
--condition='expression=resource.name=="projects/PROJECT_ID/databases/DATABASE_ID",title=TITLE,description=DESCRIPTION'

Imposta quanto segue:

• PROJECT_ID: il tuo ID progetto
• EMAIL: un indirizzo email che rappresenta uno specifico Account Google. Ad esempio, [e-mail].
• DATABASE_ID: un ID database.
• TITLE: un titolo facoltativo per l'espressione.
• DESCRIPTION: una descrizione facoltativa dell'espressione.

Concedere l'accesso a tutti i database tranne uno

gcloud projects add-iam-policy-binding PROJECT_ID \
--member='user:EMAIL' \
--role='roles/datastore.user' \
--condition='expression=resource.name!="projects/PROJECT_ID/databases/DATABASE_ID",title=TITLE,description=DESCRIPTION'

Imposta quanto segue:

• PROJECT_ID: il tuo ID progetto
• EMAIL: un indirizzo email che rappresenta uno specifico Account Google. Ad esempio, [e-mail].
• DATABASE_ID: un ID database.
• TITLE: un titolo facoltativo per l'espressione.
• DESCRIPTION: una descrizione facoltativa dell'espressione.

Rimuovere le policy per un determinato membro e ruolo

gcloud projects remove-iam-policy-binding PROJECT_ID \
--member='user:EMAIL' \
--role='roles/datastore.user' --all

Imposta quanto segue:

• PROJECT_ID: il tuo ID progetto
• EMAIL: un indirizzo email che rappresenta uno specifico Account Google. Ad esempio, [e-mail].

Cloud Monitoring

Le metriche Cloud Firestore vengono riportate in due risorse monitorate.

• firestore.googleapis.com/Database
• firestore_instance(precedente)

Puoi esaminare le metriche aggregate a livello di database esaminando firestore.googleapis.com/Database. Le metriche riportate in firestore_instance vengono aggregate a livello di progetto.

Limitazioni

• Puoi avere un massimo di 100 database per progetto. Puoi contattare l'assistenza per richiedere un aumento di questo limite.
• Non puoi eliminare il database (default) se contiene dati di ricerca GAE. Utilizza l'API Index Delete per eliminare i dati di ricerca di GAE. Se hai eliminato di recente i dati di GAE Search, potrebbe essere necessario attendere un periodo di attesa prima di poter eliminare il database.
• Non puoi eliminare il database (default) se contiene entità blob. Utilizza l'API di eliminazione Blobstore per eliminare i dati Blobstore. Puoi verificare se il tuo database (default) contiene dati Blobstore eseguendo la seguente query GQL nella console Google Cloud: SELECT * FROM __BlobInfo__.
• Non è possibile riutilizzare un ID database prima che siano trascorsi 5 minuti dall'eliminazione.
• Cloud Functions v1 non supporta i database denominati Firestore. Utilizza Cloud Firestore Triggers (2a generazione) per configurare eventi per database denominati.
• I trigger della funzione Firestore v1 e i trigger degli eventi Firestore potrebbero smettere di funzionare dopo l'eliminazione del database, anche se viene creato un nuovo database con lo stesso nome.

Passaggi successivi

• Aggiungere dati
• Recuperare i dati
• Eliminare i dati