[Hiki] update - tut-libgda-config (ruby-gnome2-doc-cvs) - Ruby-GNOME2

-------------------------
REMOTE_ADDR = 195.207.101.112
REMOTE_HOST = 
        URL = http://ruby-gnome2.sourceforge.jp/en/?tut-libgda-config
-------------------------
  = Configuring
+ {{link("tut-libgda-install", nil, "tut-libgda", "tut-libgda-init")}}

  Depending on the use you're going to get out of Ruby/Libgda, you may have to dig deep into its internals, but don't be afraid, things have been implemented to be easy to use.

  == Configuration for development

  The only step you need to do to make sure everything is well installed, is to check that Ruby/Libgda library is seen by your system:

    $ irb --simple-prompt -r libgda
    >> Gda.init("test", "0.0.0")
    => nil

  == Configuration for accessing a database

  If you want to access a data source through a GDA  provider, you must first of all have access to this provider, and most importantly, this provider should have access to its specific data source. So, first have your database up and running. For this, you'll have to check your specific data source documentation, or see the libgda providers' specific documentation.

  Once you've got your GDA provider installed, whether on your machine or on another one on the network, you must configure your local system to have access to it. If you're on a local installation, once you have installed the GDA provider (by compiling it or by installing its RPM or Debian package), the provider is visible in your machine. This is because the provider installs itself in a well known location that makes libgda  itself know about the new provider.

  Then, the next step is to configure the data sources you want available on your system. For doing this, you should, as for now, use GNOME-DB, which is a front-end to libgda for the ((<GNOME project|URL:http://www.gnome.org>)).

  One of the problem GDA solves is the naming of data sources. Every database system has it's own way of defining names for it's databases. For example MySQL uses the hostname, port number, and the name of the database. Other databases, like Solid use the hostname and port number only. There is no support for multiple databases per server. Because the client does not need all these details, the libgda configuration defines all the properties of such a data source, so that the correct data base server can be contacted. This information is accessed by the client library and sent to the provider, which in turn will parse the string to decide which database must be connected to. The data stored for each data source is as follows: 

    Provider=MySQL                                       (1)                            
    DSN=DATABASE=test;HOST=localhost;PORT=1111           (2)
    Description=MySQL Test Database in native mode       (3)
    Username=username                                    (4)
    Password=password                                    (5)

  :1
   The provider for this database is the gda-mysql provider. The value of this entry is used as the object ID for the plug-in activation. 

  :2
   This is the most important entry. The value of this entry is the string sent to the provider so that it knows which datasource to access. How this entry is interpreted by the providers is described in the provider section (at the end of this page). 

   There are, though, a set of default properties that can be used for the connection string for all providers. Those are:
     * USERNAME: user name to be used for authentication.
     * PASSWORD: password to be used for authentication.

  :3
   The value of this entry is a short description of the datasource. It is here for convenience only and it is not used for any purpose. 

  :4
   The user name to be used when connecting to the database. 

  :5
   The password to be used when connecting to the database. This is stored in plain text, so be sure you restrict access to the configuration file (~/.libgda/config) to any "dangerous" users.

  The XML configuration file (~/.libgda/config) is not recommended to be modified by hand and, for our example, it is something like this:

    <?xml version="1.0"?>
    <libgda-config>
      <section path="/apps/libgda/Datasources/sales">
        <entry name="DSN" type="string" value="PORT=1111;DATABASE=test;HOST=localhost"/>
        <entry name="Description" type="string" value="MySQL Test Database in native mode"/>
        <entry name="Password" type="string" value="password"/>
        <entry name="Provider" type="string" value="MySQL"/>
        <entry name="Username" type="string" value="username"/>
      </section>
    </libgda-config>

  ===  Managing data sources with API methods  

  ====  Create data sources

  To create a data source you must use the methods Gda::DataSource.new and Gda::DataSource#save.

  Here you see how to create a data source named foo_ds. If you do not need to give an username or password to enter the database, you could put nil:

    datasource1 = Gda::DataSource.new("foo_ds", "PostgreSQL", "DATABASE=foo_db",
                                      "description of foo_ds", "foo_username, "foo_password")
    datasource2 = Gda::DataSource.new("other_foo_ds", "MySQL", "DATABASE=other_foo_db,HOST=db.foo.com",
                                      "description of other_foo_ds", "foo", nil)
    datasource1.save
    datasource2.save

  For more details about provider specific information see in the section about provider's specific information at the end of this page.

  There is no problem about calling several times Gda::DataSource#save because if you save an existing data source, it is replaced.

  ==== Removing data sources

  To remove a data source you must use the method Gda::DataSource#remove.

  Here you see how to remove a data source named foo_ds:

    datasource = Gda::DataSource.find('foo_ds')
    datasource.remove

  ==== Listing available data sources

  To list available data sources you should use methods Gda::DataSource.datasources or Gda::DataSource.each.

  Here you see a method which lists the available data sources:

    def list_datasources
        Gda::DataSource.each do |ds|
            puts "NAME: '#{ds.name}', PROVIDER: '#{ds.provider}', CNC: '#{ds.cnc_string}', " \
                 "USER: '#{ds.username}', PASSWORD: '#{ds.password}'."
        end
    end

  ==== Listing available providers

  To list available providers you should use methods Gda::Providers.providers or Gda::Providers.each.

  Here you see a method which lists available providers:

    def list_providers
        Gda::Provider.each { |provider| puts "ID: '#{provider.prov_id}'." }
    end

  == Provider's specific information

  To get more details about each provider specific information, you should browse ((<the dedicated section|URL:http://www.gnome-db.org/docs/libgda/installation-configuring.html#INSTALLATION-PROVIDER>)) in the GDA manual.

Ruby-GNOME2

[ruby-gnome2-doc-cvs] [Hiki] update - tut-libgda-config