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 di test, per isolare i dati dei clienti e per la regionalizzazione dei dati.

Ruoli e autorizzazioni richiesti

Per creare e gestire i database, devi disporre del seguente ruolo Identity and Access Management:

• Cloud Datastore Owner (roles/datastore.owner)

Questo ruolo concede le seguenti autorizzazioni necessarie per creare e gestire i database:

• Crea un database: datastore.databases.create
• Configurazione del database di lettura: 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, utilizza uno dei seguenti metodi:

firebase firestore:databases:create DATABASE_ID \n--location=LOCATION \n[--edition EDITION] \n[--firestore-data-access FIRESTORE_ACCESS] \n[--realtime-updates REALTIME_UPDATES] \n[--delete-protection DELETE_PROTECTION_ENABLEMENT]

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

  // Optional
  delete_protection_state = DELETE_PROTECTION_STATE
}

ID database

Un ID database valido deve essere conforme alle seguenti regole:

• Includi 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.
• Almeno 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.

Esiste un'eccezione a queste regole: la versione Standard creerà un database denominato (default) se non inserisci un ID.

Tieni presente che, dopo aver eliminato un database, non puoi riutilizzarne l'ID per circa 5 minuti.

Elimina protezione

Utilizza la protezione da eliminazione per evitare 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 aggiornare la configurazione del database per attivare o disattivare la protezione da eliminazione.

Configura Cloud Firestore Security Rules per i tuoi database

Utilizza l'interfaccia a riga di comando Firebase per eseguire il deployment di Cloud Firestore Security Rules in ciascuno dei tuoi database. Consulta la guida alla gestione e al deployment 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 delle API di Google si connettono al database Cloud Firestore (default) in un progetto. Per creare un client connesso a un database denominato, imposta l'ID del database quando crei un'istanza di un client.

Elenco database

Utilizza uno dei seguenti metodi per elencare i tuoi database:

gcloud firestore databases list

firebase firestore:databases:list

Visualizza dettagli database

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

gcloud firestore databases describe --database=DATABASE_ID

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, utilizza 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 abilitare la protezione da eliminazione su un database, utilizza il comando gcloud firestore databases update con il flag --delete-protection. Ad esempio:

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

Sostituisci DATABASE_ID con un ID database.

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

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

Sostituisci DATABASE_ID con un ID database.

Elimina un database

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

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

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

L'eliminazione di un database non comporta l'eliminazione automatica di eventuali triggerEventarc per quel database. Il trigger smette di inviare eventi, ma continua a esistere finché non lo elimini.

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

gcloud firestore databases delete --database=DATABASE_ID

Clona un database

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

• Il database clonato è un nuovo database che verrà creato nella stessa località 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 momento nel passato, nel periodo definito dalla finestra PITR:

  • Se il PITR è abilitato per il tuo database, seleziona un minuto qualsiasi 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 nell'ultima ora.
  • Puoi controllare il timestamp più recente che puoi scegliere nella descrizione del tuo database.

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

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

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

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'

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

Configura le autorizzazioni di accesso per database

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

Visualizza le policy IAM esistenti

gcloud projects get-iam-policy PROJECT_ID

Imposta PROJECT_ID sull'ID progetto.

Concedi 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 un Account Google specifico. Ad esempio, alice@example.com.
• DATABASE_ID: un ID database.
• TITLE: un titolo facoltativo per l'espressione.
• DESCRIPTION: una descrizione facoltativa dell'espressione.

Concedi 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 un Account Google specifico. Ad esempio, alice@example.com.
• DATABASE_ID: un ID database.
• TITLE: un titolo facoltativo per l'espressione.
• DESCRIPTION: una descrizione facoltativa dell'espressione.

Rimuovi le policy per un membro e un ruolo specifici

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 un Account Google specifico. Ad esempio, alice@example.com.

Cloud Monitoring

Le metriche Cloud Firestore vengono riportate in due risorse monitorate.

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

Puoi ispezionare le metriche aggregate a livello di database esaminando firestore.googleapis.com/Database. Le metriche riportate in firestore_instance sono 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 di eliminazione dell'indice per eliminare i dati di ricerca di GAE. Se di recente hai eliminato i dati di GAE Search, potrebbe essere necessario un periodo di attesa prima di poter eliminare il database.
• Non puoi eliminare il tuo database (default) se contiene entità blob. Utilizza l'API di eliminazione di Blobstore per eliminare i dati di Blobstore. Puoi verificare se il tuo database (default) contiene dati Blobstore eseguendo la seguente query GQL nella console Google Cloud: SELECT * FROM __BlobInfo__.
• Non puoi riutilizzare un ID database fino a 5 minuti dopo l'eliminazione.
• Cloud Functions (1ª gen.) non supporta i database denominati Firestore. Utilizza i trigger di Cloud Firestore (2ª gen.) per configurare gli eventi per i database denominati.
• I trigger di funzioni Firestore v1 e i trigger di eventi Firestore potrebbero smettere di funzionare dopo l'eliminazione del database, anche se viene creato un nuovo database con lo stesso nome.

Passaggi successivi

• Aggiungi dati
• Recupera i dati
• Elimina i dati