Session

The ADO.Sessions package defines the control and management of database sessions. The database session is represented by the Session or Master_Session types. It provides operation to create a database statement that can be executed. The Session type is used to represent read-only database sessions. It provides operations to query the database but it does not allow to update or delete content. The Master_Session type extends the Session type to provide write access and it provides operations to get update or delete statements. The differentiation between the two sessions is provided for the support of database replications with databases such as MySQL.

Database Drivers

Database drivers provide operations to access the database. These operations are specific to the database type and the ADO.Drivers package among others provide an abstraction that allows to make the different databases look like they have almost the same interface.

A database driver exists for SQLite, MySQL and PostgreSQL. The driver is either statically linked to the application or it can be loaded dynamically if it was built as a shared library. For a dynamic load, the driver shared library name must be prefixed by libada_ado_. For example, for a mysql driver, the shared library name is libada_ado_mysql.so.

Driver name Database
mysql MySQL, MariaDB
sqlite SQLite
postgresql PostgreSQL

The database drivers are initialized automatically but in some cases, you may want to control some database driver configuration parameter. In that case, the initialization must be done only once before creating a session factory and getting a database connection. The initialization can be made using a property file which contains the configuration for the database drivers and the database connection properties. For such initialization, you will have to call one of the Initialize operation from the ADO.Drivers package.

ADO.Drivers.Initialize ("db.properties");

The set of configuration properties can be set programatically and passed to the Initialize operation.

Config : Util.Properties.Manager;
...
  Config.Set ("ado.database", "sqlite:///mydatabase.db");
  Config.Set ("ado.queries.path", ".;db");
  ADO.Drivers.Initialize (Config);

Once initialized, a configuration property can be retrieved by using the Get_Config operation.

URI : constant String := ADO.Drivers.Get_Config ("ado.database");

Dynamic loading of database drivers is disabled by default for security reasons and it can be enabled by setting the following property in the configuration file:

ado.drivers.load=true

Dynamic loading is triggered when a database connection string refers to a database driver which is not known.

MySQL Database Driver

The MySQL database driver can be initialize explicitly by using the ado_mysql GNAT project and calling the initialization procedure.

ADO.Mysql.Initialize ("db.properties");

The set of configuration properties can be set programatically and passed to the Initialize operation.

Config : Util.Properties.Manager;
...
  Config.Set ("ado.database", "mysql://localhost:3306/ado_test");
  Config.Set ("ado.queries.path", ".;db");
  ADO.Mysql.Initialize (Config);

The MySQL database driver supports the following properties:

Name Description
user The user name to connect to the server
password The user password to connect to the server
socket The optional Unix socket path for a Unix socket base connection
encoding The encoding to be used for the connection (ex: UTF-8)

SQLite Database Driver

The SQLite database driver can be initialize explicitly by using the ado_mysql GNAT project and calling the initialization procedure.

ADO.Sqlite.Initialize ("db.properties");

The set of configuration properties can be set programatically and passed to the Initialize operation.

Config : Util.Properties.Manager;
...
  Config.Set ("ado.database", "sqlite:///regtests.db?synchronous=OFF&encoding=UTF-8");
  Config.Set ("ado.queries.path", ".;db");
  ADO.Sqlite.Initialize (Config);

The SQLite database driver will pass all the properties as SQLite pragma allowing the configuration of the SQLite database.

PostgreSQL Database Driver

The PostgreSQL database driver can be initialize explicitly by using the ado_mysql GNAT project and calling the initialization procedure.

ADO.Postgresql.Initialize ("db.properties");

The set of configuration properties can be set programatically and passed to the Initialize operation.

Config : Util.Properties.Manager;
...
  Config.Set ("ado.database", "postgresql://localhost:5432/ado_test?user=ado&password=ado");
  Config.Set ("ado.queries.path", ".;db");
  ADO.Postgresql.Initialize (Config);

The PostgreSQL database driver supports the following properties:

Name Description
user The user name to connect to the server
password The user password to connect to the server

Connection string

The database connection string is an URI that specifies the database driver to use as well as the information for the database driver to connect to the database. The driver connection is a string of the form:

driver://[host][:port]/[database][?property1][=value1]...

The database connection string is passed to the session factory that maintains connections to the database (see ADO.Sessions.Factory).

Session Factory

The session factory is the entry point to obtain a database session. The ADO.Sessions.Factory package defines the factory for creating sessions.

with ADO.Sessions.Factory;
...
Sess_Factory : ADO.Sessions.Factory;

The session factory can be initialized by using the Create operation and by giving a URI string that identifies the driver and the information to connect to the database. The session factory is created only once when the application starts.

ADO.Sessions.Factory.Create (Sess_Factory, "mysql://localhost:3306/ado_test?user=test");

Having a session factory, one can get a database by using the Get_Session or Get_Master_Session function. Each time this operation is called, a new session is returned. The session is released when the session variable is finalized.

DB : ADO.Sessions.Session := Sess_Factory.Get_Session;

The session factory is also responsible for maintaining some data that is shared by all the database connections. This includes:

  • the sequence generators used to allocate unique identifiers for database tables,

  • the entity cache,

  • some application specific global cache.

Database Caches

The ADO cache manager allows to create and maintain cache of values and use the cache from the SQL expander to replace cached values before evaluating the SQL. The SQL expander identifies constructs as follows:

$cache_name[entry-name]

and look for the cache identified by cache_name and then replace the cache entry registered with the name entry-name.

The cache manager is represented by the Cache_Manager type and the database session contains one cache manager. Applications may use their own cache in that case they will declare their cache as follows:

 M : ADO.Caches.Cache_Manager;

A cache group is identified by a unique name and is represented by the Cache_Type base class. The cache group instance is registered in the cache manager by using the Add_Cache operation.