Exporter et importer à l'aide de fichiers CSV

Cette page décrit l'exportation et l'importation de données dans des instances Cloud SQL à l'aide de fichiers CSV.

Avant de commencer

Avant de lancer une opération d'exportation ou d'importation, procédez comme suit :

  • Assurez-vous que votre base de données dispose d'un espace de stockage suffisant.
  • Les opérations d'exportation et d'importation utilisent des ressources de base de données, mais elles n'interfèrent pas avec les opérations de base de données normales, sauf si l'instance est sous-provisionnée.

  • Vérifiez que le fichier CSV contient les données attendues et qu'il est au bon format. Les fichiers CSV doivent comporter une ligne par rangée de champs de données.
  • Suivez les bonnes pratiques pour l'exportation et l'importation de données.

Exporter

Rôles et autorisations requis pour l'exportation

Pour exporter des données vers Cloud Storage, le compte de service ou l'utilisateur doit disposer de l'un des rôles suivants :

  • Rôle Éditeur Cloud SQL Editor et rôle IAM roles/storage.legacyBucketWriter.
  • Rôle personnalisé comprenant les autorisations suivantes :
    • cloudsql.instances.get
    • cloudsql.instances.export
    • storage.buckets.create
    • storage.objects.create

Si le compte de service ou l'utilisateur effectuent également des opérations d'importation, il peut être plus pratique d'accorder le rôle IAM Storage Object Admin pour disposer de toutes les autorisations requises pour l'importation et l'exportation.

Pour obtenir de l'aide sur les rôles IAM, consultez la page Cloud Identity and Access Management pour Cloud Storage.

Exporter des données vers un fichier CSV

Vous pouvez exporter vos données au format CSV, qui peut être utilisé par d'autres outils et environnements. Les exportations ont lieu au niveau de la base de données. Lors d'une exportation au format CSV, vous pouvez spécifier les schémas à exporter. Tout schéma situé au niveau de la base de données peut être exporté.

Pour exporter des données d'une base de données sur une instance Cloud SQL vers un fichier CSV dans un bucket Cloud Storage, procédez comme suit :

Console

  1. Dans Google Cloud Console, accédez à la page Instances Cloud SQL.

    Accéder à la page Instances Cloud SQL

  2. Cliquez sur le nom de l'instance pour ouvrir la page Présentation.
  3. Cliquez sur Exporter.
  4. Sélectionnez Décharger l'exportation pour autoriser d'autres opérations pendant l'exportation.
  5. Dans la section Emplacement de l'exportation dans Cloud Storage, ajoutez le nom du bucket, du dossier et du fichier que vous souhaitez exporter, ou cliquez sur Parcourir pour rechercher ou créer un bucket, un dossier ou un fichier.

    Si vous cliquez sur Parcourir :

    1. Dans la section Emplacement, sélectionnez un bucket ou un dossier Cloud Storage pour votre exportation.
    2. Dans la zone Nom, saisissez un nom pour le fichier CSV ou sélectionnez un fichier existant dans la liste de la section Emplacement.

      Vous pouvez utiliser une extension de fichier .gz (l'extension complète est .csv.gz) pour compresser votre fichier d'exportation.

    3. Cliquez sur Select (Sélectionner).
  6. Dans la section Format, cliquez sur CSV.
  7. Dans la section Base de données pour l'exportation, sélectionnez le nom de la base de données dans le menu déroulant.
  8. Sous Requête SQL, saisissez une requête SQL pour spécifier la table à partir de laquelle exporter les données.

    Par exemple, pour exporter l'intégralité du contenu de la table entries de la base de données guestbook, vous devez saisir :

    SELECT * FROM guestbook.entries;
    Votre requête doit spécifier une table de la base de données spécifiée. Vous ne pouvez pas exporter une base de données entière au format CSV.
  9. Cliquez sur Exporter pour démarrer l'exportation.
  10. La boîte de dialogue Exporter la base de données ? s'ouvre avec un message indiquant que le processus d'exportation peut prendre une heure ou plus pour les bases de données volumineuses. Pendant l'exportation, la seule opération que vous pouvez effectuer sur l'instance est d'afficher ses informations. Vous ne pouvez pas arrêter l'exportation une fois celle-ci démarrée. Si vous souhaitez lancer une exportation, cliquez sur Exporter. Sinon, cliquez sur Annuler.

gcloud

  1. Créer un bucket Cloud Storage
  2. Importez le fichier dans le bucket.

    Pour obtenir de l'aide concernant l'importation de fichiers dans des buckets, consultez la page Importer des objets.

  3. Recherchez le compte de service pour l'instance Cloud SQL à partir de laquelle vous souhaitez exporter. Pour ce faire, exécutez la commande gcloud sql instances describe. Recherchez le champ serviceAccountEmailAddress dans le résultat.
    gcloud sql instances describe INSTANCE_NAME
    
  4. Utilisez gsutil iam pour accorder le rôle IAM storage.objectAdmin au compte de service. Pour obtenir de l'aide sur la définition des autorisations IAM, consultez la page Utiliser des autorisations IAM.
  5. Exportez la base de données :
    gcloud sql export csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
    --database=DATABASE_NAME \
    --offload \
    --query=SELECT_QUERY
    

    Pour plus d'informations sur l'utilisation de la commande export csv, consultez la page de référence de la commande sql export csv.

  6. Si vous n'avez pas besoin de conserver le rôle IAM que vous avez défini précédemment, révoquez-le maintenant.

REST v1

  1. Créez un bucket pour l'exportation de la manière suivante :
    gsutil mb -p PROJECT_NAME -l LOCATION_NAME gs://BUCKET_NAME
    

    Bien que cette étape soit facultative, nous vous recommandons de la suivre pour vous éviter d'ouvrir l'accès à d'autres données.

  2. Attribuez à votre instance le rôle IAM legacyBucketWriter pour votre bucket. Pour obtenir de l'aide sur la définition des autorisations IAM, consultez la page Utiliser des autorisations IAM.
  3. Exportez votre base de données :

    Avant d'utiliser les données de requête, effectuez les remplacements suivants :

    • project-id : ID du projet
    • instance-id : ID de l'instance
    • bucket_name : nom du bucket Cloud Storage
    • path_to_csv_file : chemin d'accès au fichier CSV
    • database_name : nom d'une base de données dans l'instance Cloud SQL
    • offload : active l'exportation sans serveur. Définissez la valeur sur true pour utiliser l'exportation sans serveur.
    • select_query : requête SQL pour l'exportation (facultatif).
    • escape_character : caractère qui doit précéder un caractère de données devant être échappé. La valeur de cet argument doit être un caractère en code ASCII hexadécimal. Par exemple, "22" représente les guillemets doubles. (facultatif)
    • quote_character : caractère englobant les valeurs des colonnes contenant un type de données de chaîne. La valeur de cet argument doit être un caractère en code ASCII hexadécimal. Par exemple, "22" représente les guillemets doubles. (facultatif)
    • fields_terminated_by : caractère scindant les valeurs de colonne. La valeur de cet argument doit être un caractère en code ASCII hexadécimal. Par exemple, "2C" représente une virgule. (facultatif)
    • lines_terminated_by : caractère qui divise les enregistrements de ligne. La valeur de cet argument doit être un caractère en code ASCII hexadécimal. Par exemple, "0A" représente une nouvelle ligne. (facultatif)

    Méthode HTTP et URL :

    POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id/export

    Corps JSON de la requête :

    {
     "exportContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "databases": ["database_name"],
          "offload": true | false
          "csvExportOptions":
           {
               "selectQuery":"select_query",
               "escapeCharacter":"escape_character",
               "quoteCharacter":"quote_character",
               "fieldsTerminatedBy":"fields_terminated_by",
               "linesTerminatedBy":"lines_terminated_by"
           }
       }
    }
    

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir une réponse JSON de ce type :

    Vous devez spécifier une seule base de données via la propriété databases, et si la requête "select" spécifie une base de données, celle-ci doit être identique.

  4. Si vous n'avez pas besoin de conserver les autorisations IAM que vous avez définies précédemment, supprimez-les dès maintenant.
Pour obtenir la liste complète des paramètres de cette requête, consultez la page instances:export.

REST v1beta4

  1. Créez un bucket pour l'exportation de la manière suivante :
    gsutil mb -p PROJECT_NAME -l LOCATION_NAME gs://BUCKET_NAME
    

    Bien que cette étape soit facultative, nous vous recommandons de la suivre pour vous éviter d'ouvrir l'accès à d'autres données.

  2. Attribuez à votre instance le rôle IAM storage.objectAdmin pour votre bucket. Pour obtenir de l'aide sur la définition des autorisations IAM, consultez la page Utiliser des autorisations IAM.
  3. Exportez votre base de données :

    Avant d'utiliser les données de requête, effectuez les remplacements suivants :

    • project-id : ID du projet
    • instance-id : ID de l'instance
    • bucket_name : nom du bucket Cloud Storage
    • path_to_csv_file : chemin d'accès au fichier CSV
    • database_name : nom d'une base de données dans l'instance Cloud SQL
    • offload : active l'exportation sans serveur. Définissez la valeur sur true pour utiliser l'exportation sans serveur.
    • select_query : requête SQL pour l'exportation (facultatif).
    • escape_character : caractère qui doit précéder un caractère de données devant être échappé. La valeur de cet argument doit être au format hexadécimal ASCII. Par exemple, "22" représente les guillemets doubles. (facultatif)
    • quote_character : caractère englobant les valeurs des colonnes contenant un type de données de chaîne. La valeur de cet argument doit être au format hexadécimal ASCII. Par exemple, "22" représente les guillemets doubles. (facultatif)
    • fields_terminated_by : caractère qui divise les valeurs de la colonne. La valeur de cet argument doit être au format hexadécimal ASCII. Par exemple, "2C" représente une virgule. (facultatif)
    • lines_terminated_by : caractère qui divise les enregistrements de ligne. La valeur de cet argument doit être au format hexadécimal ASCII. Par exemple, "0A" représente une nouvelle ligne. (facultatif)

    Méthode HTTP et URL :

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/export

    Corps JSON de la requête :

    {
     "exportContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "databases": ["database_name"],
          "offload": true | false
          "csvExportOptions":
           {
               "selectQuery": "select_query",
               "escapeCharacter":  "escape_character",
               "quoteCharacter": "quote_character",
               "fieldsTerminatedBy": "fields_terminated_by",
               "linesTerminatedBy": "lines_terminated_by"
           }
       }
    }
    

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir une réponse JSON de ce type :

    Vous devez spécifier une seule base de données via la propriété databases, et si la requête "select" spécifie une base de données, celle-ci doit être identique.

  4. Si vous n'avez pas besoin de conserver le rôle IAM que vous avez défini précédemment, révoquez-le maintenant.
Pour obtenir la liste complète des paramètres de cette requête, consultez la page instances:export.

Personnaliser le format d'une exportation de fichier CSV

Vous pouvez utiliser gcloud ou l'API REST pour personnaliser le format de votre fichier CSV. Lorsque vous effectuez une exportation, vous pouvez spécifier les options de mise en forme suivantes :

Option CSV Valeur par défaut Option gcloud Propriété de l'API REST Description
Échap

"22"

Code hexadécimal ASCII pour les guillemets doubles.

--escape escapeCharacter

Caractère qui précède un caractère de données devant être échappé.

Disponible uniquement pour MySQL et PostgreSQL.

Devis

"22"

Code hexadécimal ASCII pour les guillemets doubles.

--quote quoteCharacter

Caractère qui contient des valeurs de colonnes contenant un type de données de chaîne.

Disponible uniquement pour MySQL et PostgreSQL.

Délimiteur de champ

"2C"

Code hexadécimal ASCII pour la virgule.

--fields-terminated-by fieldsTerminatedBy

Caractère séparant les valeurs de colonne.

Disponible uniquement pour MySQL et PostgreSQL.

Caractère de nouvelle ligne

"0A"

Code hexadécimal ASCII pour la nouvelle ligne.

--lines-terminated-by linesTerminatedBy

Caractère séparant les enregistrements de ligne.

Disponible uniquement pour MySQL.

Par exemple, une commande gcloud utilisant tous ces arguments peut se présenter comme suit :

gcloud sql export csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--offload \
--query=SELECT_QUERY \
--quote="22" \
--escape="5C" \
--fields-terminated-by="2C" \
--lines-terminated-by="0A"

Le corps de requête API REST équivalent ressemblerait à ceci :

{
 "exportContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "databases": ["DATABASE_NAME"],
      "offload": true,
      "csvExportOptions":
       {
           "selectQuery": "SELECT_QUERY",
           "escapeCharacter":  "5C",
           "quoteCharacter": "22",
           "fieldsTerminatedBy": "2C",
           "linesTerminatedBy": "0A"
       }
   }
}

L'exportation au format CSV crée par défaut une sortie au format CSV standard avec trois options personnalisées. Si vous avez besoin d'autres options que Cloud SQL, vous pouvez utiliser l'instruction suivante dans un client psql :

      \copy [table_name] TO '[csv_file_name].csv' WITH
          (FORMAT csv, ESCAPE '[escape_character]', QUOTE '[quote_character]',
          DELIMITER '[delimiter_character]', ENCODING 'UTF8', NULL '[null_marker_string]');

Import

Rôles et autorisations requis pour l'importation

Cette procédure nécessite l'importation d'un fichier à partir de Cloud Storage. Pour importer des données depuis Cloud Storage, le compte de service ou l'utilisateur doit disposer de l'un des rôles suivants :

  • Rôle Admin Cloud SQL Editor et rôle IAM roles/storage.legacyObjectReader.
  • Rôle personnalisé comprenant les autorisations suivantes :
    • cloudsql.instances.get
    • cloudsql.instances.import
    • storage.buckets.get
    • storage.objects.get

Si le compte ou l'utilisateur effectuent également des opérations d'exportation, il peut être plus pratique d'accorder le rôle IAM Storage Object Admin afin de disposer de toutes les autorisations requises pour l'importation et l'exportation. Pour obtenir de l'aide sur les rôles IAM, consultez la page Cloud Identity and Access Management pour Cloud Storage.

Importer des données à partir d'un fichier CSV

Pour importer des données dans une instance Cloud SQL à l'aide d'un fichier CSV :

Console

  1. Dans Google Cloud Console, accédez à la page Instances Cloud SQL.

    Accéder à la page Instances Cloud SQL

  2. Cliquez sur le nom de l'instance pour ouvrir la page Présentation.
  3. Cliquez sur Import (Importer).
  4. Dans la section Sélectionnez le fichier à partir duquel vous souhaitez importer des données, saisissez le chemin d'accès au bucket et au fichier CSV à utiliser pour l'importation. Ou accédez au fichier :
    1. Cliquez sur Parcourir.
    2. Dans la section Emplacement, double-cliquez sur le nom du bucket dans la liste.
    3. Sélectionnez le fichier dans la liste.
    4. Cliquez sur Sélectionner.

    Vous pouvez importer un fichier compressé (.gz) ou non compressé (.csv).

  5. Dans la section Format, sélectionnez CSV.
  6. Spécifiez la base de données et la table de votre instance Cloud SQL dans lesquelles vous souhaitez importer le fichier CSV.
  7. Vous pouvez éventuellement spécifier un utilisateur pour l'opération d'importation.
  8. Cliquez sur Importer pour démarrer l'importation.

gcloud

  1. Créer un bucket Cloud Storage
  2. Importez le fichier dans le bucket.

    Pour obtenir de l'aide concernant l'importation de fichiers dans des buckets, consultez la page Importer des objets.

  3. Importez les données du fichier CSV dans le bucket.
  4. Décrivez l'instance à partir de laquelle vous souhaitez exporter :
    gcloud sql instances describe INSTANCE_NAME
    
  5. Copiez le champ "serviceAccountEmailAddress".
  6. Utilisez gsutil iam pour accorder au compte de service le rôle IAM storage.objectAdmin sur le bucket. Pour obtenir de l'aide sur la définition des autorisations IAM, consultez la page Utiliser des autorisations IAM.
  7. Importez le fichier :
    gcloud sql import csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
    --database=DATABASE_NAME \
    --table=TABLE_NAME
    

    Pour plus d'informations sur l'utilisation de la commande import csv, consultez la page de référence de la commande sql import csv.

  8. Si vous n'avez pas besoin de conserver les autorisations IAM que vous avez définies précédemment, supprimez-les en utilisant gsutil iam.

REST v1

  1. Créer un bucket Cloud Storage
  2. Importez le fichier dans le bucket.

    Pour obtenir de l'aide concernant l'importation de fichiers dans des buckets, consultez la page Importer des objets.

  3. Attribuez à votre instance les rôles IAM legacyBucketWriter et objectViewer pour votre bucket. Pour obtenir de l'aide sur la définition des autorisations IAM, consultez la page Utiliser des autorisations IAM.
  4. Importez le fichier :

    Avant d'utiliser les données de requête, effectuez les remplacements suivants :

    • project-id : ID du projet
    • instance-id : ID de l'instance
    • bucket_name : nom du bucket Cloud Storage
    • path_to_csv_file : chemin d'accès au fichier CSV
    • database_name : nom d'une base de données dans l'instance Cloud SQL
    • table_name : nom de la table de base de données
    • escape_character : caractère qui doit précéder un caractère de données devant être échappé. La valeur de cet argument doit être un caractère en code ASCII hexadécimal. Par exemple, "22" représente les guillemets doubles. (facultatif)
    • quote_character : caractère englobant les valeurs des colonnes contenant un type de données de chaîne. La valeur de cet argument doit être un caractère en code ASCII hexadécimal. Par exemple, "22" représente les guillemets doubles. (facultatif)
    • fields_terminated_by : caractère scindant les valeurs de colonne. La valeur de cet argument doit être un caractère en code ASCII hexadécimal. Par exemple, "2C" représente une virgule. (facultatif)
    • lines_terminated_by : caractère qui divise les enregistrements de ligne. La valeur de cet argument doit être un caractère en code ASCII hexadécimal. Par exemple, "0A" représente une nouvelle ligne. (facultatif)

    Méthode HTTP et URL :

    POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id/import

    Corps JSON de la requête :

    {
     "importContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "database": "database_name",
          "csvImportOptions":
           {
             "table": "table_name",
             "escapeCharacter": "escape_character",
             "quoteCharacter": "quote_character",
             "fieldsTerminatedBy": "fields_terminated_by",
             "linesTerminatedBy": "lines_terminated_by"
           }
       }
    }
    
    

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir une réponse JSON de ce type :

    Pour obtenir la liste complète des paramètres de cette requête, consultez la page instances:import.
  5. Si vous n'avez pas besoin de conserver les autorisations Cloud IAM que vous avez définies précédemment, supprimez-les.

REST v1beta4

  1. Créer un bucket Cloud Storage
  2. Importez le fichier dans le bucket.

    Pour obtenir de l'aide concernant l'importation de fichiers dans des buckets, consultez la page Importer des objets.

  3. Attribuez à votre instance le rôle IAM storage.objectAdmin pour votre bucket. Pour obtenir de l'aide sur la définition des autorisations IAM, consultez la page Utiliser des autorisations IAM.
  4. Importez le fichier :

    Avant d'utiliser les données de requête, effectuez les remplacements suivants :

    • project-id : ID du projet
    • instance-id : ID de l'instance
    • bucket_name : nom du bucket Cloud Storage
    • path_to_csv_file : chemin d'accès au fichier CSV
    • database_name : nom d'une base de données dans l'instance Cloud SQL
    • table_name : nom de la table de base de données
    • escape_character : caractère qui doit précéder un caractère de données devant être échappé. La valeur de cet argument doit être au format hexadécimal ASCII. Par exemple,"22" représente les guillemets doubles. (facultatif)
    • quote_character : caractère englobant les valeurs des colonnes contenant un type de données de chaîne. La valeur de cet argument doit être au format hexadécimal ASCII. Par exemple, "22" représente les guillemets doubles. (facultatif)
    • fields_terminated_by : caractère scindant les valeurs de colonne. La valeur de cet argument doit être au format hexadécimal ASCII. Par exemple, "2C" représente une virgule. (facultatif)
    • lines_terminated_by : caractère qui divise les enregistrements de ligne. La valeur de cet argument doit être au format hexadécimal ASCII. Par exemple, "0A" représente une nouvelle ligne. (facultatif)

    Méthode HTTP et URL :

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/import

    Corps JSON de la requête :

    {
     "importContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "database": "database_name",
          "csvImportOptions":
           {
             "table": "table_name",
             "escapeCharacter": "escape_character",
             "quoteCharacter": "quote_character",
             "fieldsTerminatedBy": "fields_terminated_by",
             "linesTerminatedBy": "lines_terminated_by"
           }
       }
    }
    
    

    Pour envoyer votre requête, développez l'une des options suivantes :

    Vous devriez recevoir une réponse JSON de ce type :

    Pour obtenir la liste complète des paramètres de cette requête, consultez la page instances:import.
  5. Si vous n'avez pas besoin de conserver les autorisations Cloud IAM que vous avez définies précédemment, supprimez-les.

Personnaliser le format d'une importation de fichier CSV

Vous pouvez utiliser gcloud ou l'API REST pour personnaliser le format de votre fichier CSV.

Voici un exemple de commandes gcloud :

gcloud sql import csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--table=TABLE_NAME \
--quote="22" \
--escape="5C" \
--fields-terminated-by="2C" \
--lines-terminated-by="0A"

Le corps de requête API REST équivalent ressemblerait à ceci :

{
 "importContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "database": ["DATABASE_NAME"],
      "csvImportOptions":
       {
           "table": "TABLE_NAME",
           "escapeCharacter":  "5C",
           "quoteCharacter": "22",
           "fieldsTerminatedBy": "2C",
           "linesTerminatedBy": "0A"
       }
   }
}

Si vous obtenez une erreur telle que ERROR_RDBMS, vérifiez que la table existe bien. Si tel est le cas, vérifiez que vous disposez des autorisations appropriées sur le bucket. Pour vous aider à configurer le contrôle des accès dans Cloud Storage, consultez la page Créer et gérer des listes de contrôle d'accès.

Pour découvrir comment est formée la requête sous-jacente de l'API REST pour cette tâche, consultez la page relative à la méthode "instances:import" dans l'explorateur d'API.

Étape suivante