NAME

Sphinx::Config::Builder - Perl extension dynamically creating Sphinx configuration files on the fly, using a backend datasource to drive the indexes, sources, and their relationships.

VERSION

This module is being released as version 1.02.

SYNOPSIS

        use Sphinx::Config::Builder;
        my $INDEXPATH = q{/path/to/indexes};
        my $XMLPATH   = q{/path/to/xmlpipe2/output};
        
        my $builder = Sphinx::Config::Builder->new();
        
        # %categories may be stored elsewhere, e.g. a .ini file or MySQL database
        my $categories = { cars => [qw/sedan truck ragtop/], boats => [qw/sail row motor/] };
        foreach my $category ( keys %$categories ) {
            foreach my $document_set ( @{ $categories->{$category} } ) {
                my $xmlfile     = qq{$document_set-$category} . q{.xml};
                my $source_name = qq{$document_set-$category} . q{_xml};
                my $index_name  = qq{$document_set-$category};
                my $src         = Sphinx::Config::Entry::Source->new();
                my $index       = Sphinx::Config::Entry::Index->new();
        
                $src->name($source_name);
                $src->kv_push(
                    { type            => q{xmlpipe} },
                    { xmlpipe_command => qq{/bin/cat $XMLPATH/$xmlfile} },
                );
        
                $builder->push_source($src);
        
                $index->name($index_name);
                $index->kv_push(
                    { source       => qq{$source_name} },
                    { path         => qq{$INDEXPATH/$document_set} },
                    { charset_type => q{utf-8} },
                  );
        
                $builder->push_index($index);
            }
        }
        $builder->indexer->kv_push( { mem_limit => q{64m} } );
        $builder->searchd->kv_push(
            { compat_sphinxql_magics => 0 },
            { listen                 => q{192.168.0.41:9312} },
            { listen                 => q{192.168.0.41:9306:mysql41} },
            { log                    => q{/var/log/sphinx/searchd.log} },
            { query_log              => q{/var/log/sphinx/log/query.log} },
            { read_timeout           => 30 },
            { max_children           => 30 },
            { pid_file               => q{/var/log/sphinx/searchd.pid} },
            { seamless_rotate        => 1 },
            { preopen_indexes        => 1 },
            { unlink_old             => 1 },
            { workers     => q{threads} },           # for RT to work
            { binlog_path => q{/var/log/sphinx} },
        );
        
        print $builder->as_string;

This script may now be passed to the Sphinx indexer using the --config option:

 $ indexer --config /path/to/gen_config.pl --all --rotate

DESCRIPTION

The motivation behind this module is the need to manage many indexes and corresponding sources handled by a single Sphinx searchd instance. Managing a configuration file with many indexes and sources quickly becomes unweildy, and a programatic solution is necessary. Using Sphinx::Config::Builder, one may more easily manage Sphinx configurations using a more appropriate backend (e.g., a simple .ini file or even a MySQL database). This is particularly useful if one is frequently adding or deleting indexes and sources. This approach is particularly useful for managing non-natively supported Sphinx datasources that might require the additional step of generating XMLPipe/Pipe2 sources.

This module doesn't read in Sphinx configuration files, it simply allows one to construct and output a configuration file programmtically.

This module allows one to systematically construct a Sphinx configuration file that contains so many entries that it is best created dynamically. It's fairly low level, and provides containers for the following:

A list of Sphinx::Config::Entry::Index objects, one per index section;
A list of Sphinx::Config::Entry::Source objects, one per source section;
A singular Sphinx::Config::Entry::Indexer object, one per configuration for indexer options
A singular Sphinx::Config::Entry::Searchd object, one per configuration for searchd options

The general idea is that one builds up a list of index sections and corresponding source sections. One then defines the indexer and searchd options. One is not bound to specific keywords in each section, meaning that they may add any key/value pair (as a singleton HASH referece). Each key/value pair corresponds to a key/value line in each section.

All Sphinx::Config::Entry derived classes implement a as_string method. This method outputs the section in the format that Sphinx expects. The overall Sphinx::Config::Builder class has a as_string method that will iterate over all members, calling their as_string method. The result is the full configuration file that may be printed to STDOUT for the indexer to consume using the --config option.

SUBROUTINES/METHODS

Sphinx::Config::Builder

new

Highest level constructor.

push_index

Push a reference of Sphinx::Config::Entry::Index into builder.

pop_index

Pop a reference of Sphinx::Config::Entry::Index into builder.

push_source

Push a reference of Sphinx::Config::Entry::Source into builder.

pop_source

Pop a reference of Sphinx::Config::Entry::Source into builder.

index_list

Get container list of all Index references.

source_list

Get container list of all Source references.

indexer

Get Sphinx::Config::Entry::Indexer member reference.

sourced

Get Sphinx::Config::Entry::Searchd member reference.

as_string

Calls as_string method for all members of the builder object, which results in the entire configuration file.

Sphinx::Config::Entry::Index and Sphinx::Config::Entry::Source

new

Constructor.

kv_push

Push key/value HASH ref into Index, Source list.

kv_pop

Pop key/value HASH ref from Index, Source list.

as_string

Return string reprentation of Index, Source.

name

Set name of Index, Source.

Sphinx::Config::Entry::Indexer and Sphinx::Config::Entry::Searchd

new

Constructor.

kv_push

Push key/value HASH ref into Indexer, Searchd.

kv_pop

Pop key/value HASH ref from Indexer, Searchd.

as_string

Return string representation of Indexer, Searchd.

DEPENDENCIES

None.

DIAGNOSTICS

There is no validation, garbage in, garbage out.

CONFIGURATION AND ENVIRONMENT

None.

INCOMPATIBILITIES

None.

BUGS AND LIMITATIONS

Please report - https://github.com/estrabd/perl-Sphinx-Config-Builder/issues

AUTHOR

B. Estrade, <estrabd@gmail.com>

LICENSE AND COPYRIGHT

Same terms as Perl itself.