Add README and metadata to database dump.

Author: smarnach

src/tasks/dump_db.rs

@@ -29,24 +29,57 @@ pub fn dump_db(
 /// make sure it gets deleted again even in the case of an error.
 #[derive(Debug)]
 pub struct DumpDirectory {
+    pub timestamp: chrono::DateTime<chrono::Utc>,
     pub export_dir: PathBuf,
 }
 
 impl DumpDirectory {
     pub fn create() -> Result<Self, PerformError> {
-        let timestamp = chrono::Utc::now().format("%Y-%m-%d-%H%M%S").to_string();
-        let export_dir = std::env::temp_dir().join("dump-db").join(timestamp);
+        let timestamp = chrono::Utc::now();
+        let timestamp_str = timestamp.format("%Y-%m-%d-%H%M%S").to_string();
+        let export_dir = std::env::temp_dir().join("dump-db").join(timestamp_str);
         std::fs::create_dir_all(&export_dir)?;
-        Ok(Self { export_dir })
+        Ok(Self {
+            timestamp,
+            export_dir,
+        })
     }
 
     pub fn dump_db(&self, database_url: &str) -> Result<(), PerformError> {
+        self.add_readme()?;
+        self.add_metadata()?;
         let export_script = self.export_dir.join("export.sql");
         let import_script = self.export_dir.join("import.sql");
         gen_scripts::gen_scripts(&export_script, &import_script)?;
         std::fs::create_dir(self.export_dir.join("data"))?;
         run_psql(&export_script, database_url)
     }
+
+    fn add_readme(&self) -> Result<(), PerformError> {
+        use std::io::Write;
+
+        let mut readme = File::create(self.export_dir.join("README.md"))?;
+        readme.write_all(include_bytes!("dump_db/readme_for_tarball.md"))?;
+        Ok(())
+    }
+
+    fn add_metadata(&self) -> Result<(), PerformError> {
+        #[derive(Serialize)]
+        struct Metadata<'a> {
+            timestamp: &'a chrono::DateTime<chrono::Utc>,
+            crates_io_commit: String,
+            format_version: &'static str,
+        }
+        let metadata = Metadata {
+            timestamp: &self.timestamp,
+            crates_io_commit: dotenv::var("HEROKU_SLUG_COMMIT")
+                .unwrap_or_else(|_| "unknown".to_owned()),
+            format_version: "0.1",
+        };
+        let file = File::create(self.export_dir.join("metadata.json"))?;
+        serde_json::to_writer_pretty(file, &metadata)?;
+        Ok(())
+    }
 }
 
 impl Drop for DumpDirectory {

src/tasks/dump_db/dump-export.sql.hbs

@@ -1,6 +1,3 @@
--- This script was used to create this database dump, and is only included in
--- the archive for reference.
-
 BEGIN;
 {{~#each tables}}
 {{~#if this.filter}}

src/tasks/dump_db/dump-import.sql.hbs

@@ -1,19 +1,3 @@
--- Script for psql to restore the dump into a local crates.io database.
---
--- WARNING: This will destroy the current database contents.
---
--- Instructions:
---
--- 1. Create a new database and run the Diesel migrations.
---
---        createdb DATABASE_NAME
---        diesel migration run --database-url DATABASE_URL
---
--- 2. Run this script.
---
---        cd DUMP_DIRECTORY
---        psql DATABASE_URL < import.sql
-
 BEGIN;
     -- Set defaults for non-nullable columns not included in the dump.
 {{~#each tables as |table|}}

src/tasks/dump_db/readme_for_tarball.md

@@ -0,0 +1,30 @@
+# crates.io Database Dump
+
+This is a dump of the public information in the crates.io database.
+
+## Files
+
+* `data/` – the CSV files with the actual dump data.
+* `export.sql` – the `psql` script that was used to create this database dump. It is only included in the archive for reference.
+* `import.sql` – a `psql` script that can be used to restore the dump into a PostgreSQL database with the same schema as the `crates.io` database, destroying all current data.
+* `metadata.json` – some metadata of this dump.
+
+## Metadata Fields
+
+* `timestamp` – the UTC time the dump was started.
+* `crates_io_commit` – the git commit hash of the deployed version of crates.io that created this dump.
+* `format_version` – the version of the layout and format of this dump. Roughly follows SemVer conventions.
+
+## Restoring to a Local crates.io Database
+
+WARNING: This will destroy the current database contents.
+
+1. Create a new database and run the Diesel migrations.
+
+        createdb DATABASE_NAME
+        diesel migration run --database-url DATABASE_URL
+
+2. Run this script.
+
+        cd DUMP_DIRECTORY
+        psql DATABASE_URL < import.sql