Criar  Editar  FrontPage  Índices  Buscar  Alterações  History  RSS  Back  Login

Gda::Connection Diff - Ruby-GNOME2 Project Website

  • Added parts are displayed like this.
  • Deleted parts are displayed like this.

= class Gda::Connection
The Gda::Connection class offers access to all operations involving an
opened connection to a database. Gda::Connection objects are obtained via
the Gda::Client class.

Once obtained, applications can use GdaConnection to execute commands, run
transactions, and get information about all objects stored in the
underlying database.

== Object Hierarchy
* Object
  * GLib::Instantiatable
    * GLib::Object
      * Gda::Connection

== Instance Methods
--- add_errors(*errors)
    Adds one or more errors to the connection. This method is usually called by
    providers, to inform clients of errors that happened during some operation.
    As soon as this method is called, the connection object (and the associated
    Gda::Client object) emits the "error" signal, to which clients can connect
    to be informed of errors.
    * errors: one or several Gda::Error objects.  
    * Returns: self.

--- begin_transaction(xaction)
    Starts a transaction on the data source, identified by the xaction
    parameter.
    Before starting a transaction, you can check whether the underlying provider
    does support transactions or not by using the Gda::Connection#supports?
    method.
    * xaction: a Gda::Transaction object.  
    * Returns: true if the transaction was started successfully, false otherwise.

--- change_database(name)
    Changes the current database for the given connection. This operation is
    not available in all providers.
    * name: name of the database to switch to.  
    * Returns: true if successful, false otherwise.

--- clear_errors
    This method lets you clear the list of Gda::Error's of the
    current connection. This is useful to reuse a Gda::Connection
    because next uses of Gda::Connection#errors will return an empty
    list.
    * Returns: self.

--- client
    Gets the Gda::Client object associated with a connection. This is always the
    client that created the connection, as returned by
    Gda::Client#open_connection.
    * Returns: the Gda::Client to which the connection belongs to.

--- client=(client)
    Associates a Gda::Client with this connection. This method is not intended
    to be called by applications.
    * client: a Gda::Client object.  
    * Returns: the given parameter 'client'.

--- close
    Closes the connection to the underlying data source. After calling this
    method, you should not use anymore the Gda::Connection object, since it may
    have been destroyed.
    * Returns: nil.

--- cnc_string
    Gets the connection string used to open this connection.
    The connection string is the string sent over to the underlying database
    provider, which describes the parameters to be used to open a connection on
    the underlying data source.
    * Returns: the connection string used when opening this connection.

--- commit_transaction(xaction)
    Commits the given transaction to the backend database. You need to do
    Gda::Connection#begin_transaction first.
    * xaction: a Gda::Transaction object.  
    * Returns: true if the transaction was finished successfully, false otherwise.

--- create_database(name)
    Creates a new database on the connection.
    * name: database name.  
    * Returns: true if successful, false otherwise.

--- create_table(name, attributes)
    Creates a table on the current connection from the given set of fields.
    * name: the name of the table to create.
    * attributes: an array of Gda::FieldAttributes objects.  
    * Returns: true if successful, false otherwise.

--- database
    This method returns the name of the currently active database in the connection.
    * Returns: the name of the currently active database in the connection.

--- drop_database(name)
    Drops a database from the connection.
    * name: database name.  
    * Returns: true if successful, false otherwise.

--- drop_table(name)
    Drops a table from the database.
    * name: the name of the table to drop.  
    * Returns: true if successful, false otherwise.

--- dsn
    This method returns the data source name the connection object is connected to.
    * Returns: the data source name the connection object is connected to.

--- errors
    Retrieves a list of the last errors ocurred in the connection.
    * Returns: an Array of Gda::Error objects.

--- execute(cmd, params=nil)
    Synonym for Gda::Connection#execute_single_command.
    * cmd: a Gda::Command object.
    * params: parameters, as a Gda::ParameterList object.  
    * Returns: a Gda::DataModel containing the data returned by the data source, or nil on error.

--- execute_command(cmd, params=nil)
    Executes a command on the underlying data source.
    This method provides the way to send several commands at once to the data
    source being accessed by the Gda::Connection. The Gda::Command specified
    can contain a list of commands in its "text" property (usually a set of SQL
    commands separated by ';').
    * cmd: a Gda::Command object.
    * params: parameters, as a Gda::ParameterList object.  
    * Returns: an Array of Gda::DataModel objects, as returned by the underlying provider.

--- execute_non_query(cmd, params=nil)
    Executes a single command on the underlying database, and gets the number
    of rows affected.
    * cmd: a Gda::Command object.
    * params: parameters, as a Gda::ParameterList object.  
    * Returns: the number of affected rows by the executed command, or -1 on error.

--- execute_single_command(cmd, params=nil)
    Executes a single command on the given connection.
    This method lets you retrieve a simple data model from the underlying
    difference, instead of having to retrieve a list of them, as is the case
    with Gda::Connection#execute_command.
    * cmd: a Gda::Command object.
    * params: parameters, as a Gda::ParameterList object.  
    * Returns: a Gda::DataModel containing the data returned by the data source, or nil on error.

--- get_schema(schema, params=nil)
    Asks the underlying data source for a list of database objects.
    This is the method that lets applications ask the different providers
    about all their database objects (tables, views, procedures, etc).
    The set of database objects that are retrieved are given by the 2 parameters
    of this method: 'schema' (which specifies the specific schema required) and
    'params' (which is a list of Gda::Parameter objects that can be used to give
    more detail about the objects to be returned).
    The list of parameters is specific to each schema type.
    * schema: database schema to get (see ((<GdaConnectionSchema|Gda::Connection#GdaConnectionSchema>))).
    * params: an optional Gda::ParameterList object.  
    * Returns: a Gda::DataModel containing the data required if successful,  nil otherwise.

--- opened?
    Checks whether a connection is open or not.
    * Returns: true if the connection is open, false if it is not.

--- options
    This method returns the ((<GdaConnectionOptions|Gda::Connection#GdaConnectionOptions>)) used to open this connection.
    * Returns: the ((<GdaConnectionOptions|Gda::Connection#GdaConnectionOptions>)) used to open this connection.

--- password
    This method returns the pass word used to open this connection.
    * Returns: the pass word used to open this connection.

--- provider
    This method returns the provider ID used to open this connection.
    * Returns: the provider ID used to open this connection.

--- reset!
    Resets the connection.
    * Returns: true if successful, false otherwise.

--- rollback_transaction(xaction)
    Rollbacks the given transaction. This means that all changes made to the
    underlying data source since the last call to
    Gda:Connection#begin_transaction or Gda::Connection#commit_transaction
    will be discarded.
    * xaction: a Gda::Transaction object.  
    * Returns: true if the operation was successful, false otherwise.

--- server_version
    This method returns the version string of the underlying database server.
    * Returns: the version string of the underlying database server.

--- set_client(client)
    Associates a Gda::Client with this connection. This method is not intended
    to be called by applications.
    * client: a Gda::Client object.  
    * Returns: self.

--- supports?(feature)
    Asks the underlying provider for if a specific feature is supported.
    * feature: feature to ask for (see ((<GdaConnectionFeature|Gda::Connection#GdaConnectionFeature>))).  
    * Returns: true if the provider supports it, false if not.

--- username
    This method returns the user name used to open this connection.
    * Returns: the user name used to open this connection.

== Constants
=== GdaConnectionFeature
--- FEATURE_AGGREGATES
--- FEATURE_BLOBS
--- FEATURE_INDEXES
--- FEATURE_INHERITANCE
--- FEATURE_NAMESPACES
--- FEATURE_PROCEDURES
--- FEATURE_SEQUENCES
--- FEATURE_SQL
--- FEATURE_TRANSACTIONS
--- FEATURE_TRIGGERS
--- FEATURE_UPDATABLE_CURSOR
--- FEATURE_USERS
--- FEATURE_VIEWS
--- FEATURE_XML_QUERIES

=== GdaConnectionOptions
--- OPTIONS_DONT_SHARE
--- OPTIONS_READ_ONLY

=== GdaConnectionSchema
--- SCHEMA_AGGREGATES
--- SCHEMA_DATABASES
--- SCHEMA_FIELDS
--- SCHEMA_INDEXES
--- SCHEMA_LANGUAGES
--- SCHEMA_NAMESPACES
--- SCHEMA_PARENT_TABLES
--- SCHEMA_PROCEDURES
--- SCHEMA_SEQUENCES
--- SCHEMA_TABLES
--- SCHEMA_TRIGGERS
--- SCHEMA_TYPES
--- SCHEMA_USERS
--- SCHEMA_VIEWS

== Signals
--- error

== See Also
((<Gda>)).

- ((<lrz>))