NAME

PowerDNS::Backend::MySQL - Provides an interface to manipulate PowerDNS data in the MySQL Backend.

VERSION

Version 0.12

SYNOPSIS

        use PowerDNS::Backend::MySQL;

        # Setting parameters and their default values.
        my $params = {  db_user                 =>      'root',
                        db_pass                 =>      '',
                        db_name                 =>      'pdns',
                        db_port                 =>      '3306',
                        db_host                 =>      'localhost',
                        mysql_print_error       =>      1,
                        mysql_warn              =>      1,
                        mysql_auto_commit       =>      1,
                        mysql_auto_reconnect    =>      1,
                        lock_name               =>      'powerdns_backend_mysql',
                        lock_timeout            =>      3,
        };

        my $pdns = PowerDNS::Backend::MySQL->new($params);

DESCRIPTION

        PowerDNS::Backend::MySQL provides a layer of abstraction 
        for manipulating the data stored in the PowerDNS MySQL backend.

METHODS

new(\%params)

        my $params = {  db_user                 =>      'root',
                        db_pass                 =>      '',
                        db_name                 =>      'pdns',
                        db_port                 =>      '3306',
                        db_host                 =>      'localhost',
                        mysql_print_error       =>      1,
                        mysql_warn              =>      1,
                        mysql_auto_commit       =>      1,
                        mysql_auto_reconnect    =>      1,
                        lock_name               =>      'powerdns_backend_mysql',
                        lock_timeout            =>      3,
        };

        my $pdns = PowerDNS::Backend::MySQL->new($params);

        Creates a PowerDNS::Backend::MySQL object.
db_user

The DB user to use when connecting to the MySQL Backend.

db_pass

The DB password to use when connecting to the MySQL Backend.

db_name

The DB name to use when connecting to the MySQL Backend.

db_port

The DB port to use when connecting to the MySQL Backend.

db_host

The DB host to use when connecting to the MySQL Backend.

mysql_print_error

Used to set the DBI::PrintError value.

mysql_warn

Used to set the DBI::Warn value.

mysql_auto_commit

Used to set the DBI::AutoCommit value.

mysql_auto_reconnect

Used to set the DBD::mysql::mysql_auto_reconnect value.

lock_name

Critical sections (adds, deletes, updates on records) get MySQL application level locks (GET_LOCK : http://dev.mysql.com/doc/refman/5.0/en/miscellaneous-functions.html#function_get-lock); this option can be used to override the default lock name used in those calls.

lock_timeout

Critical sections (adds, deletes, updates on records) get MySQL application level locks (GET_LOCK : http://dev.mysql.com/doc/refman/5.0/en/miscellaneous-functions.html#function_get-lock); this option can be used to override the default lock timeout used in those calls.

add_domain(\$domain)

Expects a scalar reference domain name to add to the DB. Returns 1 on success and 0 on failure.

add_master(\$domain)

Expects a scalar reference domain name to add to the DB as type master. Returns 1 on success and 0 on failure.

add_slave(\$slave_domain , \$master_ip)

Expects two scalar references; first the domain to slave, then the IP address to slave from. Returns 1 on success and 0 on failure. Updates the existing record if there is one, otherwise inserts a new record.

delete_domain(\$domain)

Expects a scalar reference domain name to delete from the DB. Returns 1 on success and 0 on failure.

list_domain_names

Does not expect anything. Returns a reference to an array which contains all the domain names listed in the PowerDNS backend.

list_domain_names_by_type(\$type)

Expects a scalar reference to a string which is the domain 'type' (i.e. NATIVE, SLAVE, MASTER, etc.) Returns a reference to an array which contains all the domain names of that type.

list_slave_domain_names(\$master_ip)

Expects a scalar reference to an IP address which is the master IP. Returns a reference to an array which contains all the slave domain names with $master as their 'master'.

domain_exists(\$domain)

Expects a scalar reference to a domain name to be found in the "domains" table. Returns 1 if the domain name is found, and 0 if it is not found.

list_records(\$rr , \$domain)

Expects two scalar references; the first to a resource record and the second to a domain name. Returns a reference to a two-dimensional array which contains the resource record name, content, TTL, and priority if any.

list_all_records(\$domain)

Expects a scalar reference to a domain name. Returns a reference to a two-dimensional array which contains the resource record name, type, content, TTL, and priority if any of the supplied domain.

add_record(\$rr , \$domain)

Adds a single record to the backend. Expects two scalar references; one to an array that contains the information for the resource record (name, type, content, ttl, prio); name, type and content are required values. The other scalar reference is the zone you want to add the RR to. Returns 1 if the record was successfully added, and 0 if not.

delete_record(\$rr , \$domain)

Deletes a single record from the backend. Expects two scalar references; one to an array that contains the information for the resource record (name, type, content); these are all required values. The other scalar reference is the zone you want to delete the RR from. Returns 1 if the record was successfully deleted, and 0 if not.

update_record(\$rr1 , \$rr2 , \$domain)

Updates a single record in the backend.

Expects three scalar references:

1) A reference to an array that contains the Resource Record to be updated; ($name , $type , $content) - all required.

2) A reference to an array that contains the updated values; ($name , $type , $content , $ttl , $prio) - only $name , $type , $content are required. Defaults for $ttl and $prio will be used if none are given.

3) The domain to be updated.

Returns 1 on a successful update, and 0 when un-successful.

update_records(\$rr1 , \$rr2 , \$domain)

Can update multiple records in the backend.

Like update_record() but without the requirement that the 'content' be set in the resource record(s) you are trying to update; also not limited to updating just one record, but can update any number of records that match the resource record you are looking for.

Expects three scalar references:

1) A reference to an array that contains the Resource Record to be updated; ($name , $type) - all required.

2) A reference to an array that contains the updated values; ($name , $type , $content , $ttl , $prio) - only $name , $type , $content are required. Defaults for $ttl and $prio will be used if none are given.

3) The domain to be updated.

Returns 1 on a successful update, and 0 when un-successful.

update_or_add_records(\$rr1 , \$rr2 , \$domain)

Can update multiple records in the backend; will insert records if they don't already exist.

Expects three scalar references:

1) A reference to an array that contains the Resource Record to be updated; ($name , $type) - all required.

2) A reference to an array that contains the updated values; ($name , $type , $content , $ttl , $prio) - only $name , $type , $content are required. Defaults for $ttl and $prio will be used if none are given.

3) The domain to be updated.

Returns 1 on a successful update, and 0 when un-successful.

find_record_by_content(\$content , \$domain)

Finds a specific (single) record in the backend. Expects two scalar references; the first is the content we are looking for, and the second is the domain to be checked. Returns a reference to an array that contains the name and type from the found record, if any.

find_record_by_name(\$name, \$domain)

Finds a specific (single) record in the backend. Expects two scalar references; the first is the name we are looking for, and the second is the domain to be checked. Returns a reference to an array that contains the content and type from the found record, if any.

make_domain_native(\$domain)

Makes the specified domain a 'NATIVE' domain. Expects one scalar reference which is the domain name to be updated. Returns 1 upon succes and 0 otherwise.

make_domain_master(\$domain)

Makes the specified domain a 'MASTER' domain. Expects one scalar reference which is the domain name to be updated. Returns 1 upon succes and 0 otherwise.

get_domain_type(\$domain)

Expects one scalar reference which is the domain name to query for. Returns a string containing the PowerDNS 'type' of the domain given or 'undef' if the domain does not exist in the backend or an empty string if the domain has no master (i.e. a NATIVE domain).

get_master(\$domain)

Expects one scalar reference which is the domain name to query for. Returns a string containing the PowerDNS 'master' of the domain given or 'undef' if the domain does not exist in the PowerDNS backend or an empty string if the domain has no master (i.e. a NATIVE domain).

increment_serial(\$domain)

Increments the serial in the SOA by one. Assumes the serial is an eight digit date (YYYYMMDD) followed by a two digit increment. Expects one scalar reference which is the domain name to update. Returns 1 upon succes and 0 otherwise.

EXAMPLES

        my $params = {  db_user                 =>      'root',
                        db_pass                 =>      '',
                        db_name                 =>      'pdns',
                        db_port                 =>      '3306',
                        db_host                 =>      'localhost',
                        mysql_print_error       =>      1,
                        mysql_warn              =>      1,
                        mysql_auto_commit       =>      1,
                        mysql_auto_reconnect    =>      1,
        };

        my $pdns = PowerDNS::Backend::MySQL->new($params);

        my $domain = 'example.com';
        my $master = '127.0.0.1';

        unless ( $pdns->add_domain(\$domain) )
        { print "Could not add domain : $domain \n"; }

        unless ( $pdns->add_master(\$domain) )
        { print "Could not add master domain : $domain \n"; }

        unless ( $pdns->add_slave(\$domain,\$master) )
        { print "Could not add slave domain : $domain \n"; }

        unless ( $pdns->delete_domain(\$domain) )
        { print "Could not delete domain : $domain \n"; }

        my $domain_names = $pdns->list_domain_names;

        for my $domain (@$domain_names)
        { print "$domain \n"; }

        my $type = 'NATIVE';
        my $domain_names = $pdns->list_domain_names_by_type(\$type);

        for my $domain (@$domain_names)
        { print "$domain \n"; }

        my $master = '127.0.0.1';
        my $domain_names = $pdns->list_slave_domain_names(\$master);

        for my $domain (@$domain_names)
        { print "$domain \n"; }
        
        if ( $pdns->domain_exists(\$domain) )
        { print "The domain $domain does exist. \n"; }
        else
        { print "The domain $domain does NOT exist. \n"; }
        
        my $rr = 'CNAME';
        my $records = $pdns->list_records(\$rr , \$domain);
        for my $record  (@$records)
        { print "@$record\n"; }
        
        my @rr = ('www.example.com','CNAME','example.com');
        unless ( $pdns->add_record( \@rr , \$domain) )
        { print "Could not add a RR for $domain \n"; }
        
        unless ( $pdns->delete_record(\@rr , \$domain) )
        { print "Could not delete RR for $domain \n"; }
        
        my $domain = 'example.com';
        my @rr1 = ('localhost.example.com','A','127.0.0.1');
        my @rr2 = ('localhost.example.com','CNAME','example.com');
        
        unless ( $pdns->update_record(\@rr1 , \@rr2 , \$domain) )
        { print "Update failed for $domain . \n"; }

        my (@rr1,@rr2,$domain);

        @rr1 = ('example.com','MX');
        @rr2 = ('example.com','MX','mx.example.com');
        $domain = 'example.com';

        unless ( $pdns->update_records( \@rr1 , \@rr2 , \$domain ) )
        { print "Update failed for $domain . \n"; }

        @rr1 = ('example.com','MX');
        @rr2 = ('example.com','MX','mx.example.com');
        $domain = 'example.com';

        unless ( $pdns->update_or_add_records(\@rr1,\@rr2,\$domain) )
        { print "Could not update/add record.\n"; }
        
        my $domain = 'example.com';
        my $content = 'localhost.example.com';
        my $records = $pdns->find_record_by_content(\$content , \$domain);
        my ($name , $type) = @$records;
        print "Name: $name\n";
        print "Type: $type\n";

        my $domain = 'example.com';
        my $name = 'localhost.example.com';
        my $records = $pdns->find_record_by_name(\$name, \$domain);
        my ($content, $type) = @$records;
        print "Content: $content\n";
        print "Type: $type\n";

        my $domain = 'example.com';
        $pdns->make_domain_native(\$domain);

        my $domain = 'example.com';
        $pdns->make_domain_master(\$domain);

        my $domain = 'example.com';
        my $type = $pdns->get_domain_type(\$domain);
        if ( $type )
        { print "Type is '$type'\n"; }
        else
        { print "Domain $domain does not exist.\n" }

        my $master = $pdns->get_master(\$domain);
        print "Master: $master\n";

        my $domain = 'augnix.net';
        unless ( $pdns->increment_serial(\$domain) )
        { print "Could not increment serial."; }

NOTES

Because PowerDNS::Backend::MySQL uses DBI you can get the last DBI error from the global variable "$DBI::errstr"; this can be handy when you want more details as to why a particular method failed.

AUTHOR

Augie Schwer, <augie at cpan.org>

http://www.schwer.us

BUGS

Please report any bugs or feature requests to bug-net-powerdns-backend-mysql at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PowerDNS-Backend-MySQL. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc PowerDNS::Backend::MySQL

    You can also look for information at:

ACKNOWLEDGEMENTS

I would like to thank Sonic.net for allowing me to release this to the public.

COPYRIGHT & LICENSE

Copyright 2012 Augie Schwer, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

        0.12