<commit_before>= <em>s3db-backup</em> for Rails

Its good practice to have a backup of your database ready at some other place than your production setup in case anything goes badly wrong there. And its a good idea to test your backups regularily. This gem will help you do both in a snap.

== Backup Your MySQL Database To Amazon S3

To get your data out of your own data center and store it somewhere save, amazon S3 is a great candidate. But, of course, you do not want to let anyone be able to read your application database. That's why <em>s3db-backup</em> is encrypting your dump before sending it to amazon S3.

== Requirements

As <em>s3db-backup</em> is using standard Unix tools for the heavy lifting, please make sure you have the following installed on your machine:

* <tt>mysqldump</tt> (comes with the mysql client, should be there)
* <tt>gzip</tt> (never saw a system without it)
* <tt>ccrypt</tt> (you might need to install it: <tt>apt-get install ccrypt</tt> (Debian, Ubuntu), <tt>yum install ccrypt</tt> (Redhat, CentOS), or <tt>brew install ccrypt</tt> (Mac OS X using homebrew))

And, of course, you'll need to sign up for an Amazon S3 account and create a bucket using the AWS Management Console (or any other way)

== Getting Started

<em>s3db-backup</em> only supports MySQL databases and works from within a Rails application. Here are the steps to get you started:

* Install the <em>s3db-backup</em> gem

    sudo gem install s3db-backup

  Alternatively you can simply add it to your <tt>Gemfile</tt> and run <tt>bundle install</tt>.
	
* Run the <em>s3db_config</em> generator to generate the necessary config files and rake tasks
  NOTE: This currently works only in a Rails 3.x app. You can create the files manually in your Rails 2.x app. Everything will run fine from there on.

    $ rails generate s3db_config
	
This will generate the following files: <tt>config/s3_config.yml</tt>, <tt>db/secret.txt</tt>, and <tt>lib/tasks/db.rake</tt>

* Store your AWS access credentials and your desired S3 buckets in the new <tt>config/s3_config.yml</tt>:

    aws_access_key_id: "<your aws access key here>"
    secret_access_key: "<your aws secret key here>"

    production:
        bucket: "my_app-production"

    development:
        bucket: "my_app-development"

<em>s3db-backup</em> expects the buckets you name there to exist. Please make sure they do (using the Amazon AWS Management Console or any other Amazon Management Tool)

* Put a long and random string as your encryption/decryption key for <tt>ccrypt</tt> into <tt>db/secret.txt</tt>

    $ echo "my secret key" > db/secret.txt

== Running a Backup
	
Dumping, encrypting, and uploading your current database is now as easy as typing one command:
	
    $ rake s3db:backup
	
When its done, go to your amazon S3 bucket and see your shiny new backup file there!
	
== Restoring a Backup Using <tt>rake</tt>

To be able to <em>fetch</em> your backups from S3 and <em>load</em> them into your environment (development or production) you can use a set of rake tasks defined in <tt>lib/tasks/s3db_backup.rake</tt>:

* Fetch the latest backup from S3 to your local disk as <tt>db/latest_prod_dump.sql</tt>:

    $ rake s3db:latest:fetch
	
Now you can either load that SQL dump with any tool you like or use a second rake task:
	
* Load that dump into your environment:

<b>ATTENTION</b>: This step will DROP your database and re-create it from your backup. Be careful when applying to your production environment. You have been warned!

    $ rake s3db:latest:load
	
== Restoring a Backup Manually

I do not trust in backup systems, which do everything on their own. In emergency I want to be able to restore my data manually. 
As <em>s3db-backup</em> only uses standard Unix tools for the job, its pretty easy. Here are the steps to manually restore your database

* Download the latest backup from your Amazon S3 bucket e.g. <tt>mysql-my_app-production-22-09-2010-11h24m10s.sql.gz.cpt</tt>
* Decrypt the file using your key from <tt>db/secret.txt</tt>
	ccdecrypt mysql-my_app-production-22-09-2010-11h24m10s.sql.gz.cpt
* Unzip the SQL file
    gunzip mysql-my_app-production-22-09-2010-11h24m10s.sql.gz
* Re-create your database
    rake db:create
* Load the dump into mysql
    mysql -u <your_db_user> -p <your_db> < mysql-my_app-production-22-09-2010-11h24m10s.sql
	
Now you should have your DB restored.

== Note on Patches/Pull Requests
 
* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.

== Copyright
<commit_msg>one more layout fix for README<commit_after>= <em>s3db-backup</em> for Rails

Its good practice to have a backup of your database ready at some other place than your production setup in case anything goes badly wrong there. And its a good idea to test your backups regularily. This gem will help you do both in a snap.

== Backup Your MySQL Database To Amazon S3

To get your data out of your own data center and store it somewhere save, amazon S3 is a great candidate. But, of course, you do not want to let anyone be able to read your application database. That's why <em>s3db-backup</em> is encrypting your dump before sending it to amazon S3.

== Requirements

As <em>s3db-backup</em> is using standard Unix tools for the heavy lifting, please make sure you have the following installed on your machine:

* <tt>mysqldump</tt> (comes with the mysql client, should be there)
* <tt>gzip</tt> (never saw a system without it)
* <tt>ccrypt</tt> (you might need to install it: <tt>apt-get install ccrypt</tt> (Debian, Ubuntu), <tt>yum install ccrypt</tt> (Redhat, CentOS), or <tt>brew install ccrypt</tt> (Mac OS X using homebrew))

And, of course, you'll need to sign up for an Amazon S3 account and create a bucket using the AWS Management Console (or any other way)

== Getting Started

<em>s3db-backup</em> only supports MySQL databases and works from within a Rails application. Here are the steps to get you started:

* Install the <em>s3db-backup</em> gem

    sudo gem install s3db-backup

  Alternatively you can simply add it to your <tt>Gemfile</tt> and run <tt>bundle install</tt>.
	
* Run the <em>s3db_config</em> generator to generate the necessary config files and rake tasks
  NOTE: This currently works only in a Rails 3.x app. You can create the files manually in your Rails 2.x app. Everything will run fine from there on.

    $ rails generate s3db_config
	
This will generate the following files: <tt>config/s3_config.yml</tt>, <tt>db/secret.txt</tt>, and <tt>lib/tasks/db.rake</tt>

* Store your AWS access credentials and your desired S3 buckets in the new <tt>config/s3_config.yml</tt>:

    aws_access_key_id: "<your aws access key here>"
    secret_access_key: "<your aws secret key here>"

    production:
        bucket: "my_app-production"

    development:
        bucket: "my_app-development"

<em>s3db-backup</em> expects the buckets you name there to exist. Please make sure they do (using the Amazon AWS Management Console or any other Amazon Management Tool)

* Put a long and random string as your encryption/decryption key for <tt>ccrypt</tt> into <tt>db/secret.txt</tt>

    $ echo "my secret key" > db/secret.txt

== Running a Backup
	
Dumping, encrypting, and uploading your current database is now as easy as typing one command:
	
    $ rake s3db:backup
	
When its done, go to your amazon S3 bucket and see your shiny new backup file there!
	
== Restoring a Backup Using <tt>rake</tt>

To be able to <em>fetch</em> your backups from S3 and <em>load</em> them into your environment (development or production) you can use a set of rake tasks defined in <tt>lib/tasks/s3db_backup.rake</tt>:

* Fetch the latest backup from S3 to your local disk as <tt>db/latest_prod_dump.sql</tt>:

    $ rake s3db:latest:fetch
	
Now you can either load that SQL dump with any tool you like or use a second rake task:
	
* Load that dump into your environment:

<b>ATTENTION</b>: This step will DROP your database and re-create it from your backup. Be careful when applying to your production environment. You have been warned!

    $ rake s3db:latest:load
	
== Restoring a Backup Manually

I do not trust in backup systems, which do everything on their own. In emergency I want to be able to restore my data manually. 
As <em>s3db-backup</em> only uses standard Unix tools for the job, its pretty easy. Here are the steps to manually restore your database

* Download the latest backup from your Amazon S3 bucket e.g. <tt>mysql-my_app-production-22-09-2010-11h24m10s.sql.gz.cpt</tt>
* Decrypt the file using your key from <tt>db/secret.txt</tt>
    ccdecrypt mysql-my_app-production-22-09-2010-11h24m10s.sql.gz.cpt
* Unzip the SQL file
    gunzip mysql-my_app-production-22-09-2010-11h24m10s.sql.gz
* Re-create your database
    rake db:create
* Load the dump into mysql
    mysql -u <your_db_user> -p <your_db> < mysql-my_app-production-22-09-2010-11h24m10s.sql
	
Now you should have your DB restored.

== Note on Patches/Pull Requests
 
* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.

== Copyright

{'fraction_non_alphanumeric': 0.07909371781668383, 'fraction_numerical': 0.01709577754891864, 'mean_word_length': 3.9419847328244275, 'pattern_counts': {'":': 0, '<': 133, '<?xml version=': 0, '>': 133, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2672436', 'n_tokens_mistral': 3051, 'n_tokens_neox': 2876, 'n_words': 1379}