view release on metacpan or  search on metacpan

lib/DBM/Deep/Cookbook.pod  view on Meta::CPAN

=head1 NAME

DBM::Deep::Cookbook - Cookbook for DBM::Deep

=head1 DESCRIPTION

This is the Cookbook for L<DBM::Deep>. It contains useful tips and tricks,
plus some examples of how to do common tasks.

=head1 RECIPES

=head2 Unicode data

If possible, it is highly recommended that you upgrade your database to
version 2 (using the F<utils/upgrade_db.pl> script in the CPAN
distribution), in order to use Unicode.

If your databases are still shared by perl installations with older
DBM::Deep versions, you can use filters to encode strings on the fly:

  my $db = DBM::Deep->new( ... );
  my $encode_sub = sub { my $s = shift; utf8::encode($s); $s };
  my $decode_sub = sub { my $s = shift; utf8::decode($s); $s };
  $db->set_filter( 'store_value' => $encode_sub );
  $db->set_filter( 'fetch_value' => $decode_sub );
  $db->set_filter( 'store_key' => $encode_sub );
  $db->set_filter( 'fetch_key' => $decode_sub );

A previous version of this cookbook recommended using
C<binmode $db-E<gt>_fh, ":utf8">, but that is I<not> a good idea, as it
could easily corrupt the database.

=head2 Real-time Encryption Example

B<NOTE>: This is just an example of how to write a filter. This most
definitely should B<NOT> be taken as a proper way to write a filter that does
encryption. (Furthermore, it fails to take Unicode into account.)

Here is a working example that uses the I<Crypt::Blowfish> module to
do real-time encryption / decryption of keys & values with DBM::Deep Filters.
Please visit L<http://search.cpan.org/search?module=Crypt::Blowfish> for more
on I<Crypt::Blowfish>. You'll also need the I<Crypt::CBC> module.

  use DBM::Deep;
  use Crypt::Blowfish;
  use Crypt::CBC;

  my $cipher = Crypt::CBC->new({
      'key'             => 'my secret key',
      'cipher'          => 'Blowfish',
      'iv'              => '$KJh#(}q',
      'regenerate_key'  => 0,
      'padding'         => 'space',
      'prepend_iv'      => 0
  });

  my $db = DBM::Deep->new(
      file => "foo-encrypt.db",
      filter_store_key => \&my_encrypt,
      filter_store_value => \&my_encrypt,
      filter_fetch_key => \&my_decrypt,
      filter_fetch_value => \&my_decrypt,
  );

  $db->{key1} = "value1";
  $db->{key2} = "value2";
  print "key1: " . $db->{key1} . "\n";
  print "key2: " . $db->{key2} . "\n";

  undef $db;
  exit;

  sub my_encrypt {
      return $cipher->encrypt( $_[0] );
  }
  sub my_decrypt {
      return $cipher->decrypt( $_[0] );
  }

=head2 Real-time Compression Example

Here is a working example that uses the I<Compress::Zlib> module to do real-time
compression / decompression of keys & values with DBM::Deep Filters.
Please visit L<http://search.cpan.org/search?module=Compress::Zlib> for
more on I<Compress::Zlib>.

  use DBM::Deep;
  use Compress::Zlib;

  my $db = DBM::Deep->new(
      file => "foo-compress.db",
      filter_store_key => \&my_compress,
      filter_store_value => \&my_compress,
      filter_fetch_key => \&my_decompress,
      filter_fetch_value => \&my_decompress,
  );

  $db->{key1} = "value1";
  $db->{key2} = "value2";
  print "key1: " . $db->{key1} . "\n";
  print "key2: " . $db->{key2} . "\n";

  undef $db;
  exit;

  sub my_compress {
      my $s = shift;
      utf8::encode($s);