SQL Relay C++ API
Public Member Functions | List of all members
sqlrcrud Class Reference

Inherits mvccrud.

Public Member Functions

 sqlrcrud ()
 
 ~sqlrcrud ()
 
void setSqlrConnection (sqlrconnection *con)
 
void setSqlrCursor (sqlrcursor *cur)
 
void setTable (const char *table)
 
void setIdSequence (const char *idsequence)
 
const char * getTable ()
 
const char * getIdSequence ()
 
bool buildQueries ()
 
void setPrimaryKeyColumn (const char *primarykey)
 
void setAutoIncrementColumn (const char *autoinc)
 
const char * getPrimaryKeyColumn ()
 
const char * getAutoIncrementColumn ()
 
void setCreateQuery (const char *createquery)
 
void setReadQuery (const char *readquery)
 
void setUpdateQuery (const char *updatequery)
 
void setDeleteQuery (const char *deletequery)
 
const char * getCreateQuery ()
 
const char * getReadQuery ()
 
const char * getUpdateQuery ()
 
const char * getDeleteQuery ()
 
void setReadQueryContainsPartialWhere (bool containspartial)
 
void setReadQueryContainsPartialOrderBy (bool containspartial)
 
void setUpdateQueryContainsPartialWhere (bool containspartial)
 
void setDeleteQueryContainsPartialWhere (bool containspartial)
 
bool getReadQueryContainsPartialWhere ()
 
bool getReadQueryContainsPartialOrderBy ()
 
bool getUpdateQueryContainsPartialWhere ()
 
bool getDeleteQueryContainsPartialWhere ()
 
bool doCreate (const char *const *columns, const char *const *values, const char *const *types)
 
bool doCreate (dictionary< const char *, const char * > *kvp)
 
bool doCreate (jsondom *j)
 
bool doRead (const char *criteria, const char *sort, uint64_t skip)
 
bool doRead (jsondom *j)
 
bool doUpdate (const char *const *columns, const char *const *values, const char *const *types, const char *criteria)
 
bool doUpdate (dictionary< const char *, const char * > *kvp, const char *criteria)
 
bool doUpdate (jsondom *j)
 
bool doDelete (const char *criteria)
 
bool doDelete (jsondom *j)
 
const char * getErrorMessage ()
 
int64_t getErrorCode ()
 
uint64_t getAffectedRows ()
 
scalarcollection< uint64_t > * getAffectedRowsScalar ()
 
listcollection< uint64_t > * getAffectedRowsList ()
 
dictionarycollection< const char *, uint64_t > * getAffectedRowsDictionary ()
 
tablecollection< uint64_t > * getAffectedRowsTable ()
 
scalarcollection< const char * > * getFirstFieldScalar ()
 
listcollection< const char * > * getFirstRowList ()
 
dictionarycollection< const char *, const char * > * getFirstRowDictionary ()
 
listcollection< const char * > * getFirstColumnList ()
 
tablecollection< const char * > * getResultSetTable ()
 

Detailed Description

The sqlrcrud class provides a generic CRUD (create, read, update, and delete) interface to SQL Relay.

A typical invocation of a mycrud class which implements mvccrud, from within the dao tier of an MVC application, would be something like:

// initialize crud sqlrconnection *con=new sqlrconnection(...); sqlrcursor *cur=new sqlrcursor(con); sqlrcrud *crud=new sqlrcrud();

crud->setSqlrConnection(con); crud->setSqlrCursor(cur); crud->setTable("mytable"); crud->setIdSequence("mytable_ids"); crud->buildQueries();

// read data crud->doRead(...);

// return results via instance of mvcresults mvcr->setSuccess(); mvcr->attachData("myresults","table",crud->getResultSetTable()); mvcr->getWatebasket()->attach(crud); mvcr->getWatebasket()->attach(con); mvcr->getWatebasket()->attach(cur);

Various methods such as doRead(), doUpdate(), and doDelete() take a "criteria" argument. This should be a JSON string in jsonlogic format (http://jsonlogic.com), and will be used to construct the where clause for these operations:

{ "and" : [ { "=" : [ { "var" : "col1" }, 1 ] }, { "!=" : [ { "var" : "col2" }, "one" ] } ] }

The doRead() method also takes a "sort" argument. This should be a JSON string conforming to the following format, and will be used to construct the order-by clause for these operations:

{ "col1" : "asc", "col2" : "asc", "col3" : "desc" }

The class also provides methods for overriding the template queries that are automatically built by buildQueries() as well as any primary key or autoincrement columns detected by buildQueries().

Constructor & Destructor Documentation

◆ sqlrcrud()

sqlrcrud::sqlrcrud ( )

Creates an instance of the sqlrcrud class.

◆ ~sqlrcrud()

sqlrcrud::~sqlrcrud ( )

Destroys this instance of the sqlrcrud class.

Member Function Documentation

◆ buildQueries()

bool sqlrcrud::buildQueries ( )

Uses the table set by setTable() and sequence set by setIdSequence() to construct template CRUD queries (insert, select, update, and delete queries). Also detects the primary key and autoincrement columns, if the table has any.

◆ doCreate() [1/3]

bool sqlrcrud::doCreate ( const char *const *  columns,
const char *const *  values,
const char *const *  types 
)

Executes the create (insert) query as either built by buildQueries() or overridden by setCreateQuery().

"columns" should contain the set of columns that corresponding elements of "values" will be inserted into.

"types" should contain the corresponding data type for each value:

  • "n" for numeric
  • "t" for true
  • "f" for false
  • "u" for null
  • "s" (or any other value) for string Otherwise "types" may be null, and the data type will be derived as "s", "n", or "u" from the value.

Note that if getAutoIncrementColumn() returns non-NULL (see getAutoIncrementColumn() for why this may be) then any value specified for that column will be overridden, such that the column will auto-increment. If getAutoIncrementColumn() returns NULL (see getAutoIncrementColumn() for why this may be) then any value specified for the autoincrement column will not be overridden.

Note that if getPrimaryKeyColumn() and getIdSequence() both return non-NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for that column will be overridden, such that the column will be populated from the id sequence. If either of getPrimaryKeyColumn() or getIdSequence() return NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for the primary column will not be overridden.

Returns true on success and false on error. On error, the code and message can be retrieved using getErrorCode() and getErrorMessage().

◆ doCreate() [2/3]

bool sqlrcrud::doCreate ( dictionary< const char *, const char * > *  kvp)

Executes the create (insert) query as either built by buildQueries() or overridden by setCreateQuery().

Keys of "kvp" and values of "kvp" should be set to the column/value pairs to be inserted. The data type of each value will be derived as "s", "n", or "u" from the value.

Note that if getAutoIncrementColumn() returns non-NULL (see getAutoIncrementColumn() for why this may be) then any value specified for that column will be overridden, such that the column will auto-increment. If getAutoIncrementColumn() returns NULL (see getAutoIncrementColumn() for why this may be) then any value specified for the autoincrement column will not be overridden.

Note that if getPrimaryKeyColumn() and getIdSequence() both return non-NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for that column will be overridden, such that the column will be populated from the id sequence. If either of getPrimaryKeyColumn() or getIdSequence() return NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for the primary column will not be overridden.

Returns true on success and false on error. On error, the code and message can be retrieved using getErrorCode() and getErrorMessage().

◆ doCreate() [3/3]

bool sqlrcrud::doCreate ( jsondom *  j)

Executes the create (insert) query as either built by buildQueries() or overridden by setCreateQuery(),

"j" should be a jsondom containing 1 object:

"data" should be a JSON object consisting of the column/value pairs to be inserted.

Note that if getAutoIncrementColumn() returns non-NULL (see getAutoIncrementColumn() for why this may be) then any value specified for that column will be overridden, such that the column will auto-increment. If getAutoIncrementColumn() returns NULL (see getAutoIncrementColumn() for why this may be) then any value specified for the autoincrement column will not be overridden.

Note that if getPrimaryKeyColumn() and getIdSequence() both return non-NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for that column will be overridden, such that the column will be populated from the id sequence. If either of getPrimaryKeyColumn() or getIdSequence() return NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for the primary column will not be overridden.

Returns true on success and false on error. On error, the code and message can be retrieved using getErrorCode() and getErrorMessage().

◆ doDelete() [1/2]

bool sqlrcrud::doDelete ( const char *  criteria)

Executes the delete query as either built by buildQueries() or overridden by setDeleteQuery().

"criteria" should be a JSON string representing the criteria that will be used to build the where clause, conforming to the format described in the class description.

Returns true on success and false on error. On error, the code and message can be retrieved using getErrorCode() and getErrorMessage().

◆ doDelete() [2/2]

bool sqlrcrud::doDelete ( jsondom *  j)

Executes the delete query as either built by buildQueries() or overridden by setDeleteQuery().

"j" should be a jsondom containing 1 object:

"criteria" should be a JSON object representing the criteria that will be used to build the where clause, conforming to the format described in the class description.

Returns true on success and false on error. On error, the code and message can be retrieved using getErrorCode() and getErrorMessage().

◆ doRead() [1/2]

bool sqlrcrud::doRead ( const char *  criteria,
const char *  sort,
uint64_t  skip 
)

Executes the read (select) query as either built by buildQueries() or overridden by setReadQuery().

"criteria" should be a JSON string representing the criteria that will be used to build the where clause, conforming to the format described in the class description.

"sort" should be a JSON string representing the criteria that will be used to build the order-by clause, conforming to the format described in the class description.

"skip" indicates how many rows to skip immediately (useful for paging).

Returns true on success and false on error. On error, the code and message can be retrieved using getErrorCode() and getErrorMessage().

◆ doRead() [2/2]

bool sqlrcrud::doRead ( jsondom *  j)

Executes the read (select) query as either built by buildQueries() or overridden by setReadQuery().

"j" should be a jsondom containing 3 objects:

"criteria" should be a JSON object representing the criteria that will be used to build the where clause, conforming to the format described in the class description.

"sort" should be a JSON object representing the criteria that will be used to build the order-by clause, conforming to the format described in the class description.

"skip" should be a number indicating how many rows to skip immediately (useful for paging).

Returns true on success and false on error. On error, the code and message can be retrieved using getErrorCode() and getErrorMessage().

◆ doUpdate() [1/3]

bool sqlrcrud::doUpdate ( const char *const *  columns,
const char *const *  values,
const char *const *  types,
const char *  criteria 
)

Executes the update query as either built by buildQueries() or overridden by setUpdateQuery().

"columns" and "values" should be set to the column/value pairs to be updated. "types" should be set to the corresponding data type for each value:

  • "n" for numeric
  • "t" for true
  • "f" for false
  • "u" for null
  • "s" (or any other value) for string Otherwise "types" may be null, and the data type will be derived as "s", "n", or "u" from the value.

"criteria" should be a JSON string representing the criteria that will be used to build the where clause, conforming to the format described in the class description.

Note that if getAutoIncrementColumn() returns non-NULL (see getAutoIncrementColumn() for why this may be) then any value specified for that column will be overridden, such that the column will auto-increment. If getAutoIncrementColumn() returns NULL (see getAutoIncrementColumn() for why this may be) then any value specified for the autoincrement column will not be overridden.

Note that if getPrimaryKeyColumn() and getIdSequence() both return non-NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for that column will be overridden, such that the column will be populated from the id sequence. If either of getPrimaryKeyColumn() or getIdSequence() return NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for the primary column will not be overridden.

Returns true on success and false on error. On error, the code and message can be retrieved using getErrorCode() and getErrorMessage().

◆ doUpdate() [2/3]

bool sqlrcrud::doUpdate ( dictionary< const char *, const char * > *  kvp,
const char *  criteria 
)

Executes the update query as either built by buildQueries() or overridden by setUpdateQuery().

Keys of "kvp" and values of "kvp" should be set to the column/value pairs to be updated. The data type of each value will be derived as "s", "n", or "u" from the value.

"criteria" should be a JSON string representing the criteria that will be used to build the where clause, conforming to the format described in the class description.

Note that if getAutoIncrementColumn() returns non-NULL (see getAutoIncrementColumn() for why this may be) then any value specified for that column will be overridden, such that the column will auto-increment. If getAutoIncrementColumn() returns NULL (see getAutoIncrementColumn() for why this may be) then any value specified for the autoincrement column will not be overridden.

Note that if getPrimaryKeyColumn() and getIdSequence() both return non-NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for that column will be overridden, such that the column will be populated from the id sequence. If either of getPrimaryKeyColumn() or getIdSequence() return NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for the primary column will not be overridden.

Returns true on success and false on error. On error, the code and message can be retrieved using getErrorCode() and getErrorMessage().

◆ doUpdate() [3/3]

bool sqlrcrud::doUpdate ( jsondom *  j)

Executes the update query as either built by buildQueries() or overridden by setUpdateQuery().

"j" should be a jsondom containing 2 objects:

"criteria" should be a JSON object representing the criteria that will be used to build the where clause, conforming to the format described in the class description.

"data" should be a JSON object consisting of the column/value pairs to be updated.

Note that if getAutoIncrementColumn() returns non-NULL (see getAutoIncrementColumn() for why this may be) then any value specified for that column will be overridden, such that the column will auto-increment. If getAutoIncrementColumn() returns NULL (see getAutoIncrementColumn() for why this may be) then any value specified for the autoincrement column will not be overridden.

Note that if getPrimaryKeyColumn() and getIdSequence() both return non-NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for that column will be overridden, such that the column will be populated from the id sequence. If either of getPrimaryKeyColumn() or getIdSequence() return NULL (see getPrimaryKeyColumn() and getIdSequence() for why this may be) then any value specified for the primary column will not be overridden.

Returns true on success and false on error. On error, the code and message can be retrieved using getErrorCode() and getErrorMessage().

◆ getAffectedRows()

uint64_t sqlrcrud::getAffectedRows ( )

Returns the number of rows affected by the most recent doCreate(), doUpdate(), or doDelete() call, or 0 if the most recent call was to doRead().

◆ getAffectedRowsDictionary()

dictionarycollection<const char *, uint64_t>* sqlrcrud::getAffectedRowsDictionary ( )

Returns an instance of dictionarycollection with a single element, containing the affected rows doCreate(), doUpdate(), or doDelete() was most recently called or an empty dictionary if doRead() was most recently called.

◆ getAffectedRowsList()

listcollection<uint64_t>* sqlrcrud::getAffectedRowsList ( )

Returns an instance of listcollection with a single element, containing the affected rows doCreate(), doUpdate(), or doDelete() was most recently called or an empty list if doRead() was most recently called.

◆ getAffectedRowsScalar()

scalarcollection<uint64_t>* sqlrcrud::getAffectedRowsScalar ( )

Returns an instance of scalarcollection, containing the number of affected rows if doCreate(), doUpdate(), or doDelete() was most recently called or an empty scalar if doRead() was most recently called.

◆ getAffectedRowsTable()

tablecollection<uint64_t>* sqlrcrud::getAffectedRowsTable ( )

Returns an instance of tablecollection with a single field, containing the affected rows doCreate(), doUpdate(), or doDelete() was most recently called or an empty table if doRead() was most recently called.

◆ getAutoIncrementColumn()

const char* sqlrcrud::getAutoIncrementColumn ( )

Returns the autoincrement column as either determined by buildQueries() or overridden by setAutoIncrementColumn().

Note that this may return NULL if:

◆ getCreateQuery()

const char* sqlrcrud::getCreateQuery ( )

Returns the create (insert) query as either built by buildQueries() or overridden by setCreateQuery().

◆ getDeleteQuery()

const char* sqlrcrud::getDeleteQuery ( )

Returns the delete query as either built by buildQueries() or overridden by setDeleteQuery().

◆ getDeleteQueryContainsPartialWhere()

bool sqlrcrud::getDeleteQueryContainsPartialWhere ( )

Returns true if the delete query contains a partial where clause and false otherwise.

◆ getErrorCode()

int64_t sqlrcrud::getErrorCode ( )

Returns whatever error code may have been set by the most recent failed method call.

◆ getErrorMessage()

const char* sqlrcrud::getErrorMessage ( )

Returns whatever error message may have been set by the most recent failed method call.

◆ getFirstColumnList()

listcollection<const char *>* sqlrcrud::getFirstColumnList ( )

Returns an instance of sqlrrowdictionary, representing the first column of each row of the result set if doRead() was most recently called, or an empty sqlrresultsetlist if doCreate(), doUpdate(), or doDelete() was most recently called.

◆ getFirstFieldScalar()

scalarcollection<const char *>* sqlrcrud::getFirstFieldScalar ( )

Returns an instance of sqlrscalar, representing the first field of the first row of the result set if doRead() was most recently called, or an empty sqlrscalar if doCreate(), doUpdate(), or doDelete() was most recently called.

◆ getFirstRowDictionary()

dictionarycollection<const char *, const char *>* sqlrcrud::getFirstRowDictionary ( )

Returns an instance of sqlrrowdictionary, representing the first row of the result set if doRead() was most recently called, or an empty sqlrrowdictionary if doCreate(), doUpdate(), or doDelete() was most recently called.

◆ getFirstRowList()

listcollection<const char *>* sqlrcrud::getFirstRowList ( )

Returns an instance of sqlrrowlist, representing the first row of the result set if doRead() was most recently called, or an empty sqlrrowlist if doCreate(), doUpdate(), or doDelete() was most recently called.

◆ getIdSequence()

const char* sqlrcrud::getIdSequence ( )

Returns the sequence set by setSequence() or setTable().

Note that this may return NULL if:

◆ getPrimaryKeyColumn()

const char* sqlrcrud::getPrimaryKeyColumn ( )

Returns the primary key column as either determined by buildQueries() or overridden by setPrimaryKeyColumn().

Note that this may return NULL if:

◆ getReadQuery()

const char* sqlrcrud::getReadQuery ( )

Returns the read (select) query as either built by buildQueries() or overridden by setReadQuery().

◆ getReadQueryContainsPartialOrderBy()

bool sqlrcrud::getReadQueryContainsPartialOrderBy ( )

Returns true if the read (select) query contains a partial order-by clause and false otherwise.

◆ getReadQueryContainsPartialWhere()

bool sqlrcrud::getReadQueryContainsPartialWhere ( )

Returns true if the read (select) query contains a partial where clause and false otherwise.

◆ getResultSetTable()

tablecollection<const char *>* sqlrcrud::getResultSetTable ( )

Returns an instance of sqlresultsettable, representing the result set if doRead() was most recently called, or an empty sqlrresultsettable if doCreate(), doUpdate(), or doDelete() was most recently called.

◆ getTable()

const char* sqlrcrud::getTable ( )

Returns the table set by setTable().

◆ getUpdateQuery()

const char* sqlrcrud::getUpdateQuery ( )

Returns the update query as either built by buildQueries() or overridden by setUpdateQuery().

◆ getUpdateQueryContainsPartialWhere()

bool sqlrcrud::getUpdateQueryContainsPartialWhere ( )

Returns true if the update query contains a partial where clause and false otherwise.

◆ setAutoIncrementColumn()

void sqlrcrud::setAutoIncrementColumn ( const char *  autoinc)

Indicates which column is the autoincrement column of the table set by setTable().

May be used to override the autoincrement column detected by buildQueries() or to set one if none was detected. Note that subsequent calls to buildQueries() will override the autoincrement column set by this method if one was detected in the table.

Defaults to NULL. Remains NULL if a call to buildQueries() doesn't detect a autoincrement column in the table. If set to NULL then the table will be presumed not to have a primary key.

◆ setCreateQuery()

void sqlrcrud::setCreateQuery ( const char *  createquery)

Sets the create (insert) query template to "createquery".

May be used to override the query built by buidQueries(). Note that subsequent calls to buildQueries() will override the query set by this method.

This query should contain substitution variables and , into which columns and values will be placed.

For example: insert into mytable () values ()

Defaults to NULL and remains NULL until set by buildQuery() or a call to this method.

◆ setDeleteQuery()

void sqlrcrud::setDeleteQuery ( const char *  deletequery)

Sets the delete query template to "deletequery".

May be used to override the query built by buidQueries(). Note that subsequent calls to buildQueries() will override the query set by this method.

This query should contain substitution variable , into which the where clause will be placed.

For example: delete from mytable

Defaults to NULL and remains NULL until set by buildQuery() or a call to this method.

◆ setDeleteQueryContainsPartialWhere()

void sqlrcrud::setDeleteQueryContainsPartialWhere ( bool  containspartial)

Indicates that the delete query contains a partial where clause. This affects the behavior of doDelete() when it builds a where clause from "criteria".

◆ setIdSequence()

void sqlrcrud::setIdSequence ( const char *  idsequence)

Sets the sequence to generate new ids from during create operations (insert queries).

◆ setPrimaryKeyColumn()

void sqlrcrud::setPrimaryKeyColumn ( const char *  primarykey)

Indicates which column is the primary key of the table set by setTable().

May be used to override the primary key column detected by buildQueries() or to set one if none was detected. Note that subsequent calls to buildQueries() will override the primary key set by this method if one was detected in the table.

Defaults to NULL. Remains NULL if a call to buildQueries() doesn't detect a primary key in the table. If set to NULL then the table will be presumed not to have a primary key.

◆ setReadQuery()

void sqlrcrud::setReadQuery ( const char *  readquery)

Sets the read (select) query template to "readquery".

May be used to override the query built by buidQueries(). Note that subsequent calls to buildQueries() will override the query set by this method.

This query should contain substitution variables and , into which where and order-by clauses will be placed.

For example: select * from mytable

Defaults to NULL and remains NULL until set by buildQuery() or a call to this method.

◆ setReadQueryContainsPartialOrderBy()

void sqlrcrud::setReadQueryContainsPartialOrderBy ( bool  containspartial)

Indicates that the read (select) query contains a partial order-by clause. This affects the behavior of doRead() when it builds an order-by clause from the "sort".

◆ setReadQueryContainsPartialWhere()

void sqlrcrud::setReadQueryContainsPartialWhere ( bool  containspartial)

Indicates that the read (select) query contains a partial where clause. This affects the behavior of doRead() when it builds a where clause from "criteria".

◆ setSqlrConnection()

void sqlrcrud::setSqlrConnection ( sqlrconnection con)

Sets the instance of sqlrconnection for this instance to use.

◆ setSqlrCursor()

void sqlrcrud::setSqlrCursor ( sqlrcursor cur)

Sets the instance of sqlrcursor for this instance to use.

◆ setTable()

void sqlrcrud::setTable ( const char *  table)

Sets the table that this instance operates on.

Also sets the sequence to generate new ids from during create operations to "table"_ids, if the id sequence is NULL, either because setIdSequence() hasn't been called, or was called with NULL.

◆ setUpdateQuery()

void sqlrcrud::setUpdateQuery ( const char *  updatequery)

Sets the update query template to "updatequery".

May be used to override the query built by buidQueries(). Note that subsequent calls to buildQueries() will override the query set by this method.

This query should contain substitution variables and , into which set and where clauses will be placed.

For example: update mytable set

Defaults to NULL and remains NULL until set by buildQuery() or a call to this method.

◆ setUpdateQueryContainsPartialWhere()

void sqlrcrud::setUpdateQueryContainsPartialWhere ( bool  containspartial)

Indicates that the update query contains a partial where clause. This affects the behavior of doUpdate() when it builds a where clause from "criteria".