Official Database Adapters for Induction
Switch branches/tags
Nothing to show
Pull request Compare This branch is even with paulrosania:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Writing a Database Adapter

Database adapters for Induction are designed to be easy to write. Adapters are packaged as bundles, with their primary class implementing the DBAdapter protocol. Here is a rundown of the roles and responsibilities of the adapter protocols (note, these interfaces are not final, and subject to evolve and change as the project matures):


Specifies a URL scheme, validates connection URLs and creates connections.

@protocol DBAdapter <NSObject>
+ (NSString *)primaryURLScheme;
+ (BOOL)canConnectWithURL:(NSURL *)url;
+ (id <DBConnection>)connectionWithURL:(NSURL *)url 
                                 error:(NSError **)error;


Initializes and manages a connection client, most often a C interface to a system library.

@protocol DBConnection <NSObject>
@property (nonatomic, readonly) NSURL *url;
@property (nonatomic, readonly) NSArray *databases;

- (id)initWithURL:(NSURL *)url;

- (BOOL)open;
- (BOOL)close;
- (BOOL)reset;


Represents an organized collection of data, most often corresponding to a database in the target platform.

It's principle responsibility is to populate the source list on the left side of the connection window.

@protocol DBDatabase <NSObject>
@property (nonatomic, readonly) id <DBConnection> connection;
@property (nonatomic, readonly) NSOrderedSet *dataSourceGroupNames;

- (NSArray *)dataSourcesForGroupNamed:(NSString *)groupName;


Following the interpretation used by Yahoo YUI, this is "an abstract representation of a live set of data that presents a common predictable API for other objects to interact with." Examples of this include SQL tables, MongoDB collections, collections of Redis keys according to their type, etc.

Data sources have their responsibilities split across three different protocols, representing the "Explore", "Query", and "Visualize" features of the application. By conforming to its respective protocol, the adapter makes itself available for that feature.

@protocol DBDataSource <NSObject>
- (NSUInteger)numberOfRecords;


@protocol DBExplorableDataSource <NSObject>
- (id <DBResultSet>)resultSetForRecordsAtIndexes:(NSIndexSet *)indexes                                                          
                                           error:(NSError **)error;


@protocol DBQueryableDataSource <NSObject>
- (id <DBResultSet>)resultSetForQuery:(NSString *)query 
                                error:(NSError **)error;


@protocol DBVisualizableDataSource <NSObject>
- (id <DBResultSet>)resultSetForDimension:(NSExpression *)dimension
                                 measures:(NSArray *)measures
                                    error:(NSError **)error;


Perhaps the most significant part of an adapter, this object represents a result set of data, and drives the display of information in tables and outlines. Whereas a SQL table is a DBDataSource, the first page of 1000 results would be a DBResultSet, and it is the result set that is displayed.

@protocol DBResultSet <NSObject>
- (NSUInteger)numberOfRecords;
- (NSArray *)recordsAtIndexes:(NSIndexSet *)indexes;

- (NSUInteger)numberOfFields;
- (NSString *)identifierForTableColumnAtIndex:(NSUInteger)index;
- (DBValueType)valueTypeForTableColumnAtIndex:(NSUInteger)index;
- (NSCell *)dataCellForTableColumnAtIndex:(NSUInteger)index;
- (NSSortDescriptor *)sortDescriptorPrototypeForTableColumnAtIndex:(NSUInteger)index;


Records correspond to rows, or individual documents in the result set, and are represented by an object conforming to the DBRecord protocol. DBResultSet fields correspond to columns or values, which are strings that are passed to DBRecord objects using valueForKey:.

Adapters to graph or document databases can optionally specify the child records, which can be expanded using disclosure indicators in an outline view.

@protocol DBRecord <NSObject>
- (id)valueForKey:(NSString *)key;
@property (nonatomic, readonly) NSArray *children;