aRT is an R package for manipulating spatial data using TerraLib. TerraLib manipulates data stored in DataBase Management Systems (DBMS), to which it is necessary to establish connections. Connecting to a DBMS is aways the first action when using aRT. This short document introduces the primary class of the package, named aRTconn. This class implements a virtual connection to a DBMS. In the initial examples, we consider the user already has permissions in the DBMS. Later, in Section 4, we explain how aRT functions can change the permissions in the DBMS.
After loading the package, it is necessary to establish a DBMS connection. The function openConn() is designed for such task. Currently, this function takes four arguments (the defaults values are indicated within parenthesis): user (the current user as given by $USER), password (no password), host (‘localhost’), and port (3306). Future versions will include a fifth argument, DBMS, with options to supported BDMS such as “MySQL”, “Postgres”, “PostGIS”.
When a connection is successfully stablished, this function returns an object of the class aRTconn. It is important to notice that the elements in the object con cannot be changed. The only possible way to set/change the connection parameters is creating another object. calling openConn() with the new options. This happens because its data is stored in an external pointer. If the connection cannot be established, the function stops with an error, as in the following example:
An aRTconn object stores a virtual connection to a DBMS, that is, every time a database access is required, the object connects with the DBMS, performs the task, and then disconnects. aRTconn objects allow for some basic queries and operations in the DBMS. The function showDbs() lists the databases available (the ones which the user has some permission):
New databases can be created with createDb():
and existing databases can be opened with openDb(),
In these examples, both dbintro and db belong to the class aRTdb, that stores a real connection to a particular database. As a consequence, at this point the virtual connection is no longer needed and these objects are independent from con. Note that an aRTdb object can turn inconsistent if the database is removed from the DBMS, possibly generating a core dump. This cannot be avoided because the database can be removed from any other connection to the DBMS, which can be from another aRTconn object, directly from MySQL, or by another TerraLib-based application.
Whenever the user removes the object that stores a database connection, the connection is not removed yet. To successfuly remove a database connection, you have to to call the garbage collector using gc().
To physically remove a database, the user needs a special permission. If you have such permission, it is possible to remove databases using deleteDb(). The argument force=TRUE can be used to avoid a keyboard confirmation, because this a dangerous operation, and cannot be undone.
The function addPermission() provides a way to add users to the DBMS, with corresponding permissions. The first step is to start a session with root permissions.
Using this conection, some types of permissions can be set1 :
This function, when called as before, provides full access to all the DBMS databases. It is also possible to restrict the permissions to some privileges or some specific databases. For instance:
In order to see the permissions of the DBMS, use getPermissions:
Finally, for removing the permissions of a given user, use dropUser:
[1] Chambers, J.M., 1998, Programming with data, a guide to the S language. Springer, New York.
[2] MySQL Documentation. http://dev.mysql.com/doc/. Last access: 08/14/2008