# SQLClient documentation

### Authors

Richard Frith-Macdonald (`rfm@gnu.org`)

Version: 38114

Date: 2014-10-13 11:47:06 +0100 (Mon, 13 Oct 2014)

Copyright: (C) 2004 Free Software Foundation, Inc.

### Contents -

1. The SQLClient library
2. What is the SQLClient library?
3. What backend bundles are available?
4. Where can you get it? How can you install it?
5. Software documentation for the SQLClient class
6. Software documentation for the SQLClientPool class
7. Software documentation for the SQLDictionaryBuilder class
8. Software documentation for the SQLRecord class
9. Software documentation for the SQLSetBuilder class
10. Software documentation for the SQLSingletonBuilder class
11. Software documentation for the SQLTransaction class
12. Software documentation for the SQLClient(Caching) category
13. Software documentation for the SQLClient(Convenience) category
14. Software documentation for the SQLClient(Logging) category
15. Software documentation for the SQLClient(Notifications) category
16. Software documentation for the SQLClient(Subclass) category
17. SQLClient constants
18. SQLClient variables
19. SQLClient functions

# The SQLClient library

## What is the SQLClient library?

The SQLClient library is designed to provide a simple interface to SQL databases for GNUstep applications. It does not attempt the sort of abstraction provided by the much more sophisticated GDL2 library, but rather allows applications to directly execute SQL queries and statements.

SQLClient provides for the Objective-C programmer much the same thing that JDBC provides for the Java programmer (though SQLClient is a bit faster, easier to use, and easier to add new database backends for than JDBC).

The major features of the SQLClient library are -

- Simple API for executing queries and statements... a variable length sequence of comma separated strings and other objects (NSNumber, NSDate, NSData) are concatenated into a single SQL statement and executed.
- Simple API ([SQLTransaction])for combining multiple SQL statements into a single transaction which can be used to minimise client-server interactions to get the best possible performance from your database.
- Supports multiple sumultaneous named connections to a database server in a thread-safe manner.
- Supports multiple simultaneous connections to different database servers with backend driver bundles loaded for different database engines. Clear, simple subclassing of the abstract base class to enable easy implementation of new backend bundles.
- Configuration for all connections held in one place and referenced by connection name for ease of configuration control. Changes via NSUserDefaults can even allow reconfiguration of client instances within a running application.
- Thread safe operation... The base class supports locking such that a single instance can be shared between multiple threads.
- Support for standalone web applications... eg to allow data to be added to the database by people posting web forms to the application.
- Supports notification of connection to and disconnection from the database server.

## What backend bundles are available?

Current backend bundles are -

- ECPG - a bundle using the embedded SQL interface for postgres.
  This is based on a similar code which was in production use for over eighteen months, so it should be reliable, but inefficient.
- Postgres - a bundle using the libpq native interface for postgres.
  This is the preferred backend as it allows 'SELECT FOR UPDATE', which the ECPG backend cannot support due to limitations in the postgres implementation of cursors. The code is now well tested and known to be efficient.
- MySQL - a bundle using the mysqlclient library for *recent* MySQL.
  I don't use MySQL... but the test program ran successfully with a vanilla install of the MySQL packages for recent Debian unstable.
- SQLite - a bundle using the sqlite3 library which supports an SQL-like API for direct access to a database file (rather than acting as a client of a database server process).
  Not as functional as the other backends (doesn't support dates for instance), but good enough for many purposes and very 'lightweight'. See http://www.sqlite.org
- Oracle - a bundle using embedded SQL for Oracle.
  Completely untested... may even need some work to compile... but this *is* based on code which was working about a year ago.
  No support for BLOBs yet.

## Where can you get it? How can you install it?

The SQLClient library is currently only available via CVS from the GNUstep CVS repository.
See <https://savannah.gnu.org/cvs/?group=gnustep>
You need to check out `gnustep/dev-libs/SQLClient`

To build this library you must have a basic GNUstep environment set up...

- The gnustep-make package must have been built and installed.
- The gnustep-base package must have been built and installed.
- The Performance library (from the dev-libs area in GNUstep CVS) must have been built and installed.
- If this environment is in place, all you should need to do is run 'make' to configure and build the library, 'make install' to install it.
- Then you can run the test programs.
- Your most likely problems are that the configure script may not detect the database libraries you want... Please figure out how to modify `configure.ac` so that it will detect the required headers and libraries on your system, and supply na patch.
- Once the library is installed, you can include the header file `<SQLClient/SQLClient.h%gt;` and link your programs with the `SQLClient` library to use it.

Bug reports, patches, and contributions (eg a backend bundle for a new database) should be entered on the GNUstep project page <http://savannah.gnu.org/projects/gnustep> and the bug reporting page <http://savannah.gnu.org/bugs/?group=gnustep>

# Software documentation for the SQLClient class

## SQLClient : NSObject

> Declared in:
>   SQLClient.h

The SQLClient class encapsulates dynamic SQL access to relational database systems. A shared instance of the class is used for each database (as identified by the name of the database), and the number of simultanous database connections is managed too.

SQLClient is an abstract base class... when you create an instance of it, you are actually creating an instance of a concrete subclass whose implementation is loaded from a bundle.

Instance Variables
Method summary

- -cache
- -cache:query:,...
- -cache:query:with:
- -cache:simpleQuery:
- -cache:simpleQuery:recordType:listType:
- -setCache:
- -setCacheThread:
- -batch:
- -columns:
- -queryRecord:,...
- -queryString:,...
- -singletons:
- -transaction
- +debugging
- +durationLogging
- +setDebugging:
- +setDurationLogging:
- -debug:,...
- -debugging
- -durationLogging
- -setDebugging:
- -setDurationLogging:
- -addObserver:selector:name:
- -postNotificationName:payload:
- -removeObserver:name:
- -backendConnect
- -backendDisconnect
- -backendExecute:
- -backendListen:
- -backendNotify:payload:
- -backendQuery:
- -backendQuery:recordType:listType:
- -backendUnlisten:
- -copyEscapedBLOB:into:
- -insertBLOBs:intoStatement:length:withMarker:length:giving:
- -lengthOfEscapedBLOB:
- +allClients
- +clientWithConfiguration:name:
- +existingClient:
- +maxConnections
- +purgeConnections:
- +setMaxConnections:
- -begin
- -buildQuery:,...
- -buildQuery:with:
- -clientName
- -commit
- -connect
- -connected
- -database
- -disconnect
- -execute:,...
- -execute:with:
- -initWithConfiguration:
- -initWithConfiguration:name:
- -initWithConfiguration:name:pool:
- -isEqual:
- -isInTransaction
- -lastOperation
- -longestIdle:
- -name
- -password
- -query:,...
- -query:with:
- -quote:
- -quoteBigInteger:
- -quoteCString:
- -quoteChar:
- -quoteFloat:
- -quoteInteger:
- -quoteString:
- -quotef:,...
- -rollback
- -setDatabase:
- -setName:
- -setPassword:
- -setShouldTrim:
- -setUser:
- -simpleExecute:
- -simpleQuery:
- -simpleQuery:recordType:listType:
- -user

### allClients

+ (NSArray*) allClients;
Returns an array containing all the SQLClient instances.

### clientWithConfiguration: name:

+ (SQLClient*) clientWithConfiguration: (NSDictionary*)config name: (NSString*)reference;
Return an existing SQLClient instance (using +existingClient:) if possible, or creates one, initialises it using -initWithConfiguration:name: , and returns the new instance (autoreleased).
Returns `nil` on failure.

### existingClient:

+ (SQLClient*) existingClient: (NSString*)reference;
Return an existing SQLClient instance for the specified name if one exists, otherwise returns `nil`.

### maxConnections

+ (unsigned int) maxConnections;
Returns the maximum number of simultaneous database connections permitted (set by +setMaxConnections: and defaults to 8) for connections outside of SQLClientPool instances.

### purgeConnections:

+ (void) purgeConnections: (NSDate*)since;

Use this method to reduce the number of database connections currently active so that it is less than the limit set by the +setMaxConnections: method. This mechanism is used internally by the class to ensure that, when it is about to open a new connection, the limit is not exceeded.

If since is not `nil`, then any connection which has not been used more recently than that date is disconnected anyway.
You can (and probably should) use this periodically to purge idle connections, but you can also pass a date in the future to close all connections.

Purging does not apply to connections made by SQLClientPool instances.

### setMaxConnections:

+ (void) setMaxConnections: (unsigned int)c;

Set the maximum number of simultaneous database connections permitted (defaults to 8 and may not be set less than 1).

This value is used by the +purgeConnections: method to determine how many connections should be disconnected when it is called.

Connections used by SQLClientPool instances are not considered by this maximum.

### begin

- (void) begin;
Start a transaction for this database client.
You must match this with either a -commit or a -rollback .

Normally, if you execute an SQL statement without using this method first, the autocommit feature is employed, and the statement takes effect immediately. Use of this method permits you to execute several statements in sequence, and only have them take effect (as a single operation) when you call the -commit method.

NB. You must not execute an SQL statement which would start a transaction directly... use only this method.

Where possible, consider using the SQLTransaction class rather than calling -begin -commit or -rollback yourself.

### buildQuery: ,...

- (NSString*) buildQuery: (NSString*)stmt,...;

Build an sql query string using the supplied arguments.

This method has at least one argument, the string starting the query to be executed (which must have the prefix 'select ').

Additional arguments are a `nil` terminated list which also be strings, and these are appended to the statement.
Any string arguments are assumed to have been quoted appropriately already, but non-string arguments are automatically quoted using the -quote: method.

       sql = [db buildQuery: @"SELECT Name FROM ", table, nil];

Upon error, an exception is raised.

The method returns a string containing sql suitable for passing to the -simpleQuery:recordType:listType: or -cache:simpleQuery:recordType:listType: methods.

### buildQuery: with:

- (NSString*) buildQuery: (NSString*)stmt with: (NSDictionary*)values;
Takes the query statement and substitutes in values from the dictionary where markup of the format {key} is found.
Returns the resulting query string.

       sql = [db buildQuery: @"SELECT Name FROM {Table} WHERE ID = {ID}"
                       with: values];

Any non-string values in the dictionary will be replaced by the results of the -quote: method.
The markup format may also be {key?default} where default is a string to be used if there is no value for the key in the dictionary.

The method returns a string containing sql suitable for passing to the -simpleQuery:recordType:listType: or -cache:simpleQuery:recordType:listType: methods.

### clientName

- (NSString*) clientName;
Return the client name for this instance.
Normally this is useful only for debugging/reporting purposes, but if you are using multiple instances of this class in your application, and you are using embedded SQL, you will need to use this method to fetch the client/connection name and store its C-string representation in a variable 'connectionName' declared to the sql preprocessor, so you can then have statements of the form - 'exec sql at :connectionName...'.

### commit

- (void) commit;
Complete a transaction for this database client.
This must match an earlier -begin .

NB. You must not execute an SQL statement which would commit or rollback a transaction directly... use only this method or the -rollback method.

Where possible, consider using the SQLTransaction class rather than calling -begin -commit or -rollback yourself.

### connect

- (BOOL) connect;
If the connected instance variable is `NO`, this method calls -backendConnect to ensure that there is a connection to the database server established. Returns the result.
Performs any necessary locking for thread safety.
This method also counts the number of consecutive failed connection attempts. A delay is enforced between each connection attempt, with the length of the delay growing with each failure. This ensures that applications which fail to deal with connection failures, and just keep trying to reconnect, will not overload the system/server.
The maximum delay is 30 seconds, so when the database server is restarted, the application can reconnect reasonably quickly.

### connected

- (BOOL) connected;
Return a flag to say whether a connection to the database server is currently live (the value of the 'connected' instance variable).
This is mostly useful for debug/reporting.

### database

- (NSString*) database;
Return the database name for this instance (or `nil`).

### disconnect

- (void) disconnect;
If the connected instance variable is `YES`, this method calls -backendDisconnect to ensure that the connection to the database server is dropped.
Performs any necessary locking for thread safety.

### execute: ,...

- (NSInteger) execute: (NSString*)stmt,...;
Perform arbitrary operation which does not return any value.
This arguments to this method are a `nil` terminated list which are concatenated in the manner of the -query:,... method.
Any string arguments are assumed to have been quoted appropriately already, but non-string arguments are automatically quoted using the -quote: method.

       [db execute: @"UPDATE ", table, @" SET Name = ",
         myName, " WHERE ID = ", myId, nil];

Where the database backend support it, this method returns the count of the number of rows to which the operation applied. Otherwise this returns -1.

### execute: with:

- (NSInteger) execute: (NSString*)stmt with: (NSDictionary*)values;
Takes the statement and substitutes in values from the dictionary where markup of the format {key} is found.
Passes the result to the -execute:,... method.

       [db execute: @"UPDATE {Table} SET Name = {Name} WHERE ID = {ID}"
              with: values];

Any non-string values in the dictionary will be replaced by the results of the -quote: method.
The markup format may also be {key?default} where default is a string to be used if there is no value for the key in the dictionary.
Where the database backend support it, this method returns the count of the number of rows to which the operation applied. Otherwise this returns -1.

### initWithConfiguration:

- (id) initWithConfiguration: (NSDictionary*)config;
Calls -initWithConfiguration:name: passing a `nil` reference name.

### initWithConfiguration: name:

- (id) initWithConfiguration: (NSDictionary*)config name: (NSString*)reference;
Calls -initWithConfiguration:name:pool: passing `NO` to say the client is not in a pool.

### initWithConfiguration: name: pool:

- (id) initWithConfiguration: (NSDictionary*)config name: (NSString*)reference pool: (SQLClientPool*)pool;
Initialise using the supplied configuration, or if that is `nil`, try to use values from NSUserDefaults (and automatically update when the defaults change).
Uses the reference name to determine configuration information... and if a `nil` name is supplied, defaults to the value of SQLClientName in the configuration dictionary (or in the standard user defaults). If there is no value for SQLClientName, uses the string 'Database'.
If pool is `nil` and a SQLClient instance already exists with the name used for this instance, the receiver is deallocated and the existing instance is retained and returned... there may only ever be one instance for a particular reference name which is not in a pool.
The config argument (or the SQLClientReferences user default) is a dictionary with names as keys and dictionaries as its values. Configuration entries from the dictionary corresponding to the database client are used if possible, general entries are used otherwise.
Database... is the name of the database to use, if it is missing then 'Database' may be used instead.
User... is the name of the database user to use, if it is missing then 'User' may be used instead.
Password... is the name of the database user password, if it is missing then 'Password' may be used instead.
ServerType... is the name of the backend server to be used... by convention the name of a bundle containing the interface to that backend. If this is missing then 'Postgres' is used.
The database name may be of the format 'name@host:port' when you wish to connect to a database on a different host over the network.

### isEqual:

- (BOOL) isEqual: (id)other;
Two clients are considered equal if they refer to the same database and are logged in as the same database user using the same protocol. These are the general criteria for transactions to be compatoible so that an SQLTransaction object generated by one client can be used by the other.

### isInTransaction

- (BOOL) isInTransaction;
Return the state of the flag indicating whether the library thinks a transaction is in progress. This flag is normally maintained by -begin , -commit , and -rollback .

### lastOperation

- (NSDate*) lastOperation;
Returns the date/time stamp of the last database operation performed by the receiver, or `nil` if no operation has ever been done by it.
Simply connecting to or disconnecting from the databsse does not count as an operation.

### longestIdle:

- (SQLClient*) longestIdle: (SQLClient*)other;
Compares the receiver with the other client to see which one has been inactive but connected for longest (if they are connected) and returns that instance.
If neither is idle but connected, the method returns `nil`.
In a tie, the method returns the other instance.

### name

- (NSString*) name;
Return the database reference name for this instance (or `nil`).

### password

- (NSString*) password;
Return the database password for this instance (or `nil`).

### query: ,...

- (NSMutableArray*) query: (NSString*)stmt,...;

Perform arbitrary query which returns values.

This method handles its arguments in the same way as the -buildQuery:,... method and returns the result of the query.

       result = [db query: @"SELECT Name FROM ", table, nil];

Upon error, an exception is raised.

The query returns an array of records (each of which is represented by an SQLRecord object).

Each SQLRecord object contains one or more fields, in the order in which they occurred in the query. Fields may also be retrieved by name.

NULL field items are returned as NSNull objects.

Most other field items are returned as NSString objects.

Date and timestamp field items are returned as NSDate objects.

### query: with:

- (NSMutableArray*) query: (NSString*)stmt with: (NSDictionary*)values;
Takes the query statement and substitutes in values from the dictionary (in the same manner as the -buildQuery:with: method) then executes the query and returns the response.

       result = [db query: @"SELECT Name FROM {Table} WHERE ID = {ID}"
                     with: values];

Any non-string values in the dictionary will be replaced by the results of the -quote: method.
The markup format may also be {key?default} where default is a string to be used if there is no value for the key in the dictionary.

### quote:

- (NSString*) quote: (id)obj;
Convert an object to a string suitable for use in an SQL query.
Normally the -execute:,... , and -query:,... methods will call this method automatically for everything apart from string objects.
Strings have to be handled specially, because they are used both for parts of the SQL command, and as values (where they need to be quoted). So where you need to pass a string value which needs quoting, you must call this method explicitly.
Subclasses may override this method to provide appropriate quoting for types of object which need database backend specific quoting conventions. However, the defalt implementation should be OK for most cases.
This method makes use of -quoteString: to quote literal strings.
The base class implementation formats NSDate objects as
YYYY-MM-DD hh:mm:ss.mmm ?ZZZZ
NSData objects are not quoted... they must not appear in queries, and where used for insert/update operations, they need to be passed to the -backendExecute: method unchanged.
For a `nil` object, we return NULL.
For a number, we simply convert directly to a string.
For a date, we convert to the text format used by the database, and add leading and trailing quotes.
For a data object, we don't quote... the other parts of the code need to know they have an NSData object and pass it on unchanged to the -backendExecute: method.
Just in case an NSNull subclass has been created by someone. The normal NSNull instance should have been handled earlier.
For an NSArray or NSSet, we produce a bracketed list of the (quoted) objects in the array.
For any other type of data, we just produce a quoted string representation of the objects description.

### quoteBigInteger:

- (NSString*) quoteBigInteger: (int64_t)i;
Convert a big (64 bit) integer to a string suitable for use in an SQL query.

### quoteCString:

- (NSString*) quoteCString: (const char*)s;
Convert a 'C' string to a string suitable for use in an SQL query by using -quoteString: to convert it to a literal string format.
NB. a null pointer is treated as an empty string.

### quoteChar:

- (NSString*) quoteChar: (char)c;
Convert a single character to a string suitable for use in an SQL query by using -quoteString: to convert it to a literal string format.
NB. a nul character is not allowed and will cause an exception.

### quoteFloat:

- (NSString*) quoteFloat: (float)f;
Convert a float to a string suitable for use in an SQL query.

### quoteInteger:

- (NSString*) quoteInteger: (int)i;
Convert an integer to a string suitable for use in an SQL query.

### quoteString:

- (NSString*) quoteString: (NSString*)s;
Convert a string to a form suitable for use as a string literal in an SQL query.
Subclasses may override this for non-standard literal string quoting conventions.

### quotef: ,...

- (NSString*) quotef: (NSString*)fmt,...;
Produce a quoted string from the supplied arguments (printf style).

### rollback

- (void) rollback;
Revert a transaction for this database client.
If there is no transaction in progress, this method does nothing.

NB. You must not execute an SQL statement which would commit or rollback a transaction directly... use only this method or the -rollback method.

Where possible, consider using the SQLTransaction class rather than calling -begin -commit or -rollback yourself.

### setDatabase:

- (void) setDatabase: (NSString*)s;
Set the database host/name for this object.
This is called automatically to configure the connection... you normally shouldn't need to call it yourself.

### setName:

- (void) setName: (NSString*)s;
Set the database reference name for this object. This is used to differentiate between multiple connections to the database.
This is called automatically to configure the connection... you normally shouldn't need to call it yourself.
NB. attempts to change the name of an instance to that of an existing instance are ignored.

### setPassword:

- (void) setPassword: (NSString*)s;
Set the database password for this object.
This is called automatically to configure the connection... you normally shouldn't need to call it yourself.

### setShouldTrim:

- (void) setShouldTrim: (BOOL)aFlag;
Sets an internal flag to indicate whether leading and trailing white space characters should be removed from values retrieved from the database by the receiver.

### setUser:

- (void) setUser: (NSString*)s;
Set the database user for this object.
This is called automatically to configure the connection... you normally shouldn't need to call it yourself.

### simpleExecute:

- (NSInteger) simpleExecute: (NSArray*)info;
Calls -backendExecute: in a safe manner.
Handles locking.
Maintains -lastOperation date.
Returns the result of -backendExecute:

### simpleQuery:

- (NSMutableArray*) simpleQuery: (NSString*)stmt;
Calls -simpleQuery:recordType:listType: with the default record class and default array class.

### simpleQuery: recordType: listType:

- (NSMutableArray*) simpleQuery: (NSString*)stmt recordType: (id)rtype listType: (id)ltype;
Calls -backendQuery:recordType:listType: in a safe manner.
Handles locking.
Maintains -lastOperation date.
The value of rtype must respond to the [SQLRecord +newWithValues:keys:count:] method.
If rtype is `nil` then the SQLRecord class is used.
The value of ltype must respond to the [NSObject +alloc] method to produce a container which must repond to the [NSMutableArray -initWithCapacity:] method to initialise itsself and the [NSMutableArray -addObject:] method to add records to the list.
If ltype is `nil` then the NSMutableArray class is used.
This library provides a few helper classes to provide alternative values for rtype and ltype.

### user

- (NSString*) user;
Return the database user for this instance (or `nil`).

## Instance Variables for SQLClient Class

### _cache

@protected GSCache* _cache;
The cache for query results
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _cacheThread

@protected NSThread* _cacheThread;
Thread for cache queries
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _client

@protected NSString* _client;
Identifier within backend
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _connectFails

@protected unsigned int _connectFails;
The count of connection failures
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _database

@protected NSString* _database;
The configured database name/host
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _debugging

@protected unsigned int _debugging;
The current debugging level
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _duration

@protected NSTimeInterval _duration;
Duration logging threshold
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _extra

@protected void* _extra;
Allow for extensions by allocating memory and pointing to it from the _extra ivar. That way we can avoid binary incompatibility between minor releases.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _inTransaction

@protected BOOL _inTransaction;
A flag indicating whether this instance is currently within a transaction. This variable must only be set by the -begin , -commit or -rollback methods.
Are we inside a transaction?
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _lastOperation

@protected NSTimeInterval _lastOperation;
Timestamp of completion of last operation.
Maintained by -simpleExecute: -simpleQuery:recordType:listType: and -cache:simpleQuery:recordType:listType: Also set for a failed connection attempt, but not reported by the -lastOperation method in that case.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _lastStart

@protected NSTimeInterval _lastStart;
Last op start or connect
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _name

@protected NSString* _name;
Unique identifier for instance
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _names

@protected NSCountedSet* _names;
Track notification names
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _observers

@protected NSMapTable* _observers;
Observations of async events
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _password

@protected NSString* _password;
The configured password
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _pool

@protected SQLClientPool* _pool;
The pool of the client (or `nil`)
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _shouldTrim

@protected BOOL _shouldTrim;
A flag indicating whether leading and trailing white space in values read from the database should automatically be removed.
This should only be modified by the -setShouldTrim: method.
Should whitespace be trimmed?
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _statements

@protected NSMutableArray* _statements;
Uncommitted statements
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _user

@protected NSString* _user;
The configured user
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### connected

@protected BOOL connected;
A flag indicating whether this instance is currently connected to the backend database server. This variable must only be set by the -backendConnect or -backendDisconnect methods.

### extra

@protected void* extra;
For subclass specific data

### lock

@protected NSRecursiveLock* lock;
Maintain thread-safety

# Software documentation for the SQLClientPool class

## SQLClientPool : NSObject

> Declared in:
>   SQLClient.h

An SQLClientPool instance may be used to create/control a pool of client objects. Code may obtain autoreleased proxies to the clients from the pool and use them safe in the knowledge that they won't be used anywhere else... as soon as the client would be deallocated, it is returned to the pool.

All clients in the pool share the same cache object, so query results cached by one client will be available to other clients in the pool.

Instance Variables
Method summary

- -availableConnections
- -initWithConfiguration:name:max:min:
- -maxConnections
- -minConnections
- -provideClient
- -provideClientBeforeDate:
- -setCache:
- -setCacheThread:
- -setDebugging:
- -setDurationLogging:
- -setMax:min:
- -statistics
- -swallowClient:

### availableConnections

- (int) availableConnections;
Returns the count of currently available connections in the pool.

### initWithConfiguration: name: max: min:

- (id) initWithConfiguration: (NSDictionary*)config name: (NSString*)reference max: (int)maxConnections min: (int)minConnections;
Creates a pool of clients using a single client configuration.
Calls -initWithConfiguration:name:pool: (passing `NO` to say the client is not in a pool) to create each client.
The value of maxConnections is the size of the pool (ie the number of clients created) and thus the maximum number of concurrent connections to the database server.
The value of minConnections is the minimum number of connected clients normally expected to be in the pool. The pool tries to ensure that it doesn't contain more than this number of idle connected clients.

### maxConnections

- (int) maxConnections;
Return the maximum number of database connections in the pool.

### minConnections

- (int) minConnections;
Return the minimum number of database connections in the pool.

### provideClient

- (SQLClient*) provideClient;
Fetches an (autoreleased) client from the pool.
This method blocks indefinitely waiting for a client to become available in the pool.

### provideClientBeforeDate:

- (SQLClient*) provideClientBeforeDate: (NSDate*)when;
Fetches an (autoreleased) client from the pool.
If no client is or becomes available before the specified date then the method returns `nil`.
If when is `nil` then a date in the distant future is used so that the method will effectively wait forever to get a client.

### setCache:

- (void) setCache: (GSCache*)aCache;
Sets the cache for all the clients in the pool.

### setCacheThread:

- (void) setCacheThread: (NSThread*)aThread;
Sets the cache thread for all the clients in the pool.

### setDebugging:

- (void) setDebugging: (unsigned int)level;
Set the debugging level for all clients in the pool.

### setDurationLogging:

- (void) setDurationLogging: (NSTimeInterval)threshold;
Set the duration logging threshold for all clients in the pool.

### setMax: min:

- (void) setMax: (int)maxConnections min: (int)minConnections;
Sets the pool size limits (number of connections we try to maintain).
The value of maxConnections is the size of the pool (ie the number of clients created) and thus the maximum number of concurrent connections to the database server.
The value of minConnections is the minimum number of connected clients normally expected to be in the pool. The pool tries to ensure that it doesn't contain more than this number of idle connected clients.
The value of maxConnections must be greater than or equal to that of minConnections and may not be greater than 100. The value of minConnections must be less than or equal to that of maxConnections and may not be less than 1.

### statistics

- (NSString*) statistics;
Returns a string describing the usage of the pool.

### swallowClient:

- (BOOL) swallowClient: (SQLClient*)client;
Puts the client back in the pool. This happens automatically when a client from a pool would normally be deallocated so you don't generally need to do it.
Returns `YES` if the supplied client was from the pool, `NO` otherwise.
If the swallowed client would take the count of idle client connections in the pool above the configured minimum, the oldest (ie longest idle) client in the pool is disconnected.

## Instance Variables for SQLClientPool Class

### _config

@protected NSDictionary* _config;
The pool configuration object
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _debugging

@protected unsigned int _debugging;
The current debugging level
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _delayWaits

@protected NSTimeInterval _delayWaits;
Time waiting for provisions
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _delayed

@protected uint64_t _delayed;
Count of delayed provisions
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _duration

@protected NSTimeInterval _duration;
Duration logging threshold
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _failWaits

@protected NSTimeInterval _failWaits;
Time waiting for timewouts
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _failed

@protected uint64_t _failed;
Count of timed out provisions
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _immediate

@protected uint64_t _immediate;
Immediate client provisions
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _longest

@protected NSTimeInterval _longest;
Count of longest delay
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _name

@protected NSString* _name;
The pool configuration name
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### c

@protected SQLClient** c;
The clients of the pool.

### lock

@protected NSConditionLock* lock;
Controls access to the pool contents

### max

@protected int max;
Maximum connection count

### min

@protected int min;
Minimum connection count

### u

@protected BOOL* u;
Whether the client is in use.

# Software documentation for the SQLDictionaryBuilder class

## SQLDictionaryBuilder : NSObject

> Declared in:
>   SQLClient.h

Description forthcoming.

Instance Variables
Method summary

- -addObject:
- -alloc
- -content
- -initWithCapacity:
- -mutableCopyWithZone:
- -newWithValues:keys:count:

### addObject:

- (void) addObject: (id)anObject;
No need to do anything... the object will already have been added by the -newWithValues:keys:count: method.

### alloc

- (id) alloc;
When a container is supposed to be allocated, we just return the receiver (which will then quietly ignore -addObject: messages).

### content

- (NSMutableDictionary*) content;
Returns the content dictionary for the receiver.

### initWithCapacity:

- (id) initWithCapacity: (NSUInteger)capacity;
Creates a new content dictionary... this method will be called automatically by the SQLClient object when it performs a query, so there is no need to call it at any other time.

### mutableCopyWithZone:

- (id) mutableCopyWithZone: (NSZone*)aZone;
Makes a mutable copy of the content dictionary (called when a caching query uses this helper to produce the cached collection).

### newWithValues: keys: count:

- (id) newWithValues: (id*)values keys: (NSString**)keys count: (unsigned int)count;
This is the main workhorse of the class... it is called once for every record read from the database, and is responsible for adding that record to the content dictionary. The default implementation, instead of creating an object to hold the supplied record data, uses the two fields from the record as a key-value pair to add to the content dictionary, and returns `nil` as the record object. It's OK to return a `nil` object since we ignore the -addObject: argument.

## Instance Variables for SQLDictionaryBuilder Class

### content

@protected NSMutableDictionary* content;
Description forthcoming.

# Software documentation for the SQLRecord class

## SQLRecord : NSArray

> Declared in:
>   SQLClient.h

An enhanced array to represent a record returned from a query. You should NOT try to create instances of this class except via the +newWithValues:keys:count: method.

SQLRecord is the abstract base class of a class cluster. If you wish to subclass it you must implement the primitive methods +newWithValues:keys:count: -count -keyAtIndex: -objectAtIndex: and -replaceObjectAtIndex:withObject:

NB. You do not need to use SQLRecord (or a subclass of it), all you actually need to supply is a class which responds to the +newWithValues:keys:count: method that the system uses to create new records... none of the other methods of the SQLRecord class are used internally by the SQLClient system.

Method summary

- +newWithValues:keys:count:
- -allKeys
- -count
- -dictionary
- -getKeys:
- -getObjects:
- -keyAtIndex:
- -objectAtIndex:
- -objectForKey:
- -replaceObjectAtIndex:withObject:
- -setObject:forKey:
- -sizeInBytes:

### newWithValues: keys: count:

+ (id) newWithValues: (id*)v keys: (NSString**)k count: (unsigned int)c;
Create a new SQLRecord containing the specified fields.
NB. The values and keys are retained by the record rather than being copied.
A `nil` value is represented by [NSNull null].
Keys must be unique string values (case insensitive comparison).

### allKeys

- (NSArray*) allKeys;
Returns an array containing the names of all the fields in the record.

### count

- (NSUInteger) count;
Returns the number of items in the record.
Subclasses must implement this method.

### dictionary

- (NSMutableDictionary*) dictionary;
Return the record as a mutable dictionary with the keys as the record field names standardised to be lowercase strings.

### getKeys:

- (void) getKeys: (id*)buf;
Optimised mechanism for retrieving all keys in order.

### getObjects:

- (void) getObjects: (id*)buf;
Optimised mechanism for retrieving all objects.

### keyAtIndex:

- (NSString*) keyAtIndex: (NSUInteger)index;
Subclasses must override this method.
Returns the key at the specified indes.

### objectAtIndex:

- (id) objectAtIndex: (NSUInteger)index;
Subclasses must override this method.
Returns the object at the specified indes.

### objectForKey:

- (id) objectForKey: (NSString*)key;
Returns the value of the named field.
The field name is case insensitive.

### replaceObjectAtIndex: withObject:

- (void) replaceObjectAtIndex: (NSUInteger)index withObject: (id)anObject;
Replaces the value at the specified index.
Subclasses must implement this method.

### setObject: forKey:

- (void) setObject: (id)anObject forKey: (NSString*)aKey;
Replaces the value of the named field.
The field name is case insensitive.
NB. You must be careful not to change the contents of a record which has been cached (unless you are sure you really want to), as you will be changing the contents of the cache, not just a private copy.

### sizeInBytes:

- (NSUInteger) sizeInBytes: (NSMutableSet*)exclude;
Return approximate size of this record in bytes.
The exclude set is used to specify objects to exclude from the calculation (to prevent recursion etc).

# Software documentation for the SQLSetBuilder class

## SQLSetBuilder : NSObject

> Declared in:
>   SQLClient.h

Description forthcoming.

Instance Variables
Method summary

- -addObject:
- -added
- -alloc
- -content
- -initWithCapacity:
- -mutableCopyWithZone:
- -newWithValues:keys:count:

### addObject:

- (void) addObject: (id)anObject;
No need to do anything... the object will already have been added by the -newWithValues:keys:count: method.

### added

- (NSUInteger) added;
Returns the number of objects actually added to the counted set.

### alloc

- (id) alloc;
When a container is supposed to be allocated, we just return the receiver (which will then quietly ignore -addObject: messages).

### content

- (NSCountedSet*) content;
Returns the counted set for the receiver.

### initWithCapacity:

- (id) initWithCapacity: (NSUInteger)capacity;
Creates a new content set... this method will be called automatically by the SQLClient object when it performs a query, so there is no need to call it at any other time.

### mutableCopyWithZone:

- (id) mutableCopyWithZone: (NSZone*)aZone;
Makes a mutable copy of the content dictionary (called when a caching query uses this helper to produce the cached collection).

### newWithValues: keys: count:

- (id) newWithValues: (id*)values keys: (NSString**)keys count: (unsigned int)count;
This is the main workhorse of the class... it is called once for every record read from the database, and is responsible for adding that record to the content set. The default implementation, instead of creating an object to hold the supplied record data, uses the singe field from the record to add to the content set, and returns `nil` as the record object. It's OK to return a `nil` object since we ignore the -addObject: argument.

## Instance Variables for SQLSetBuilder Class

### added

@protected NSUInteger added;
Description forthcoming.

### content

@protected NSCountedSet* content;
Description forthcoming.

# Software documentation for the SQLSingletonBuilder class

## SQLSingletonBuilder : NSObject

> Declared in:
>   SQLClient.h

Description forthcoming.
Method summary

- -newWithValues:keys:count:

### newWithValues: keys: count:

- (id) newWithValues: (id*)values keys: (NSString**)keys count: (unsigned int)count;
Description forthcoming.

# Software documentation for the SQLTransaction class

## SQLTransaction : NSObject

> Declared in:
>   SQLClient.h

> Conforms to:
>   NSCopying

The SQLTransaction transaction class provides a convenient mechanism for grouping together a series of SQL statements to be executed as a single transaction. It avoids the need for handling begin/commit, and should be as efficient as reasonably possible.
You obtain an instance by calling [SQLClient -transaction] , add SQL statements to it using the -add:,... and/or -add:with: methods, and then use the -execute method to perform all the statements as a single operation.
Any exception is caught and re-raised in the -execute method after any tidying up to leave the database in a consistent state.
NB. This class is not in itsself thread-safe, though the underlying database operations should be. If you have multiple threads, you should create multiple SQLTransaction instances, at least one per thread.

Instance Variables
Method summary

- -add:,...
- -add:with:
- -append:
- -copyWithZone:
- -count
- -db
- -execute
- -executeBatch
- -executeBatchReturningFailures:logExceptions:
- -insertTransaction:atIndex:
- -removeTransactionAtIndex:
- -reset
- -setMerge:
- -totalCount
- -transactionAtIndex:

### add: ,...

- (void) add: (NSString*)stmt,...;
Adds an SQL statement to the transaction. This is similar to [SQLClient -execute:,...] but does not cause any database operation until -execute is called, so it will not raise a database exception.

### add: with:

- (void) add: (NSString*)stmt with: (NSDictionary*)values;
Adds an SQL statement to the transaction. This is similar to [SQLClient -execute:with:] but does not cause any database operation until -execute is called, so it will not raise a database exception.

### append:

- (void) append: (SQLTransaction*)other;
Appends a copy of the other transaction to the receiver.
This provides a convenient way of merging transactions which have been built by different code modules, in order to have them all executed together in a single operation (for efficiency etc).
This does not alter the other transaction, so if the execution of a group of merged transactions fails, it is then possible to attempt to commit the individual transactions separately.
NB. All transactions appended must be using the same database connection (SQLClient instance).

### copyWithZone:

- (id) copyWithZone: (NSZone*)z;
Make a copy of the receiver.

### count

- (NSUInteger) count;
Returns the number of individual statements and/or subsidiary transactions which have been added to the receiver. For a count of the total number of statements, use the -totalCount method.

### db

- (SQLClient*) db;
Returns the database client with which this instance operates.
This client is retained by the transaction.

### execute

- (void) execute;

Performs any statements added to the transaction as a single operation. If any problem occurs, an NSException is raised, but the database connection is left in a consistent state and a partially completed operation is rolled back.

NB. If the database is not already in a transaction, this implicitly calls the -begin method to start the transaction before executing the statements.
The method always commits the transaction, even if the transaction was begun earlier rather than in -execute .
This behavior allows you to call [SQLClient -begin] , then run one or more queries, build up a transaction based upon the query results, and then -execute that transaction, causing the entire process to be commited as a single transaction.

### executeBatch

- (unsigned) executeBatch;
Convenience method which calls -executeBatchReturningFailures:logExceptions: with a `nil` failures argument and exception logging off.

### executeBatchReturningFailures: logExceptions:

- (unsigned) executeBatchReturningFailures: (SQLTransaction*)failures logExceptions: (BOOL)log;

This is similar to the -execute method, but may allow partial execution of the transaction if appropriate:

If the transaction was created using the [SQLClient -batch:] method and the transaction as a whole fails, individual statements are retried.
The stopOnFailure flag for the batch creation indicates whether the retries are stopped at the first statement to fail, or continue (skipping any failed statements).

If the transaction has had transactions appended to it, those subsidiary transactions may succeed or fail atomically depending on their individual attributes.

If the transaction was not created using [SQLClient -batch:] , then calling this method is equivalent to calling the -execute method.

If any statements/transactions in the batch fail, they are added to the transaction supplied in the failures parameter (if it's not `nil`) so that you can retry them later.
NB. statements/transactions which are not executed at all (because the batch is set to stop on the first failure) are also added to the failures transaction.

If the log argument is `YES`, then any exceptions encountered when executing the batch are logged using the [SQLClient -debug:,...] method, even if debug logging is not enabled with [SQLClient -setDebugging:] .

The method returns the number of statements which actually succeeded.

### insertTransaction: atIndex:

- (void) insertTransaction: (SQLTransaction*)trn atIndex: (unsigned)index;
Insert trn at the index'th position in the receiver.
The transaction trn must be non-empty and must use the same database client as the receiver.

### removeTransactionAtIndex:

- (void) removeTransactionAtIndex: (unsigned)index;
Remove the index'th transaction or statement from the receiver.

### reset

- (void) reset;
Resets the transaction, removing all previously added statements. This allows the transaction object to be re-used for multiple transactions.

### setMerge:

- (uint8_t) setMerge: (uint8_t)history;

Use this method to enable merging of statemements subsequently added or appended to the receiver. The history argument specifies how many of the most recent statements in the transaction should be checked for merging in a new statement, with a value of zero meaning that no merging is done.
Returns the previous setting for the transaction.

You may use this feature with an insert statement of the form:
INSERT INTO table (fieldnames) VALUES (values);
For databases which support multiline inserts such that they can be merged into something of the form: INSERT INTO table (fieldnames) VALUES (values1),(values2),...;

Or may use this with an update or delete statement of the form:
command table SET settings WHERE condition;
So that statements may be merged into:
command table SET settings WHERE (condition1) OR (condition2) OR...;

If no opportunity for merging is found, the new statement is simply added to the transaction.
Caveats:
1. databases may not actually support multiline insert.
2. Merging is done only if the statement up to the string 'VALUES' (for insert) or 'WHERE' (for update) matches.
3. Merging into any of the last N statements (where N is greater than 1) may of course change the order of statements in the transaction, so care must be taken not to use this feature where that might matter.
4. This is a simple text match rather than sql syntactic analysis, so it's possible to confuse the process with complex statements.

### totalCount

- (unsigned) totalCount;
Returns the total count of statements in this transaction including those in any subsidiary transactions. For a count of the statements and/or transactions directly added to the receiver, use the -count method.

### transactionAtIndex:

- (SQLTransaction*) transactionAtIndex: (unsigned)index;
Return an autoreleased copy of the index'th transaction or statement added to the receiver.
Since the returned transaction contains a copy of the statement/transaction in the receiver, you can modify it without effecting the original.

## Instance Variables for SQLTransaction Class

### _batch

@protected BOOL _batch;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _count

@protected unsigned int _count;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _db

@protected SQLClient* _db;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _info

@protected NSMutableArray* _info;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _merge

@protected uint8_t _merge;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _stop

@protected BOOL _stop;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the SQLClient(Caching) category

## SQLClient(Caching)

> Declared in:
>   SQLClient.h

This category provides methods for caching the results of queries in order to reduce the number of client-server trips and the database load produced by an application which needs update its information from the database frequently.
Method summary

- -cache
- -cache:query:,...
- -cache:query:with:
- -cache:simpleQuery:
- -cache:simpleQuery:recordType:listType:
- -setCache:
- -setCacheThread:

### cache

- (GSCache*) cache;
Returns the cache used by the receiver for storing the results of requests made through it. Creates a new cache if necessary.

### cache: query: ,...

- (NSMutableArray*) cache: (int)seconds query: (NSString*)stmt,...;
Calls -cache:simpleQuery:recordType:listType: with the default record class, array class, and with a query string formed from stmt and the following values (if any).

### cache: query: with:

- (NSMutableArray*) cache: (int)seconds query: (NSString*)stmt with: (NSDictionary*)values;
Calls -cache:simpleQuery:recordType:listType: with the default record class array class and with a query string formed from stmt and values.

### cache: simpleQuery:

- (NSMutableArray*) cache: (int)seconds simpleQuery: (NSString*)stmt;
Calls -cache:simpleQuery:recordType:listType: with the default record class and array class.

### cache: simpleQuery: recordType: listType:

- (NSMutableArray*) cache: (int)seconds simpleQuery: (NSString*)stmt recordType: (id)rtype listType: (id)ltype;
If the result of the query is already cached and has not expired, return it. Otherwise, perform the query and cache the result giving it the specified lifetime in seconds.
If seconds is negative, the query is performed irrespective of whether it is already cached, and its absolute value is used to set the lifetime of the results.
If seconds is zero, the cache for this query is emptied.
Handles locking.
Maintains -lastOperation date.
The value of rtype must respond to the [SQLRecord +newWithValues:keys:count:] method.
If rtype is `nil` then the SQLRecord class is used.
The value of ltype must respond to the [NSObject +alloc] method to produce a container which must repond to the [NSMutableArray -initWithCapacity:] method to initialise itsself and the [NSMutableArray -addObject:] method to add records to the list.
If ltype is `nil` then the NSMutableArray class is used.
The list produced by this argument is used as the return value of this method.
If a cache thread has been set using the -setCacheThread: method, and the -cache:simpleQuery:recordType:listType: method is called from a thread other than the cache thread, then any query to retrieve uncached data will be performed in the cache thread, and for cached (but expired) data, the old (expired) results may be returned... in which case an asynchronous query to update the cache will be executed as soon as possible in the cache thread.

### setCache:

- (void) setCache: (GSCache*)aCache;
Sets the cache to be used by the receiver for storing the results of requests made through it.
If aCache is `nil`, the current cache is released, and a new cache will be automatically created as soon as there is a need to cache anything.

### setCacheThread:

- (void) setCacheThread: (NSThread*)aThread;
Sets the thread to be used to retrieve data to populate the cache.
All cached queries will be performed in this thread (if non-nil).
The setting of a thread for the cache also implies that expired items in the cache may not be removed when they are queried from another thread, rather they can be kept (if they are not too old) and an asynchronous query to update them will be run on the cache thread.
The rule is that, if the item's age is more than twice its nominal lifetime, it will be retrieved immediately, otherwise it will be retrieved asynchronously.
Currently this may only be the main thread or `nil`. Any attempt to set another thread will use the main thread instead.

# Software documentation for the SQLClient(Convenience) category

## SQLClient(Convenience)

> Declared in:
>   SQLClient.h

This category contains convenience methods including those for frequently performed database operations... message logging etc.
Method summary

- -batch:
- -columns:
- -queryRecord:,...
- -queryString:,...
- -singletons:
- -transaction

### batch:

- (SQLTransaction*) batch: (BOOL)stopOnFailure;
Returns a transaction object configured to handle batching and execute part of a batch of statements if execution of the whole using the [SQLTransaction -executeBatch] method fails.
If stopOnFailure is `YES` than execution of the transaction will stop with the first statement to fail, otherwise it will execute all the statements it can, skipping any failed statements.

### columns:

- (NSMutableArray*) columns: (NSMutableArray*)records;
Convenience method to deal with the results of a query converting the normal array of records into an array of record columns. Each column in the array is an array containing all the values from that column.

### queryRecord: ,...

- (SQLRecord*) queryRecord: (NSString*)stmt,...;
Executes a query (like the -query:,... method) and checks the result (raising an exception if the query did not contain a single record) and returns the resulting record.

### queryString: ,...

- (NSString*) queryString: (NSString*)stmt,...;
Executes a query (like the -query:,... method) and checks the result.
Raises an exception if the query did not contain a single record, or if the record did not contain a single field.
Returns the resulting field as a string.

### singletons:

- (void) singletons: (NSMutableArray*)records;
Convenience method to deal with the results of a query where each record contains a single field... it converts the array of records returned by the query to an array containing the fields.
NB. This does not check that the contents of the records array are actually instances of SQLRecord , so you must ensure you don't call it more than once on the same array (something that may happen if you retrieve the array using a cache based query).

### transaction

- (SQLTransaction*) transaction;
Creates and returns an autoreleased SQLTransaction instance which will use the receiver as the database connection to perform transactions.

# Software documentation for the SQLClient(Logging) category

## SQLClient(Logging)

> Declared in:
>   SQLClient.h

This category porovides basic methods for logging debug information.
Method summary

- +debugging
- +durationLogging
- +setDebugging:
- +setDurationLogging:
- -debug:,...
- -debugging
- -durationLogging
- -setDebugging:
- -setDurationLogging:

### debugging

+ (unsigned int) debugging;
Return the class-wide debugging level, which is inherited by all newly created instances.

### durationLogging

+ (NSTimeInterval) durationLogging;
Return the class-wide duration logging threshold, which is inherited by all newly created instances.

### setDebugging:

+ (void) setDebugging: (unsigned int)level;
Set the debugging level to be inherited by all new instances.
See [SQLClient(Logging) -setDebugging:] for controlling an individual instance of the class.

### setDurationLogging:

+ (void) setDurationLogging: (NSTimeInterval)threshold;
Set the duration logging threshold to be inherited by new instances.
See [SQLClient(Logging) -setDurationLogging:] for controlling an individual instance of the class.

### debug: ,...

- (void) debug: (NSString*)fmt,...;
The default implementation calls NSLogv to log a debug message.
Override this in a category to provide more sophisticated logging.
Do NOT override with code which can be slow or which calls (directly or indirectly) any SQLCLient methods, since this method will be used inside locked regions of the SQLClient code and you could cause deadlocks or long delays to other threads using the class.

### debugging

- (unsigned int) debugging;
Return the current debugging level.
A level of zero (default) means that no debug output is produced, except for that concerned with logging the database transactions taking over a certain amount of time (see the -setDurationLogging: method).

### durationLogging

- (NSTimeInterval) durationLogging;
Returns the threshold above which queries and statements taking a long time to execute are logged. A negative value (default) indicates that this logging is disabled. A value of zero means that all statements are logged.

### setDebugging:

- (void) setDebugging: (unsigned int)level;
Set the debugging level of this instance... overrides the default level inherited from the class.

### setDurationLogging:

- (void) setDurationLogging: (NSTimeInterval)threshold;
Set a threshold above which queries and statements taking a long time to execute are logged. A negative value (default) disables this logging. A value of zero logs all statements.

# Software documentation for the SQLClient(Notifications) category

## SQLClient(Notifications)

> Declared in:
>   SQLClient.h

This category contains methods for asynchronous notification of events via the database (for those database backends which support it: currently only PostgreSQL).
Method summary

- -addObserver:selector:name:
- -postNotificationName:payload:
- -removeObserver:name:

### addObserver: selector: name:

- (void) addObserver: (id)anObserver selector: (SEL)aSelector name: (NSString*)name;
Adds anObserver to receive notifications when the backend database server sends an asynchronous event identified by the specified name (which must be a valid database identifier).
When a notification (NSNotification instance) is received by the method specified by aSelector, its object will be the SQLClient instance to which anObserver was added and its userInfo dictionary will contain the key 'Local' and possibly the key 'Payload'.
If the 'Local' value is the boolean `YES`, the notification originated as an action by this SQLClient instance.
If the 'Payload' value is not `nil`, then it is a string providing extra information about the notification.
NB. At the point when the observer is notified about an event the database client object will be locked and may not be used to query or modify the database (typically a database query will already be in progress). The method handling the notification must therefore handle any database operations in a later timeout.

### postNotificationName: payload:

- (void) postNotificationName: (NSString*)name payload: (NSString*)more;
Posts a notification via the database. The name is an SQL identifier (for which observers may have registered) and the extra payload information may be `nil` if not required.

### removeObserver: name:

- (void) removeObserver: (id)anObserver name: (NSString*)name;
Removes anObserver as an observer for asynchronous notifications from the database server. If name is omitted, the observer will be removed for all names.

# Software documentation for the SQLClient(Subclass) category

## SQLClient(Subclass)

> Declared in:
>   SQLClient.h

This category contains the methods which a subclass must override to provide a working instance, and helper methods for the backend implementations.
Application programmers should not call the backend methods directly.

When subclassing to produce a backend driver bundle, please be aware that the subclass must NOT introduce additional instance variables. Instead the extra instance variable is provided for use as a pointer to subclass specific data.

Method summary

- -backendConnect
- -backendDisconnect
- -backendExecute:
- -backendListen:
- -backendNotify:payload:
- -backendQuery:
- -backendQuery:recordType:listType:
- -backendUnlisten:
- -copyEscapedBLOB:into:
- -insertBLOBs:intoStatement:length:withMarker:length:giving:
- -lengthOfEscapedBLOB:

### backendConnect

- (BOOL) backendConnect;
Subclasses must override this method.
Attempts to establish a connection to the database server.
Returns a flag to indicate whether the connection has been established.
If a connection was already established, returns `YES` and does nothing.
You should not need to use this method normally, as it is called for you automatically when necessary.

Subclasses must implement this method to establish a connection to the database server process (and initialise the extra instance variable if necessary), setting the connected instance variable to indicate the state of the object.

This method must call +purgeConnections: to ensure that there is a free slot for the new connection.

Application code must not call this method directly, it is for internal use only. The -connect method calls this method if the connected instance variable is `NO`.

### backendDisconnect

- (void) backendDisconnect;
Subclasses must override this method.
Disconnect from the database unless already disconnected.

This method is called automatically when the receiver is deallocated or reconfigured, and may also be called automatically when there are too many database connections active.

If the receiver is an instance of a subclass which uses the extra instance variable, it must clear that variable in the -backendDisconnect method, because a reconfiguration may cause the class of the receiver to change.

This method must set the connected instance variable to `NO`.

Application code must not call this method directly, it is for internal use only. The -disconnect method calls this method if the connected instance variable is `YES`.

### backendExecute:

- (NSInteger) backendExecute: (NSArray*)info;
Subclasses must override this method.
Perform arbitrary operation which does not return any value.
This method has a single argument, an array containing the string representing the statement to be executed as its first object, and an optional sequence of data objects following it.

       [db backendExecute: [NSArray arrayWithObject:
         @"UPDATE MyTable SET Name = 'The name' WHERE ID = 123"]];

The backend implementation is required to perform the SQL statement using the supplied NSData objects at the points in the statement marked by the `'?'''?'` sequence. The marker saequences are inserted into the statement at an earlier stage by the -execute:,... and -execute:with: methods.

Callers should lock the instance using the lock instance variable for the duration of the operation, and unlock it afterwards.

NB. callers (other than the -begin , -commit , and -rollback methods) should not pass any statement to this method which would cause a transaction to begin or end.

Application code must not call this method directly, it is for internal use only.

Where the database backend support it, this method returns the count of the number of rows to which the operation applied. Otherwise this returns -1.

### backendListen:

- (void) backendListen: (NSString*)name;
Subclasses must override this method.
Called to enable asynchronous notification of database events using the specified name (which must be a valid identifier consisting of ascii letters, digits, and underscore characters, starting with a letter). Names are not case sensitive (so AAA is the same as aaa).
Repeated calls to list on the same name should be treated as a single call.
The backend is responsible for implicitly unlistening when a connection is closed.
There is a default implementation which does nothing ... for backends which don't support asynchronous notifications.
If a backend does support asynchronous notifications, it should do so by posting NSNotification instances to [NSNotificationCenter defaultCenter] using the SQLClient instance as the notification object and supplying any payload as a string using the 'Payload' key in the NSNotification userInfo dictionary. The userInfo dictionary should also contain a boolean (NSNumber) value, using the 'Local' key, to indicate whether the notification was sent by the current SQLClient instance or by some other client/

### backendNotify: payload:

- (void) backendNotify: (NSString*)name payload: (NSString*)more;
Subclasses must override this method.
The backend should implement this to send asynchronous notifications to anything listening for them. The name of the notification is an SQL identifier used for listening for the asynchronous data.
The payload string may be `nil` if no additional information is needed in the notification.

### backendQuery:

- (NSMutableArray*) backendQuery: (NSString*)stmt;
Calls -backendQuery:recordType:listType: with the default record class and array class.

### backendQuery: recordType: listType:

- (NSMutableArray*) backendQuery: (NSString*)stmt recordType: (id)rtype listType: (id)ltype;
Subclasses must override this method.

Perform arbitrary query which returns values.

       result = [db backendQuery: @"SELECT Name FROM Table"
                      recordType: [SQLRecord class]]
                        listType: [NSMutableArray class]];

Upon error, an exception is raised.

The query returns an array of records (each of which is represented by an SQLRecord object).

Each SQLRecord object contains one or more fields, in the order in which they occurred in the query. Fields may also be retrieved by name.

NULL field items are returned as NSNull objects.

Callers should lock the instance using the lock instance variable for the duration of the operation, and unlock it afterwards.

Application code must not call this method directly, it is for internal use only.

The rtype argument specifies an object to be used to create the records produced by the query.
This is provided as a performance optimisation when you want to store data directly into a special class of your own.
The object must respond to the [SQLRecord +newWithValues:keys:count:] method to produce a new record initialised with the supplied data.

The ltype argument specifies an object to be used to create objects to store the records produced by the query.
The should be a subclass of NSMutableArray. It must at least implement the [NSObject +alloc] method to create an instnce to store records. The instance must implement [NSMutableArray -initWithCapacity:] to initialise itsself and [NSMutableArray -addObject:] to allow the backend to add records to it.
For caching to work, it must be possible to make a mutable copy of the instance using the mutableCopy method.

### backendUnlisten:

- (void) backendUnlisten: (NSString*)name;
Subclasses must override this method.
Called to disable asynchronous notification of database events using the specified name. This has no effect if the name has not been used in an earlier call to -backendListen: , or if the name has already been unlistened since the last call to listen. on it.
There is a default implementation which does nothing... for backends which don't support asynchronous notifications.

### copyEscapedBLOB: into:

- (unsigned) copyEscapedBLOB: (NSData*)blob into: (void*)buf;
Subclasses must override this method.
This method is only for the use of the -insertBLOBs:intoStatement:length:withMarker:length:giving: method.
Subclasses which need to insert binary data into a statement must implement this method to copy the escaped data into place and return the number of bytes actually copied.

### insertBLOBs: intoStatement: length: withMarker: length: giving:

- (const void*) insertBLOBs: (NSArray*)blobs intoStatement: (const void*)statement length: (unsigned)sLength withMarker: (const void*)marker length: (unsigned)mLength giving: (unsigned*)result;

This method is a convenience method provided for subclasses which need to insert escaped binary data into an SQL statement before sending the statement to a backend server process. This method makes use of the -copyEscapedBLOB:into: and -lengthOfEscapedBLOB: methods, which must be implemented by the subclass.

The blobs array is an array containing the original SQL statement string (unused by this method) followed by the data items to be inserted.

The statement and sLength arguments specify the datastream to be copied and into which the BLOBs are to be inserted.

The marker and mLength arguments specify the sequence of marker bytes in the statement which indicate a position for insertion of an escaped BLOB.

The method returns either the original statement or a copy containing the escaped BLOBs. The length of the returned data is stored in result.

### lengthOfEscapedBLOB:

- (unsigned) lengthOfEscapedBLOB: (NSData*)blob;
Subclasses must override this method.
This method is only for the use of the -insertBLOBs:intoStatement:length:withMarker:length:giving: method.
Subclasses which need to insert binary data into a statement must implement this method to return the length of the escaped bytestream which will be inserted.

# SQLClient constants

### SQLClientDidConnectNotification

NSString* const SQLClientDidConnectNotification;
Notification sent when an instance becomes connected to the database server. The notification object is the instance connected.

### SQLClientDidDisconnectNotification

NSString* const SQLClientDidDisconnectNotification;
Notification sent when an instance becomes disconnected from the database server. The notification object is the instance disconnected.

# SQLClient variables

### SQLConnectionException

NSString* SQLConnectionException;
Exception for when a connection to the server is lost.

### SQLEmptyException

NSString* SQLEmptyException;
Exception for when a query is supposed to return data and doesn't.

### SQLException

NSString* SQLException;
Exception raised when an error with the remote database server occurs.

### SQLUniqueException

NSString* SQLUniqueException;
Exception for when an insert/update would break the uniqueness of a field or index.

# SQLClient functions

### SQLClientTimeLast

NSTimeInterval SQLClientTimeLast();
Returns the timestamp of the most recent call to SQLClientTimeNow() .

### SQLClientTimeNow

NSTimeInterval SQLClientTimeNow();
Convenience function to provide timing information quickly.
This returns the current date/time, and stores the value for use by the SQLClientTimeLast() function.

### SQLClientTimeStart

NSTimeInterval SQLClientTimeStart();
This returns the timestamp from which any of the SQLClient classes was first used or SQLClientTimeNow() was first called (whichever came first).

### SQLClientTimeTick

unsigned int SQLClientTimeTick();
A convenience method to return the current clock 'tick'... which is the current second based on the time we started. This does not check the current time, but relies on SQLClientTimeLast() returning an up to date value (so if you need an accurate tick, you should ensure that SQLClientTimeNow() is called at least once a second).
The returned value is always greater than zero, and is basically calculated as (SQLClientTimeLast() - SQLClientTimeStart() + 1).
In the event that the system clock is reset into the past, the value of SQLClientTimeStart() is automatically adjusted to ensure that the result of a call to SQLClientTimeTick() is never less than the result of any earlier call to the function.