SqueakDBX - Dealings with connections


	links to this page:

Last updated at 11:36 pm UTC on 4 April 2009

Instantiation

Just right now (we hope to have it in a future), there isn't a pool connection. So, you have to manage them manually.
There is the class DBXConnection that you should instantiate per connection to database you want. This is a statefull class that contains all the connection information and the current status. This is the driver interface. This class has lots of useful messages like open, close, connect, disconnect, execute, enable special options, and so on.
Now, how do you instantiate a DBXConnection? Just like this:

| conn connectionSettings |

    connectionSettings := DBXConnectionSettings

                host: 'localhost'

                port: '5432'

                database: 'sodbxtest'

                userName: 'sodbxtest'

                userPassword: 'sodbxtest'.

    conn := DBXConnection platform: DBXPostgresPlatform new settings: connectionSettings.

In this case we use a Postgres database and because of this we use a DBXPostgresPlatform, but you can use any of the supported backends. For example, DBXMySQLPlatform, DBXOdbcPlatform, DBXOraclePlatform, DBXMSSQLPlatform and DBXSqlitePlatform. See all the subclasses of DBXPlatform.

DBXConnection states

Before seeing all the messages to change the state of a connection, it will be nice to see which are the possible states. So, here its a state diagram of a DBXConnection.

Connection/Open

Ok. Till now you have only created a connection object. You should now open the real TCP connection with the database. To do this, you will need to do two things: connect to database and then open the connection. Example:

    conn connect.

    conn open.

Connect message allocates and initializes an opaque object required for all further operations within the OpenDBX library which is used to identify the connection and to maintain per connection information. Connect message will use the IP and the port from the DBXConnectionSettings.
The open message associates a connected connection to a specific database after the server verified and accepted the user credentials. To do this, it will use database, username and password. Currently, OpenDBX and some database backends only provides user name / password authentication method. However it is expected to provide more of them in a future.

Suppose you are sure you don't want to use any SqueakDBX special options (see SqueakDBX - Special options), you can use connectAndOpen message. However, we recommend to use connect and open separately. Here is an example:

    conn connectAndOpen.

Disconnection/Close

After you have done all you want with the database, you should now disconnect from it and release all resources. The correct way of doing this is:

conn close.

conn disconnect

There are some point you should know:

If you don't do the close but the disconnect, the disconnect will do the close for you.
You cannot close something that wasn't open.
If you try to disconnect something without connect, it does nothing.
You will have an error if you try to open an already opened connection. The same happens with connect.
If you don't do the close neither the disconnect, the framework will do it when the object is garbage collected.

However, we recommend you do it in the correct way.

Reopen

Suppose you have a DBXConnection connected and open. Sometimes it may be necessary to connect to a different database (schema) or re-authenticate using different credentials. In such a case you can do this:

    | conn connectionSettings |

    connectionSettings := DBXConnectionSettings

                host: 'localhost'

                port: '5432'

                database: 'sodbxtest'

                userName: 'sodbxtest'

                userPassword: 'sodbxtest'.

    conn := DBXConnection platform: DBXPostgresPlatform new settings: connectionSettings.

    conn connect.

    conn open.

    connectionSettings := DBXConnectionSettings

                host: 'localhost'

                port: '5432'

                database: 'otherDataBase'

                userName: 'otherUserName'

                userPassword: 'otherUserPassword'.

    conn reOpen: connectionSettings.





This will open a new connection to the database but to the new schema and usign the new username and password.

Special Options

You may be asking why not to do connect/open and close/disconnect all together, don't you? Ok, we have some reasons:

This let you do the reopen.
There are some special options that have to be enable after the connect, but before the open. You can read about special options here SqueakDBX - Special options

Unit Tests

For more examples, information and usage, you can see the tests we have related with this. These tests are: DBXConnectionTest, DBXConnectionSettingsTest.