Michael Lausch

Rodrigo Moya

Sean Allen

GDP compliance, FDL, added mark-up, English and syntax  

Xabier Rodriguez Calvar

How to begin and migration formulae  
Igalia, S.L.

Jose Dapena Paz

Some examples  
Igalia, S.L.

Bas Driessen

libgda, gda-postgres, gda-mysql  
Xobas Software

Daniel Espinosa Ortiz

libgda, Vala, GObject Introspection  

Vivien Malerba

Current maintainer  

for version 5.2.10

Copyright © 1999 - 2011 The GNOME Foundation

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found in the appendix.

Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps.

GNOME Data Access (GDA) is an architecture whose purpose is to provide universal access to many different kinds and types of data sources. This goes from traditional relational database systems, to any imaginable kind of data source such as a mail server, a LDAP directory...

This universality is obtained through the use of an easily extensible plug-in system as the mechanism for communication between the different components in the architecture.

I. Getting started
Introduction
Features
Architecture
Foreword about abstraction
Variables syntax in SQL
NULL handling when using variables
SQL identifiers
Binary large objects (BLOBs)
Installation
Getting the library
Installing from the sources
Compiling your code using the Libgda library
Configuring
Configuration for development
Configuration for accessing a database
Provider's specific information
Code examples
Initializing
Connecting
Executing queries
Managing data models
Example using random access
Example using an iterator
Freeing data models
Managing transactions
Managing connection's events and errors
Full example
DDL example
Binary large objects (BLOBs) example
Other examples
Migration from 1.X versions
GdaValue and GdaDataModel changes
GdaClient, GdaConnection and GdaError
Various API changes
Migration from 3.X versions
Overview
New unique parser
GdaQuery and GdaCommand merge into GdaStatement
Dictionary changes
Statement execution
Reports
Other changes
Multi threading environment
Configuration management
Database provider's changes
API changes
List of removed objects and interfaces
List of removed functions
Migration from 4.X versions
Overview
GDA_TYPE_NULL
Provider's notes
For Oracle
For SQLite
The gda_file_exists() function
The gda_hex_print() function
The gda_hex() function
The gda_rmdiacr() function
The gda_upper() and gda_lower() functions
The regexp_match() function
For SQLCipher
How to create and encrypted database
How to encrypt an existing plaintext database to an encrypted database file
How to change the passphrase of an encrypted database
How to decrypt an existing database to a plaintext database
For LDAP
Authentication
Mapping to GdaDataModel
For JDBC
How it works
JDBC drivers' location
Connection parameters
Limitations
Global limitations
For MySQL
Multi threaded environment
Statements execution
Timezone information
For Oracle
For PostgreSQL
BLOB handling
Last inserted row's values
Multi threaded environment
Statements execution
Timezone information
For SQLite
Last inserted row's values
Date and time
Timezone information
Multi threaded environment
Error reporting
For SQLCipher
For LDAP
User name
SSL/TLS certificate validation
For JDBC based providers
Last inserted row's values
Multi threaded environment
II. API reference
HOWTO for common tasks
Open a connection
Define a data source (DSN)
Build statements without using a parser
INSERT INTO customers (e, f, g) VALUES (##p1::string, 15, 'joe')
SELECT people.firstname AS person, people.lastname, "date" AS birthdate, age FROM people
SELECT c."date", name AS person FROM "select" AS c INNER JOIN orders USING (id)
UPDATE products set ref='A0E''FESP' WHERE id = 14
DELETE FROM items WHERE id = ##theid::int
SELECT myfunc (a, 5, 'Joe') FROM mytable
SELECT name FROM master WHERE id IN (SELECT id FROM subdata)
INSERT INTO customers (e, f, g) SELECT id, name, location FROM subdate
SELECT id, name FROM subdata1 UNION SELECT ident, lastname FROM subdata2
SELECT CASE tag WHEN 'Alpha' THEN 1 WHEN 'Bravo' THEN 2 WHEN 'Charlie' THEN 3 ELSE 0 END FROM data
SELECT product_id, name, sum (4 * 5 * price * 1.200000) FROM invoice_lines
SELECT id, name, adress, cntry_id, countries.name FROM customers INNER JOIN countries ON (countries.id = cntry_id)
Execute a SELECT command
Modify the result of a SELECT command
Execute an INSERT, UPDATE or DELETE command
Get the last inserted row
Execute a DDL command
Get information about a table's columns
Update the meta data about a table
Validate a DML statement
Control value's assignment to various objects
Add your own data to a GdaMetaStore
Object Hierarchy
Initialization and configuration
Library initialization — Library initialization and information
Configuration — Access/Management of libgda configuration
Configuring Libgda with environment variables
Connections & commands
GdaConnection — A connection to a database
GdaSqlParser — SQL parser
GdaSqlBuilder — Factory object for statements
GdaStatement — Single SQL statement
GdaRepetitiveStatement — Execute the same statement several times with different values
GdaBatch — Multiple SQL statements grouped together.
GdaHolder — Container for a single GValue
GdaSet — Container for several values
GdaConnectionEvent — Any event which has occurred on a GdaConnection
GdaTransactionStatus — Keeps track of the transaction status of a connection
GdaXaTransaction — Distributed transaction manager
Description of the data model returned by gda_connection_get_meta_store_data()
GDA_CONNECTION_META_NAMESPACES
GDA_CONNECTION_META_TYPES
GDA_CONNECTION_META_TABLES
GDA_CONNECTION_META_VIEWS
GDA_CONNECTION_META_FIELDS
GDA_CONNECTION_META_INDEXES
Virtual connections
GdaVirtualProvider — Base class for all virtual provider objects
GdaVproviderDataModel — Virtual provider for connections based on a list of GdaDataModel
GdaVproviderHub — Virtual provider for connections based on other connection
GdaVirtualConnection — Base class for all virtual connection objects
GdaVconnectionDataModel — Virtual connection based on a list of GdaDataModel
GdaVconnectionHub — Virtual connection which bind together connections
GdaLdapConnection — LDAP connection objects
Data handling
A single Value — Assorted functions for dealing with GValue values
Custom data validation
GdaHolder controls
GdaSet controls
GdaDataProxy controls
Advanced GdaDataSelect usage
Automatic re-run of the SELECT statement
Invalid parameters
Blobs — Binary data and BLOBs handling
GdaDataModel — Data model interface
GdaDataSelect — Base class for data models returned by the execution of a SELECT statement
GdaDataModel columns — Management of GdaDataModel column attributes
GdaDataModelIter — Data model iterator
GdaDataModelImport — Importing data from a string or a file
GdaDataPivot — A data model for data summarisation
GdaDataAccessWrapper — Offers a random access on top of a cursor-only access data model
GdaDataModelArray — An implementation of GdaDataModel based on a GArray
GdaRow — Individual row of a GdaDataModelArray object
GdaDataModelLdap — GdaDataModel to extract LDAP information
GdaDataModelBdb — GdaDataModel to access Berkeley DB database contents
GdaDataModelDir — GdaDataModel to list files in filesystem
GdaDataProxy — Proxy to hold modifications for any GdaDataModel, providing the GdaDataModel interface itself
GdaDataComparator — Simple data model's contents comparison
Implementing your own data model
Virtual methods
Signalling changes
Trees
GdaTree — A tree-structure
GdaTreeManager — Base class for all the tree managers
GdaTreeNode — A node in a GdaTree
GdaTreeMgrLabel — A tree manager which creates a single node
GdaTreeMgrSelect — A tree manager which creates a node for each row resulting from the execution of a SELECT statement
GdaTreeMgrSchemas — A tree manager which creates a node for each schema in a database
GdaTreeMgrTables — A tree manager which creates a node for each table in a schema
GdaTreeMgrColumns — A tree manager which creates a node for each column of a table
GdaTreeMgrLdap — A tree manager which creates a node for each child entry of an LDAP entry
Data conversions
GdaDataHandler — Interface which provides data handling (conversions) capabilities
GdaHanderString — Default handler for string values
GdaHanderBoolean — Default handler for boolean values
GdaHanderTime — Default handler for time values
GdaHanderNumerical — Default handler for numeric values
GdaHanderBin — Default handler for binary values
GdaHanderType — Default handler for GType values
Dictionary - metadata
Setup
Adding custom data
Database structure
Data types
SQL identifiers
Short and full names
Declared foreign keys
Individual table description
GdaMetaStore — Dictionary object
GdaMetaStruct — In memory representation of some database objects
Data definition (DDL) queries
GdaServerOperation — Handles any DDL query in an abstract way
GdaServerOperation: individual nodes — Getting information about parts (nodes) composing a path
GdaServerOperation: sequences — Manipulating sequences
User interface API reference
Library initialization — Library initialization and information
GdauiLogin — Connection opening widget
GdauiProviderSelector — Select a database provider from a combo box
GdauiDataSelector — Selecting data in a GdaDataModel
GdauiDataProxy — Displaying and modifying data in a GdaDataProxy
GdauiBasicForm — Form widget mapping the values contained in a GdaSet
GdauiForm — Form widget to manipulate data in a GdaDataModel, with decorations
GdauiRawForm — Form widget to manipulate data in a GdaDataModel
GdauiGrid — Grid widget to manipulate data in a GdaDataModel, with decorations
GdauiRawGrid — Grid widget to manipulate data in a GdaDataModel
GdauiCombo — Combo box to choose from the contents of a GdaDataModel
GdauiCloud — Cloud widget
GdauiRtEditor — Rich text editor which uses a subset of the txt2tags markup.
UI plugins — Plugin to customize dana entry widgets and call renderers in tree views
GdauiDataEntry — Data entry widget
GdauiDataStore — Bridge between a GdaDataModel and a GtkTreeModel
GdauiDataFilter — Entrer rules to filter the rows in a GdauiDataProxy
GdauiDataProxyInfo — Shows information & actions about a GdauiDataProxy widget
GdauiServerOperation — Enter information to perform a DDL query
GdauiTreeStore — Bridge between a GdaTree and a GtkTreeModel
UI Utility functions — Set of UI related functions
Multi threading
GdaMutex — Recursive mutex implementation
GdaLockable — Interface for locking objects in a multi threaded environment
GdaThreadWrapper — Execute functions in a sub thread
Miscellaneous
Utility functions — Utility functions
Logging — Log functions
Attributes manager — Manager for lists of attributes
III. Using Other Programing Languages
Introduction
Vala Extensions
IV. GDA Tools
Introduction
gda-sql
gda-list-config-5.0
gda-test-connection-5.0
gda-list-server-op-5.0
Control center
GdaBrowser
V. Reports
Introduction
API reference
GdaReportEngine — Low level report generator based on XML
GdaReportDocument — Report document
GdaReportDocbookDocument — Report document based on the DocBook dialect
GdaReportRmlDocument — Report document based on the RML dialect
VI. XSLT extension
Introduction
API reference
Example
VII. Gda SQL console's user manual
Getting started
Features
Execution
Commands
DSN management
Connections management
Virtual connections
Meta data
Information about tables
Information about views
Information about schemas
Information about other objects
Detailed features
Query buffer
Internal parameters
Embedded HTTP server
Environment variables
VIII. Databases providers for developers
Getting started
Virtual methods for providers
Synchronous / asynchronous mode
Multi threaded environment
Methods - provider's information
get_name() - mandatory
get_version() - mandatory
get_server_version() - mandatory
supports_feature()
Methods - connection management
open_connection() - mandatory
close_connection() - mandatory
get_database()
Methods - DDL queries
supports_operation()
create_operation()
render_operation()
perform_operation()
Methods - transactions management
begin_transaction()
commit_transaction()
rollback_transaction()
add_savepoint()
rollback_savepoint()
delete_savepoint()
Methods - DML queries
create_parser()
statement_to_sql()
statement_prepare()
statement_execute() - mandatory
handle_async()
Methods - data representation
get_data_handler()
get_def_dbms_type()
escape_string()
unescape_string()
Methods - metadata
Important note about SQL identifiers
Reserved SQL keywords
_info()
_btypes()
schemata() and _schemata()
tables_views() and _tables_views()
columns() and _columns()
constraints_tab() and _constraints_tab()
constraints_ref() and _constraints_ref()
key_columns() and _key_columns()
Methods - misc.
cancel()
create_connection()
is_busy()
Virtual methods for recordsets
Virtual methods for Blob operations
SQL parser
Implementation overview
Generic SQL parser
Provider specific SQL parser
Tips to write a custom parser
GdaSqlStatement — SQL statement
Assembling all the parts
libmain.c
plugin_init()
plugin_get_name()
plugin_get_description()
plugin_get_dsn_spec()
plugin_get_auth_spec()
plugin_create_provider()
Providers' support API
GdaServerProvider — Base class for all the DBMS providers
Subclassing GdaDataSelect — Base class for all the data models returned by DBMS providers when a SELECT statement is executed
GdaPstmt — Base class for prepared statement's
Quark list — Manages lists of KEY=VALUE pairs
SQL rendering API — Adapting the SQL to the database's own SQL dialect
Misc API for database providers — Methods dedicated to implementing providers
IX. Packaging
Packaging Libgda
Overview of the components
Runtime component
GObject introspection
Tools
Diagnostic tools
SQL console
Database providers
'Generic' provider
The SQLite provider
The JDBC provider
Development files
Documentation
Localization
Packaging Libgda UI extension
Overview of the components
Runtime component
GObject introspection
Tools
Control center
Gda browser
Development files
X. Appendix
Index
A. GNU Free Documentation License
0. PREAMBLE
1. APPLICABILITY AND DEFINITIONS
2. VERBATIM COPYING
3. COPYING IN QUANTITY
4. MODIFICATIONS
5. COMBINING DOCUMENTS
6. COLLECTIONS OF DOCUMENTS
7. AGGREGATION WITH INDEPENDENT WORKS
8. TRANSLATION
9. TERMINATION
10. FUTURE REVISIONS OF THIS LICENSE
Addendum
Generated by GTK-Doc V1.33.1