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 des données depuis Cloud SQL pour PostgreSQL

Rôles et autorisations requis pour l'exportation à partir de Cloud SQL pour PostgreSQL

Pour exporter des données de Cloud SQL vers Cloud Storage, l'utilisateur qui lance l'exportation doit disposer de l'un des rôles suivants :

De plus, le compte de service de l'instance Cloud SQL doit disposer de l'un des rôles suivants :

  • Le rôle IAM (Identity and Access Management) storage.objectAdmin
  • Un rôle personnalisé comprenant les autorisations suivantes :
    • storage.objects.create
    • storage.objects.list (pour l'exportation de fichiers en parallèle uniquement)
    • storage.objects.delete (pour l'exportation de fichiers en parallèle uniquement)

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

Exporter des données vers un fichier CSV à partir de Cloud SQL pour PostgreSQL

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 la console Google Cloud, accédez à la page Instances Cloud SQL.

    Accéder à la page Instances Cloud SQL

  2. Pour ouvrir la page Présentation d'une instance, cliquez sur son nom.
  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 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. Une fois l'exportation démarrée, vous pouvez annuler l'opération. 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 gcloud storage buckets add-iam-policy-binding pour accorder le rôle IAM storage.objectAdmin au compte de service de l'instance Cloud SQL. 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 : 
    gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_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 devant 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 qui contient des valeurs de 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 : 
    gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_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 devant 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 qui contient des valeurs de 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'un fichier d'exportation 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

"5C"

Code hexadécimal ASCII pour le séparateur de fichiers.

--escape escapeCharacter

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

Disponible uniquement pour MySQL et PostgreSQL.

Citation

"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"
       }
   }
}

Par défaut, l'exportation au format CSV crée un fichier de sortie au format CSV standard. 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]');

Importer des données dans Cloud SQL pour PostgreSQL

Rôles et autorisations requis pour l'importation dans Cloud SQL pour PostgreSQL

Pour importer des données de Cloud Storage dans Cloud SQL, l'utilisateur qui lance l'importation doit disposer de l'un des rôles suivants :

De plus, le compte de service de l'instance Cloud SQL doit disposer de l'un des rôles suivants :

  • Le rôle IAM storage.objectAdmin
  • Un rôle personnalisé comprenant les autorisations suivantes :
    • storage.objects.get
    • storage.objects.list (pour l'importation de fichiers en parallèle uniquement)

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

Importer des données à partir d'un fichier CSV dans Cloud SQL pour PostgreSQL

Exigences relatives au format de fichier CSV

Les fichiers CSV doivent comporter une ligne par rangée de données ainsi que des champs séparés par une virgule.

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

Console

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

    Accéder à la page Instances Cloud SQL

  2. Pour ouvrir la page Présentation d'une instance, cliquez sur son nom.
  3. Cliquez sur 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. Identifiez le compte de service de l'instance Cloud SQL à partir de laquelle vous souhaitez effectuer l'exportation. Pour ce faire, exécutez la commande gcloud sql instances describe avec le nom de l'instance. Recherchez le champ serviceAccountEmailAddress dans le résultat. 
    gcloud sql instances describe INSTANCE_NAME
  5. Copiez le champ "serviceAccountEmailAddress".
  6. Utilisez gcloud storage buckets add-iam-policy-binding pour accorder le rôle IAM storage.objectAdmin au compte de service de l'instance Cloud SQL 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 à l'aide de gcloud storage buckets remove-iam-policy-binding.

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 devant 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 qui contient des valeurs de 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 devant 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 qui contient des valeurs de 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'un fichier CSV pour Cloud SQL pour PostgreSQL

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 sur la méthode instances:import dans APIs Explorer.

Étape suivante