rbarman 0.0.1 → 0.0.2

data/README.md

@@ -1,10 +1,10 @@
 # rbarman
 
-rbarman - Ruby Wrapper for 2ndQuadrant's PostgreSQL backup tool [pgbarman](http://pgbarman.org)
+rbarman - Ruby Wrapper for 2ndQuadrant's PostgreSQL backup tool [barman](http://pgbarman.org)
 
 ## Installation
 
-pgbarman has to be installed and configured on the same host where this gem is to be used, otherwise it cannot get any useful information about your backups ;)
+barman has to be installed and configured on the same host where this gem is to be used, otherwise it cannot get any useful information about your backups ;)
 
 
 Add this line to your application's Gemfile:
@@ -21,20 +21,32 @@ Or install it yourself as:
 
 ## Usage
 
+Just a few examples..
+
 ### Get all your backups!
 
-This will call pgbarman and some other sources (backup.info, xlog.db) to get information about your backups. This could take several minutes (and  memory) if you have many backups with thousand of wal files. If you don't want to scan for wal file information, use RBarman::Backups.all('server', false)
+This will call various barman commands and some other sources (backup.info, xlog.db) to get information about your backups and could take several minutes (and  memory) if you have many backups with thousand of wal files. 
 
 <pre>
-backups = RBarman::Backups.all('server', true)
-backups.count
+servers = RBarman::Servers.all({:with_backups => true, :with_wal_files => true })
+servers.count
 => 3
 
-backups.each { |b| p "id: #{b.id} }
+servers[0].name
+=> "pgmaster"
+
+servers[0].ssh_cmd
+=> "ssh postgres@10.118.19.4"
+
+servers[0].backups.count
+=> 2
+
+servers[0].backups.each { |b| p "id: #{b.id} }
 => "id: 20130304T080002"
 => "id: 20130225T192654"
 => "id: 20130218T080002"
 
+backups = servers[0].backups
 backups.latest.id
 => "20130304T080002"
 
@@ -75,7 +87,7 @@ backups[0].wal_files[1022].compression
 ### Get just one backup without wal files
 
 <pre>
-backup = RBarman::Backup.by_id('server', '20130225T192654', false)
+backup = RBarman::Backup.by_id('pg_master', '20130225T192654')
 p "id: #{backup.id}|size: #{backup.size / (1024 ** 3) } GB|wal size: #{backup.wal_file_size / (1024 ** 3)} GB"
 => "id: 20130225T192654|size: 217GB|wal size: 72 GB"
 </pre>
@@ -95,7 +107,7 @@ p b.id
 This tells pgbarman to delete the specified backup
 
 <pre>
-backup = RBarman::Backup.by_id('server', '20130225T192654', false)
+backup = RBarman::Backup.by_id('server', '20130225T192654', { :with_wal_files => false })
 p backup.deleted
 => false
 backup.delete

data/lib/rbarman/backup.rb

@@ -1,29 +1,120 @@
 require 'time'
 
+# @author Holger Amann <holger@sauspiel.de>
 module RBarman
 
   class InvalidBackupIdError < RuntimeError
   end
 
+
+  # Represents a barman Backup
   class Backup
+
+    # @return [String, nil] name of the server to which the backup belongs. 
     attr_accessor :server 
-    attr_reader :id, :backup_start, :backup_end, :status, :wal_files, :size, :wal_file_size, :begin_wal, :end_wal, :timeline, :pgdata, :deleted
+
+    # @overload id
+    #   @return [String, nil] id (like '20130304T080002') which identifies 
+    #     the backup and is unique among all backups of a server. 
+    # @overload id=
+    #   Id of the backup
+    #   @param [#to_s] id id of the backup
+    #   @raise [InvalidBackupIdError] if the id is not valid
+    #   @see backup_id_valid?
+    attr_reader :id
+
+    # @overload backup_start
+    #   @return [Time, nil] time when the backup started. 
+    # @overload backup_start=
+    #   Start of the backup 
+    #   @param [#to_s] start time when the backup started
+    attr_reader :backup_start
+
+    # @overload backup_end
+    #   @return [Time, nil] time when the backup stopped. 
+    # @overload backup_end=
+    #   End of the backup
+    #   @param [#to_s] b_end time when the backup stopped
+    attr_reader :backup_end 
+
+    # @overload status
+    #   @return [Symbol, nil] status of the backup, `:empty`, `:started`, `:done` or `:failed`
+    # @overload status=
+    #   Status of the backup
+    #   @param [Symbol] status status of the backup 
+    #   @raise [ArgumentError] if status is not one of `:empty`, `:started`, `:done` or `:failed`
+    attr_reader :status
+
+    # @overload wal_files
+    #   @return [WalFiles, nil] All wal files
+    # @overload wal_files=
+    #   All wal files
+    #   @param [Array, WalFiles] wal_files all wal files
+    #   @raise [ArgumentError] if argument is not an Array
+    attr_reader :wal_files
+
+    # @overload size
+    #   @return [Integer, nil] size of data (in bytes)
+    # @overload size=
+    #   Size of data (in bytes)
+    #   @param [#to_i] size size (in bytes 
+    attr_reader :size 
+
+    # @overload wal_file_size
+    #   @return [Integer, nil] size of wal files (in bytes)
+    # @overload wal_file_size=
+    #   Size of wal files (in bytes)
+    #   @param [#to_i] size size of wal files (in bytes)
+    attr_reader :wal_file_size
+
+    # @overload begin_wal
+    #   @return [WalFile, nil] first wal file after backup started
+    # @overload begin_wal=
+    #   First wal file after backup started
+    #   @param [String,WalFile] wal_file the wal file
+    attr_reader :begin_wal
+
+    # @overload end_wal
+    #   @return [WalFile, nil] last wal file after backup stopped
+    # @overload end_wal=
+    #   Last wal file after backup stopped
+    #   @param [String,WalFile] wal_file the wal file
+    attr_reader :end_wal
+
+    # @overload timeline
+    #   @return [Integer, nil] timeline of the backup. 
+    # @overload timeline=
+    #   Timeline of the backup
+    #   @param [Integer] i timeline of the backup
+    #   @raise [ArgumentError] if timeline == 0
+    attr_reader :timeline
+
+    # @overload pgdata
+    #   @return [String, nil] server's data directory
+    # @overload pgdata=
+    #   Server's data directory
+    #   @param [String] path path to directory
+    #   @raise [ArgumentError] if path is empty
+    attr_reader :pgdata
+
+    # @return [Boolean] if the backup has been deleted
+    attr_reader :deleted
 
     def initialize
       @deleted = false
     end
 
     def id=(id)
-      raise InvalidBackupIdError if !Backup.backup_id_valid?(id)
-      @id = id 
+      raise InvalidBackupIdError if !Backup.backup_id_valid?(id.to_s)
+      @id = id.to_s
     end
 
     def backup_start=(start)
-      @backup_start = Time.parse(start)
+      @backup_start = Time.parse(start.to_s)
     end
 
     def backup_end=(b_end)
-      @backup_end = Time.parse(b_end)
+      @backup_end = Time.parse(b_end.to_s)
     end
 
     def status=(status)
@@ -54,7 +145,6 @@ module RBarman
       @end_wal = WalFile.parse(wal_file)
     end
 
-
     def wal_file_size=(size)
       @wal_file_size = size.to_i
     end
@@ -69,38 +159,58 @@ module RBarman
       @pgdata = path
     end
 
+    # Adds a wal file to the backup
+    # @param [String, WalFile] wal_file the wal file
+    # @return [void]
     def add_wal_file(wal_file)
-      @wal_files = Array.new if @wal_files.nil?
+      @wal_files = WalFiles.new if @wal_files.nil?
       @wal_files << WalFile.parse(wal_file)
     end
 
+    # @return [Boolean] if the wal file is already added to the backup
+    # @param [String, WalFile] wal_file the wal file
     def wal_file_already_added?(wal_file)
       return false if @wal_files.nil?
       return @wal_files.include?(WalFile.parse(wal_file))
     end
 
 
+    # @return [Boolean] if id is a valid backup id
+    # @param [#to_s] id the backup id
+    # @example Check if a backup id is valid
+    #   Backup.backup_id_valid?("20130304T080002") #=> true
+    #   Backup.backup_id_valid?("213") #=> false
     def self.backup_id_valid?(id)
       return false if id.nil?
-      return !id.match(/\d{8,8}T\d{6,6}/).nil?
+      return !id.to_s.match(/\d{8,8}T\d{6,6}/).nil?
     end
 
+    # Instructs the underlying (barman) command to delete the backup and sets its flag {#deleted} to true
     def delete
       cmd = CliCommand.new
       cmd.delete(@server, @id)
       @deleted = true
     end
 
+    # Instructs the underlying (barman) command to create a new backup.
+    # @param [String] server server name for which a backup should be created
+    # @return [Backup] a new backup object with wal files
     def self.create(server)
       cmd = CliCommand.new
       cmd.create(server)
-      backups = Backups.all(server, false)
-      return Backup.by_id(server, backups.latest.id, true)
+      backups = Backups.all(server, { :with_wal_files => false })
+      return Backup.by_id(server, backups.latest.id, { :with_wal_files => true })
     end
 
-    def self.by_id(server, backup_id, with_wal_files=true)
+    # Get a specific backup
+    # @param [String] server server name
+    # @param [String] backup_id id of the backup
+    # @param [Hash] opts options for creating a {Backup}
+    # @option opts [Boolean] :with_wal_files whether to include {WalFiles} in {Backup}
+    # @return [Backup] the backup
+    def self.by_id(server, backup_id, opts = {})
       cmd = CliCommand.new
-      return cmd.backup(server, backup_id, with_wal_files)
+      return cmd.backup(server, backup_id, opts)
     end
   end
 end

data/lib/rbarman/backups.rb

@@ -1,18 +1,33 @@
+# @author Holger Amann <holger@sauspiel.de
 module RBarman
+
+  # An array of {Backup}
   class Backups < Array
+
+    # Initializes a new Array of {Backup}
+    # @param [Array,Backups] other appends all backups from another array
     def initialize(other=nil)
       self.concat(other) if !other.nil? and other.is_a? Array
     end
 
-    def self.all(server, with_wal_files=true)
+    # Instructs the underlying (barman) command to get all backups for a specific server
+    # @param [String] server server name
+    # @param [Hash] opts options for creating {Backups}
+    # @option opts [Boolean] :with_wal_files whether to include {WalFiles}
+    # @return [Backups] an array of {Backup}
+    def self.all(server, opts={})
       cmd = CliCommand.new
-      return Backups.new(cmd.backups(server, with_wal_files))
+      return Backups.new(cmd.backups(server, opts))
     end
 
+    # Get the latest (newest) backup of all backups in the array
+    # @return [Backup] the latest {Backup}
     def latest
       self.sort_by { |d| Time.parse(d.id) }.reverse.first
     end
 
+    # Get the oldest backup of all backups in the array
+    # @return [Backup] the oldest {Backup}
     def oldest
       self.sort_by { |d| Time.parse(d.id) }.first
     end

data/lib/rbarman/cli_command.rb

@@ -1,9 +1,30 @@
 require 'mixlib/shellout'
 
+# @author Holger Amann <holger@sauspiel.de>
 module RBarman
+
+  # Wrapper for the barman command line tool
   class CliCommand
-    attr_reader :binary, :barman_home
 
+    # @overload binary
+    #   @return [String] path to the barman binary
+    # @overload binary=
+    #   Path to the barman binary
+    #   @param [String] path path to the binary
+    #   @raise [ArgumentError] if path doesn't exist or path doesn't end with 'barman'
+    attr_reader :binary 
+
+    # @overload barman_home
+    #   @return [String] base path where barman stores its backups
+    # @overload barman_home=
+    #   Path to the base directory of barman's backups
+    #   @param [String] path path to the base directory
+    #   @raise [ArgumentError] if path doesn't exist
+    attr_reader :barman_home
+
+    # Creates a new instance of CliCommand
+    # @param [String] path_to_binary see {#binary}. If nil, it will be initialized from {Configuration}
+    # @param [String] path_to_barman_home see {#barman_home}. If nil, it will be initialized from {Configuration}
     def initialize(path_to_binary=nil, path_to_barman_home=nil)
       self.binary=path_to_binary || Configuration.instance.binary
       self.barman_home=path_to_barman_home || Configuration.instance.barman_home
@@ -20,19 +41,34 @@ module RBarman
       @barman_home = path
     end
 
-    def backup(server, backup_id, with_wal_files=true)
+    # Instructs barman to get information about a specific backup
+    # @param [String] server server name
+    # @param [String] backup_id id of the backup
+    # @param [Hash] opts options for creating a {Backup}
+    # @option opts [Boolean] :with_wal_files whether to include {WalFiles} in each {Backup}
+    # @return [Backup] a new {Backup} object
+    # @raise [ArgumentError] if backup_id is nil
+    def backup(server, backup_id, opts = {})
       raise(ArgumentError, "backup id must not be nil!") if backup_id.nil?
-      return backups(server, with_wal_files, backup_id)[0]
+      opts[:backup_id] = backup_id
+      return backups(server, opts)[0]
     end
 
-    def backups(server, with_wal_files=true, backup_id=nil)
+    # Instructs barman to get information about backups
+    # @param [String] server server name
+    # @param [String] backup_id when given, only information about this backup id will be retrieved
+    # @param [Hash] opts options for creating {Backups}
+    # @option opts [Boolean] :with_wal_files whether to include {WalFiles} in each {Backup}
+    # @option opts [String] :backup_id retrieve just one {Backup} specified by this backup id
+    # @return [Backups] an array of {Backup}
+    def backups(server, opts = {})
       list = run_barman_command("list-backup #{server}")
-      list = list.grep(/#{backup_id}/) if !backup_id.nil?
+      list = list.grep(/#{opts[:backup_id]}/) if !opts[:backup_id].nil?
 
       backups = parse_backup_list(list)
       backups.each do |backup|
         parse_backup_info_file(backup)
-        if with_wal_files
+        if opts[:with_wal_files]
           wals = wal_files(backup.server, backup.id)
           wals.each { |w| backup.add_wal_file(w) }
         end
@@ -40,6 +76,42 @@ module RBarman
       return backups
     end
 
+    # Instructs barman to get information about a server
+    # @param [String] name name of the server
+    # @param [Hash] opts options for creating {Server}
+    # @option opts [Boolean] :with_backups whether to include {Backups} in {Server}
+    # @option opts [Boolean] :with_wal_files whether to include {WalFiles} in each {Backup}
+    # @return [Server] a new {Server}
+    def server(name, opts = {})
+      lines = run_barman_command("show-server #{name}")
+      server = parse_show_server_lines(name, lines)
+      lines = run_barman_command("check #{name}")
+      parse_check_lines(server, lines)
+      server.backups = backups(server.name, opts) if opts[:with_backups]
+      return server
+    end
+
+    # Instructs barman to get information about all servers
+    # @param [Hash] opts options for creating {Servers}
+    # @option opts [Boolean] :with_backups whether to include {Backups}
+    # @option opts [Boolean] :with_wal_files whether to include {WalFiles}
+    # @return [Servers] an array of {Server}
+    def servers(opts = {})
+      result = Servers.new
+      lines = run_barman_command("list-server")
+      server_names = parse_list_server_lines(lines)
+      server_names.each do |name|
+        result << server(name, opts)
+      end
+      return result
+    end
+
+    # Instructs barman to list all wal files for a specific backup id
+    # @param [String] server server name
+    # @param [String] backup_id id of the backup
+    # @return [WalFiles] an array of {WalFile}
+    # @raise [RuntimeError] if wal file duplicates are found in xlog.db
+    # @raise [RuntimeError] if barman lists a wal file but no information could be found in xlog.db
     def wal_files(server, backup_id)
       lines = run_barman_command("list-files --target wal #{server} #{backup_id}")
       wal_files = parse_wal_files_list(lines)
@@ -54,6 +126,65 @@ module RBarman
       return wal_files
     end
 
+
+    # Parses lines reported by barman's `list-server`
+    # @param [Array<String>] lines an array of lines from output of barman's `list-server` cmd
+    # @return [Array<String>] an array of server names
+    def parse_list_server_lines(lines)
+      result = Array.new
+      lines.each do |l|
+        result << l.split("-")[0].strip
+      end
+      return result
+    end
+
+
+    # Creates a {Server} object by parsing lines reported by barman's `show-server`
+    # @param [String] server name of the server
+    # @param [Array<String>] lines an array of lines from output of barman's `show-server` cmd
+    # @return [Server] a new {Server} object
+    def parse_show_server_lines(server, lines)
+      s = Server.new(server)
+      lines.each do |l|
+        key, value = l.gsub("\t","").split(": ")
+        case key.chomp
+        when "active"
+          s.active = value.to_bool
+        when "ssh_command"
+          s.ssh_cmd = value
+        when "conninfo"
+          s.conn_info = value
+        when "backup_directory"
+          s.backup_dir = value
+        when "basebackups_directory"
+          s.base_backups_dir = value
+        when "wals_directory"
+          s.wals_dir = value
+        end
+      end
+      return s
+    end
+
+    # Parses lines reported by barman's `check` and assigns according values
+    # @param [Server] server the server
+    # @param [Array<String>] lines an array of lines from output of barman's `check` cmd
+    # @raise [ArgumentError] if server is nil
+    def parse_check_lines(server, lines)
+      raise(ArgumentError, 'arg server not of type Server') if !server.is_a? Server
+      lines.each do |l|
+        key, value = l.gsub("\t","").split(": ")
+        case key.chomp
+        when "ssh"
+          server.ssh_check_ok = value == "OK" ? true : false
+        when "PostgreSQL"
+          server.pg_conn_ok = value == "OK" ? true : false
+        end
+      end
+    end
+
+    # Creates a {WalFiles} object by parsing lines reported by barman
+    # @param [Array<String>] lines an array of lines like '/var/lib/barman/test/wals/00000001000005A9/00000001000005A9000000BC'
+    # @return [WalFiles] the {WalFiles}
     def parse_wal_files_list(lines)
       wal_files = Array.new
       lines.each do |line|
@@ -62,6 +193,9 @@ module RBarman
       return wal_files
     end
 
+    # Creates an array of {Backup} by parsing lines reported by barman
+    # @param [Array<String>] lines an array of lines like 'test 20130218T080002 - Mon Feb 18 18:11:16 2013 - Size: 213.0 GiB - WAL Size: 130.0 GiB'
+    # @return [Array<Backup>] an array of {Backup}
     def parse_backup_list(lines)
       result = Array.new
       lines.each do |l|
@@ -75,14 +209,20 @@ module RBarman
         
         if b.status == :done
           sizematch = l.match(/.+Size:\s(.+)\s(.+)\s-.+Size:\s(.+)\s(.+)/)
-          b.size = size_in_bytes(sizematch[1].to_f, sizematch[2])
-          b.wal_file_size = size_in_bytes(sizematch[3].to_f, sizematch[4])
+          b.size = CliCommand.size_in_bytes(sizematch[1].to_f, sizematch[2])
+          b.wal_file_size = CliCommand.size_in_bytes(sizematch[3].to_f, sizematch[4])
         end
         result << b
       end
       return result
     end
 
+    # Assigns various values to a {Backup} by parsing the according "backup.info"
+    # @param [Backup] backup the backup
+    # @return [void]
+    # @raise [ArgumentError] if backup is not of type {Backup}
+    # @raise [ArgumentError] if backup.id is not set
+    # @raise [ArgumentError] if backup.server is not set
     def parse_backup_info_file(backup)
       raise(ArgumentError, "arg not of type Backup") if !backup.is_a? Backup
       raise(ArgumentError, "Backup.id not set") if backup.id.nil?
@@ -111,6 +251,10 @@ module RBarman
       end
     end
 
+    # Assigns size, created and compression values to a {WalFile} by parsing a line from xlog.db
+    # @param [WalFile] wal_file the wal file
+    # @param [String] line a string like '00000001000005A9000000BC\\t4684503\t1360568429.0\\tbzip2'
+    # @return [void]
     def wal_file_info_from_xlog_db_line(wal_file, line)
       splitted = line.split("\t")
       wal_file.size = splitted[1]
@@ -118,10 +262,18 @@ module RBarman
       wal_file.compression = splitted[3].downcase.to_sym
     end
 
-    def size_in_bytes(size, identifier)
-      raise(ArgumentError, "identifier not one of B|KiB|MiB|GiB|TiB") if !identifier.match(/(B|KiB|MiB|GiB|TiB)/)
+    # Converts the size according to the unit to bytes
+    # @param [Numeric] size the size
+    # @param [String] unit the unit, like `B`, `KiB`, `MiB`, `GiB` or `TiB`
+    # @return [Integer] the size in bytes
+    # @raise [ArgumentError] if unit is not one of B|KiB|MiB|GiB|TiB
+    # @example
+    #   CliCommand.size_in_bytes(2048, 'B') #=> 2048
+    #   CliCommand.size_in_bytes(2048, 'MiB') #=> 2048 * 1024 ** 2
+    def self.size_in_bytes(size, unit)
+      raise(ArgumentError, "unit not one of B|KiB|MiB|GiB|TiB") if !unit.match(/(B|KiB|MiB|GiB|TiB)/)
       size_b = 0
-      case identifier
+      case unit 
       when "B"
         size_b = size
       when "KiB"
@@ -136,10 +288,17 @@ module RBarman
       return size_b.to_i
     end
 
+    # Instructs barman to delete a specific backup
+    # @param [String] server server name
+    # @param [String] backup_id id of the backup
+    # @return [void]
     def delete(server, backup_id)
       run_barman_command("delete #{server} #{backup_id}")
     end
 
+    # Instructs barman to create a backup
+    # @param [String] server server name
+    # @return [void]
     def create(server)
       run_barman_command("backup #{server}")
     end

data/lib/rbarman/configuration.rb

@@ -1,25 +1,39 @@
 require 'singleton'
 
 module RBarman
+
+  # A very flexible configuration class, to be used as Singleton
   class Configuration
     include Singleton 
 
+    # Creates a new instance of {Configuration}
+    # @param [Hash] data added as configuration parameters
     def initialize(data={})
       @data = {}
       update!(data)
       basic_configuration
     end
 
+    # Adds parameters
+    # @param [Hash] data parameters to add
+    # @return [void]
     def update!(data)
       data.each do |key, value|
         self[key] = value
       end
     end
 
+    # Gives access to parameters
+    # @param [String,Symbol] key the key
+    # @return [Object, nil] the value
     def [](key)
       @data[key.to_sym]
     end
 
+    # Adds a new parameter
+    # @param [String] key the key
+    # @param [Object] value the value
+    # @return [void]
     def []=(key, value)
       if value.class == Hash
         @data[key.to_sym] = Config.new(value)
@@ -28,6 +42,16 @@ module RBarman
       end
     end
 
+    # For catching [NoMethodError] and trying to add a new parameter or returning a parameter value, based on the "missing" method name
+    # @param [Symbol] sym the method name
+    # @param [Array] args the arguments passed to the method.
+    # @return [Object, nil, void] when method name doesn't end with an `=` operator, a parameter value will be returned (if found, otherwise nil)
+    # @example
+    #   Configuration.instance[:some_key] = "some_value"
+    #   Configuration.instance.some_key #=> "some_value"
+    #   Configuration.instance.another_key = { :a => 1 }
+    #   Configuration.instance[:another_key] #=> { :a => 1}
+    #   Configuration.instance[:missing] #=> nil
     def method_missing(sym, *args)
       if sym.to_s =~ /(.+)=$/
         self[$1] = args.first
@@ -36,6 +60,11 @@ module RBarman
       end
     end
 
+    # adds `:binary` with path to barman binary as value and `:barman_home` (default $HOME) with path to barman's backup base directory as value. If `which` reports a path for barman, that path will be used, otherwise `/usr/bin/barman`
+    # @return [void]
+    # @example
+    #  Configuration.Instance.binary #=> "/usr/bin/barman"
+    #  Configuration.Instance.barman_home #=> "/var/lib/barman"
     def basic_configuration
       b_path = `which barman`.chomp
       self[:binary] = b_path.empty? ? '/usr/bin/barman' : b_path

data/lib/rbarman/server.rb

@@ -0,0 +1,83 @@
+# @author Holger Amann <holger@sauspiel.de>
+
+module RBarman
+
+  # Represents a server for which barman should do/have backups
+  class Server
+
+    # @param [String] name name of the server
+    # @return [String] name of the server
+    attr_accessor :name
+
+    # @param [Boolean] active if server is active
+    # @return [Boolean, nil] if server is active
+    attr_accessor :active
+
+    # @param [String] cmd ssh command
+    # @return [String, nil] the ssh command
+    attr_accessor :ssh_cmd
+
+    # @param [String] the connection info
+    # @return [String, nil] the connection info
+    attr_accessor :conn_info
+
+    # @param [String] path to backup directory
+    # @return [String, nil] the path to backup directory
+    attr_accessor :backup_dir
+
+    # @param [String] path to base backups directory
+    # @return [String, nil] the path to base backups directory
+    attr_accessor :base_backups_dir
+
+    # @param [String] path to wals directory
+    # @return [String, nil] the path to wals directory
+    attr_accessor :wals_dir
+
+    # @param [Boolean] if SSH connection is working
+    # @return [Boolean, nil] if SSH connection is working
+    attr_accessor :ssh_check_ok
+
+    # @param [Boolean] if PostgreSQL connection is working
+    # @return [Boolean, nil] if PostgreSQL connection is working
+    attr_accessor :pg_conn_ok
+
+    # @param [Backups] server backups
+    # @return [Backups, nil] server backups
+    attr_accessor :backups
+
+
+    # Creates a new instance of {Server}
+    def initialize(name)
+      @name = name
+    end
+
+    # Instructs the underlying (barman) command to get information about a server
+    # @param [String] name name of the server
+    # @param [Hash] opts options for creating {Server}
+    # @option opts [Boolean] :with_backups whether to include {Backups}
+    # @option opts [Boolean] :with_wal_files whether to include {WalFiles} in each {Backup}
+    def self.by_name(name, opts = {})
+      cmd = CliCommand.new
+      return cmd.server(name, opts)
+    end
+  end
+
+  # An array of {Server}
+  class Servers < Array
+    # Initializes a new Array of {Server}
+    # @param [Array, Servers] other appends all servers from another array
+    def initialize(other=nil)
+      self.concat(other) if !other.nil? and other.is_a? Array
+    end
+
+    # Instructs the underlying (barman) command to get all servers
+    # @param [Hash] opts options for creating {Servers}
+    # @option opts [Boolean] :with_backups whether to include {Backups}
+    # @option opts [Boolean] :with_wal_files whether to include {WalFiles}
+    # @return [Servers] an array of {Server}
+    def self.all(opts={})
+      cmd = CliCommand.new
+      return Servers.new(cmd.servers(opts))
+    end
+  end
+end

data/lib/rbarman/string.rb

@@ -0,0 +1,7 @@
+class String
+  def to_bool
+    return true if self == true || self =~ (/\A(true|t|yes|y|1)\Z/i)
+    return false if self == false || self.empty? || self =~ (/\A(false|f|no|n|0)\Z/i)
+    raise ArgumentError.new("invalid value for Boolean: \"#{self}\"")
+  end
+end

data/lib/rbarman/version.rb

@@ -1,3 +1,3 @@
 module RBarman
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/rbarman/wal_file.rb

@@ -1,14 +1,62 @@
 require 'time'
 
+# @author Holger Amann <holger@sauspiel.de>
 module RBarman
 
   class InvalidWalFileNameError < RuntimeError
   end
 
+  # Represents a wal file
   class WalFile
 
-    attr_reader :timeline, :xlog, :segment, :created, :compression, :size
-
+    # @overload timeline
+    #   @return [String, nil] timeline part of the wal file
+    # @overload timeline=
+    #   Timeline part of the wal file
+    #   @param [#to_s] timeline the timeline part
+    #   @raise [ArgumentError] if timeline length != 8
+    attr_reader :timeline 
+
+    # @overload xlog 
+    #   @return [String, nil] xlog part of the wal file
+    # @overload xlog=
+    #   xlog part of the wal file
+    #   @param [#to_s] xlog the xlog part 
+    #   @raise [ArgumentError] if xlog length != 8
+    attr_reader :xlog
+
+    # @overload segment
+    #   @return [String, nil] segment part of the wal file
+    # @overload segment=
+    #   segment part of the wal file
+    #   @param [#to_s] segment the segment part 
+    #   @raise [ArgumentError] if segment length != 8
+    attr_reader :segment
+
+    # @overload created
+    #   @return [Time, nil] time when wal file has been created
+    # @overload created=
+    #   Time when wal file has been created
+    #   @param [Time,Numeric,String] created the time
+    attr_reader :created
+
+    # @overload compression
+    #   @return [Symbol, nil] compression type of wal file, `:none`, `:gzip`, `:bzip2`, `:custom`
+    # @overload compression=
+    #   Compression type of wal file
+    #   @param [Symbol] compression compression type
+    #   @raise [ArgumentError] if compression is not one of `:none`, `:gzip`, `:bzip2`, `:custom`
+    attr_reader :compression
+
+
+    # @overload size
+    #   @return [Integer, nil] size of wal file (in bytes)
+    # @overload size=
+    #   Size of wal file (in bytes)
+    #   @param [#to_i] size size of wal file (in bytes)
+    attr_reader :size
+
+    # Creates a new instance of {WalFile}
     def initialize
     end
 
@@ -48,6 +96,11 @@ module RBarman
       @created = Time.parse(created) if created.is_a? String
     end
 
+    # Creates a new WalFile from the given argument
+    # @param [String, WalFile] name the wal file name
+    # @return [WalFile] the created WalFile
+    # @raise [InvalidWalFileNameError] if name is a string and string's length isn't exactly 24 chars or
+    #   name could not be splitted in 3 parts (timeline|xlog|segment)
     def self.parse(name)
       raise(InvalidWalFileNameError, "name has to be exactly 24 chars") if !name.is_a? WalFile and name.to_s.size != 24 
 
@@ -66,6 +119,9 @@ module RBarman
       return wal_file
     end
 
+    # Checks if other is equal to self by comparing timeline, xlog and segment
+    # @param [String, WalFile] other other wal file
+    # @return [Boolean] if other is equal to self
     def ==(other)
       o = other
       o = WalFile.parse(other.to_s) if !other.is_a? WalFile

data/lib/rbarman/wal_files.rb

@@ -0,0 +1,22 @@
+# @author Holger Amann <holger@sauspiel.de>
+module RBarman
+
+  # An Array of WalFile
+  class WalFiles < Array
+
+    # Initializes a new Array of {WalFile}
+    # @param [Array,WalFiles] other appends all wal files from another array
+    def initialize(other=nil)
+      self.concat(other) if !other.nil? and other.is_a? Array
+    end
+
+    # Instructs the underlying (barman) command to get all wal files for a specific backup id
+    # @param [String] server server name
+    # @param [String] backup_id id of the backup
+    # @return [WalFiles] an array of {WalFile}
+    def self.by_id(server, backup_id)
+      cmd = CliCommand.new
+      return WalFiles.new(cmd.wal_files(server, backup_id))
+    end
+  end
+end

data/lib/rbarman.rb

@@ -1,9 +1,13 @@
+require "rbarman/string"
 require "rbarman/version"
 require "rbarman/backup"
 require "rbarman/backups"
 require "rbarman/wal_file"
+require "rbarman/wal_files"
 require "rbarman/cli_command"
 require "rbarman/configuration"
+require "rbarman/server"
 
+# The RBarman module contains all aspects of backups made by barman and dealing with them
 module RBarman
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbarman
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-09 00:00:00.000000000 Z
+date: 2013-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -75,7 +75,7 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 1.1.0
-description: Wrapper about 2ndQuadrant's postgresql backup tool \'barman\'
+description: Wrapper about 2ndQuadrant's postgresql backup tool 'barman'
 email:
 - holger@sauspiel.de
 executables: []
@@ -86,8 +86,11 @@ files:
 - lib/rbarman/backups.rb
 - lib/rbarman/cli_command.rb
 - lib/rbarman/configuration.rb
+- lib/rbarman/server.rb
+- lib/rbarman/string.rb
 - lib/rbarman/version.rb
 - lib/rbarman/wal_file.rb
+- lib/rbarman/wal_files.rb
 - lib/rbarman.rb
 - LICENSE.txt
 - README.md
@@ -115,5 +118,6 @@ rubyforge_project:
 rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Wrapper about 2ndQuadrant's postgresql backup tool \'barman\'
+summary: Wrapper about 2ndQuadrant's postgresql backup tool 'barman'
 test_files: []
+has_rdoc: