GADriver

Object subclass: #'GADriver' 
instanceVariableNames: 'connectionString encoding' 
classVariableNames: 'Drivers' 
poolDictionaries: '' 
category: 'Garage-Driver'

Overview

This is the basic interface to instantiate and look for database drivers.

Database drivers subscribe themselves to a global driver manager using this class. Then, they are instantiated through it.

It also describes the minimal interface of all drivers. Its API contains the main methods to execute database queries, prepare statements and manage transactions. Also, to handle the differences between different drivers, this API provides a bunch of supports* methods to check the provided features.

Class Method Details

availableDrivers

availableDrivers
^Drivers availableDrivers

connectToConnectionString:

connectToConnectionString: aConnectionString 
| connection |
connection := self fromConnectionString: aConnectionString.
connection connect
^connection

driverAt:

driverAt: aDriverId 
^Drivers driverAt: aDriverId

driverId

driverId
^self subclassResponsibility

fromConnectionString:

fromConnectionString: string 
| connectionString |
string isString 
ifTrue: [ connectionString := GAConnectionString fromString: string ] 
ifFalse: [ connectionString := string ].

^(self driverAt: connectionString driverId) fromConnectionString: connectionString

initialize

initialize
Drivers := GADriverManager new

isAvailable:

isAvailable: aKey 
^Drivers isAvailable: aKey

newFixture

newFixture
^self subclassResponsibility

newFixtureForConnectionString:

newFixtureForConnectionString: aConnectionString 
^self newFixture

subscribeDriver

subscribeDriver
Drivers subscribeDriver: self

supportsEncoding:

supportsEncoding: anEncoding 
self subclassResponsibility

Instance Method Details

affectsOnlyChangedRows

Tests if the current database driver will inform the number of effectively affected rows during a INSERT/UPDATE/DELETE query or just all that were selected by the WHERE clause

affectsOnlyChangedRows
^false

backend

backend
^self subclassResponsibility

beginTransaction

Starts a database transaction

beginTransaction
self subclassResponsibility

close

Closes the current connection

close
self subclassResponsibility

commitTransaction

Commits the current database transaction

commitTransaction
self subclassResponsibility

connect

Opens the connection to the configured database

connect
self subclassResponsibility

connectionString

connectionString
^connectionString

connectionString:

connectionString: aGAConnectionString 
connectionString := aGAConnectionString

createStatement

Creates an empty statement object

createStatement
self subclassResponsibility

createStatement:

Creates a statement object from a sql query

createStatement: aSQLString 
self subclassResponsibility

defaultValueAutoCommit

Retrieves the expected default value of autocommit for the current driver. Autocommit should not be used in a general fashion: each database vendor implements it differently.

defaultValueAutoCommit
self subclassResponsibility

driverId

driverId
^self class driverId

encoder

encoder
| theEncoding |
theEncoding := self encoding = 'utf8mb4' 
ifTrue: [ 'utf8' ] 
ifFalse: [ self encoding ]
.
^ZnCharacterEncoder newForEncoding: theEncoding

encoding

Returns the configured encoding for this driver instance. Default: 'utf8'

encoding
^encoding ifNil: [ encoding := connectionString optionAt: 'encoding' ifAbsent: 'utf8' ]

encoding:

Sets an encoding for the current driver instance. Accepted encodings are those supported by ZnCharacterEncoder

encoding: anEncoding 
encoding := anEncoding

execute:

Executes a SQL query against the database in one roundtrip

execute: aQuery 
self subclassResponsibility

finalize

Frees all associated resources of this driver instance

finalize

hasAutoCommit

Tests if the current database driver has autocommit enabled or not

hasAutoCommit
self subclassResponsibility

isConnected

Tests if the connection is alive and connected

isConnected
self subclassResponsibility

isRegisteredForFinalization

Tests if the current driver instance is registered in the weak registry for finalization or not

isRegisteredForFinalization
^WeakRegistry default includes: self

notBoundArgumentsFail

Tests if the current database driver fails if a prepared statement contains arguments that are not bound. Some drivers such as Sqlite3 will default unbound arguments to NULL and not fail.

notBoundArgumentsFail
^true

numberOfFetchesForSingleExecute

Returns the number of roundtrips a database driver does for a single execute command

numberOfFetchesForSingleExecute
^1

optionAt:

It allows to access the configuration options of this driver

optionAt: aString 
^self connectionString optionAt: aString

prepare:

Creates a statement object from a sql query and sends it for its preparation to the database server

prepare: aQuery 
self subclassResponsibility

register

Registers the current driver into the weak registry for automatic memory management

register
WeakRegistry default add: self

rollbackTransaction

Rollbacks the current database transaction

rollbackTransaction
self subclassResponsibility

supportsAutomaticQueryEncoding

Tests if the current database driver supports not-encoded strings inside a sql query. When true the driver will encode the full request into the configured encoding and the user does not have to manage it. When false the driver does not support encoding the query and thus the user has to encode manually arguments if building a query by String concatenation.

Alternatively, use prepared statements when supported to avoid this issue

supportsAutomaticQueryEncoding
self subclassResponsibility

supportsCursoredFetch

Tests if the current database driver supports cursored fetches. i.e., bringing database rows in batch instead of all in a row.

supportsCursoredFetch
^self subclassResponsibility

supportsEncoding:

Returns a boolean that indicates if the current driver supports a particular encoding

supportsEncoding: anEncoding 
^self class supportsEncoding: anEncoding

supportsPreparedStatements

Tests if the current database driver supports prepared statements

supportsPreparedStatements
^false

supportsRetrievingGeneratedKeys

Tests if the current database driver supports retrieving auto generated keys/ids without an extra query

supportsRetrievingGeneratedKeys
^false

unregister

Unregisters the current driver from the weak registry. Calling this means that finalization will be manual

unregister
WeakRegistry default remove: self ifAbsent: [ 
 ]