Entering the Garage

This article describes the basics of the garage database driver. It covers its basic usage: creating connections, connecting and closing them, and executing SQL queries. Details and particular features are discussed in other related articles.

1. Getting a Connection

The Garage database driver supports the creation of a connection through connection strings.

connection := GADriver fromConnectionString:
	'mysql://localhost:5432/sodbxtest?&user=sodbxtest&password=sodbxtest'.

Connection strings are URL styled:

• the schema (http, ftp, etc.) is the database driver id (we will talk about it later). In this example our schema is mysql.
• host, port and database are the address of your database server
• the query-string allows us to put additional information such as connection credentials. the key user is followed by the database user to login and the key password by its password.

driver://host:port/database?key=value&key2=value2

Which are the drivers I have? To know which are the available drivers you have, you can ask it to the driver class using the #availableDrivers message. For further information, check the installation page.

2. Stablishing connection

Initially and to avoid surprises, a database connection is not connected to the database. You can check if a connection is connected at any time during the life of the connection using the isConnected message.

connection isConnected.
	" => true/false"

To activate the connection, we can send the connect message to it. If everything is allright (the database is available, username and passwords are correct) and the connection succedded we will receive no error. Instead, if a failure happened while trying to stablish the connection, it will raise an exception. Stablising manually the connection is useful to those users that want to parametrize the connection between its creation and its connection to the database. We will talk in more detail about connection settings later.

connection connect.

However, for those users that do not need to set manually parameters, he can use a shortcut that creates the connection and connects it in only one step.

connection := GADriver connectToConnectionString: 
	'mysql://localhost:3306/sodbxtest?user=sodbxtest&password=sodbxtest'.

3. Sending a Query

Once a connection is available, we can send queries and statements to it for their execution. Here we will only see a simple query, using the execute message. We will describe in details how queries and their results are managed later.

connection execute: 'CREATE TABLE CATS (
	name varchar(50),
	owner varchar(50))'.

connection execute: 'SELECT * FROM CATS'.

Executing a correct query will return an according result: a select query will answer a result with rows, other statements will return a result with a summary of the action they did (e.g., an insert or update will return the amount of modified rows). Executing a wrong query will throw an exception explaining the problem. For example, a query with incorrect syntax will fail and tell us where is the syntax problem; querying an unexistent table will throw an error saying so. We will dive later into the expected kind of results.

4. Closing the connection

Database servers allow a limited number of simultaneous connections. If too many connections are open the server will start refusing new connections. To avoid these problems we have to close unused connections. Closing an unused connection will free used resources both in our Pharo image and in the database server. We can close manually a database connection by sending it the close message.

connection close.

Garage provides also the automatic closure of connections on garbage collection. That is, when a database connection object is being garbage collected, the connection will be automatically closed. To allow a database connection to be automatically collected, we must release all references to it. We must not keep references to a connection from any of our objects.