Loading...
Searching...
No Matches
DbDataProvider::DbTableDataProvider Class Reference

Defines a data provider based on a single SQL table. More...

`#include <DbTableDataProvider.qc.dox.h>`

Inherits AbstractDataProvider.

## Public Member Functions

| beginTransaction ()
| Begins a transaction in the datasource underlying the table. More...
| commit ()
| Commits data written to the data provider. More...
| constructor (*hash< auto > options)
| Creates the object from constructor options.
| constructor (AbstractTable table, *Logger logger)
| Creates the object.
int | doSequenceCurrvalKey (string sequence_name, hash< auto > ctx, *reference< bool > missing_input)
| Processes the `sequence_currval` runtime key in mappers as a mapper key handler.
int | doSequenceKey (string sequence_name, hash< auto > ctx, *reference< bool > missing_input)
| Processes the `sequence` runtime key in mappers as a mapper key handler.
AbstractDataProviderBulkOperation | getBulkInserter ()
| Returns a bulk insert operation object for the data provider. More...
AbstractDataProviderBulkOperation | getBulkUpserter ()
| Returns a bulk upsert operation object for the data provider. More...
*AbstractDataProvider | getChildProviders ()
| Returns child providers; return NOTHING if there are no child providers.
*string | getDesc ()
| Returns the data provider description.
hash< DataProviderInfo > | getInfo ()
| Returns data provider info.
*hash< string, hash< MapperRuntimeKeyInfo > > | getMapperRuntimeKeys ()
| Returns custom data mapper runtime keys. More...
string | getName ()
| Returns the data provider name.
bool | requiresTransactionManagement ()
| Returns True if the data provider supports transaction management. More...
| rollback ()
| Rolls back data written to the data provider. More...
private AbstractDataProviderBulkRecordInterface | searchRecordsBulkImpl (int block_size=1000, *hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options. More...
string | upsertRecordImpl (hash< auto > rec, *hash< auto > upsert_options)
| Upserts the given record to the data provider. More...

## Public Attributes

const | ConstructorOptions
| Constructor options.
const | CreateOptions
| Create options; see details below. More...
const | DbUpsertMap
| Maps SqlUtil Upsert Result Codes to DB Provider Upsert Result Codes.
const | MapperKeyInfo
| Mapper runtime key info; see details below. More...
const | ProviderInfo
| Provider info.
const | SearchOptions
| Search options; see details below. More...
const | UpsertOptions
| Upsert options; see details below. More...

## Protected Member Functions

| addFieldImpl (AbstractDataField field, *hash< auto > field_add_options)
| Creates a new field. More...
| alignTable (hash< auto > table_desc)
| Align table with the given description.
*hash< auto > | createRecordImpl (hash< auto > rec, *hash< auto > create_options)
| Writes the given record to the data provider. More...
Mutex | db_lock ()
| lock for "db"
| deleteFieldImpl (string name, *hash< auto > field_delete_options)
| Deletes an existing field. More...
int | deleteRecordsImpl (*hash< auto > where_cond, *hash< auto > search_options)
| Deletes zero or more records. More...
| execDdlSql (list< auto > sqll)
| Executes the given DDL SQL string list.
*hash< string, AbstractDataField > | getRecordTypeImpl (*hash< auto > search_options)
| Returns the description of the record type, if any.
hash< DataProviderInfo > | getStaticInfoImpl ()
| Returns data provider static info.
DbTableRecordIterator | searchRecordsImpl (*hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options. More...
*hash< auto > | searchSingleRecordImpl (hash< auto > where_cond, *hash< auto > search_options)
| Returns a single record matching the search options. More...
| updateFieldImpl (string name, AbstractDataField field, *hash< auto > field_update_options)
| Updates an existing field. More...
int | updateRecordsImpl (hash< auto > set, *hash< auto > where_cond, *hash< auto > search_options)
| Updates zero or more records matching the search options. More...
bool | updateSingleRecordImpl (hash< auto > set, hash< auto > where_cond, *hash< auto > search_options)
| Updates a single record matching the search options. More...

## Protected Attributes

AbstractDatabase | db
| the database object, if required
AbstractTable | table
| the table

## Detailed Description

Defines a data provider based on a single SQL table.

## Member Function Documentation

## addFieldImpl()

DbDataProvider::DbTableDataProvider::addFieldImpl | ( | AbstractDataField | field,
|  | *hash< auto > | field_add_options
| ) |  |

protected

Creates a new field.

Parameters

  field | the field to add
  field_add_options | the options for adding the new field

Returns
  the new child data provider

Since
  DataProvider 2.0

## beginTransaction()

DbDataProvider::DbTableDataProvider::beginTransaction | ( |  | ) |

Begins a transaction in the datasource underlying the table.

See also
  :
  - commit()
  - rollback()

Since
  DbDataProvider 1.0.1

## commit()

DbDataProvider::DbTableDataProvider::commit | ( |  | ) |

Commits data written to the data provider.

See also
  :
  - beginTransaction()
  - rollback()

## createRecordImpl()

*hash< auto > DbDataProvider::DbTableDataProvider::createRecordImpl | ( | hash< auto > | rec,
|  | *hash< auto > | create_options
| ) |  |

protected

Writes the given record to the data provider.

Parameters

  rec | a hash representing a single input record
  create_options | the create options (see CreateOptions) after processing by validateCreateOptions()

Returns
  the data written to the data provider plus any output (returning) variables

Note
  this API will commit the row to the database unless the datasource was already in a transaction before this call

## deleteFieldImpl()

DbDataProvider::DbTableDataProvider::deleteFieldImpl | ( | string | name,
|  | *hash< auto > | field_delete_options
| ) |  |

protected

Deletes an existing field.

Parameters

  name | the name of the field to delete
  field_delete_options | the options for deleting the new field

Since
  DataProvider 2.0

## deleteRecordsImpl()

int DbDataProvider::DbTableDataProvider::deleteRecordsImpl | ( | *hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

protected

Deletes zero or more records.

Parameters

  where_cond | a hash for identifying the record(s) to be deleted
  search_options | the search options (see SearchOptions) after processing by validateSearchOptions()

Returns
  the number of records deleted

Exceptions

  INVALID-OPERATION | the data provider does not support record updating

Note
  this API will commit the row to the database unless the datasource was already in a transaction before this call

## getBulkInserter()

AbstractDataProviderBulkOperation DbDataProvider::DbTableDataProvider::getBulkInserter | ( |  | ) |

Returns a bulk insert operation object for the data provider.

Returns
  a bulk insert operation object for the data provider

## getBulkUpserter()

AbstractDataProviderBulkOperation DbDataProvider::DbTableDataProvider::getBulkUpserter | ( |  | ) |

Returns a bulk upsert operation object for the data provider.

Returns
  a bulk upsert operation object for the data provider

## getMapperRuntimeKeys()

*hash< string, hash< MapperRuntimeKeyInfo > > DbDataProvider::DbTableDataProvider::getMapperRuntimeKeys | ( |  | ) |

Returns custom data mapper runtime keys.

Returns
  custom data mapper runtime keys

## requiresTransactionManagement()

bool DbDataProvider::DbTableDataProvider::requiresTransactionManagement | ( |  | ) |

Returns True if the data provider supports transaction management.

Returns
  True if the data provider supports transaction management, in which case commit() or rollback() must be called to flush or discard data written to the data provider

## rollback()

DbDataProvider::DbTableDataProvider::rollback | ( |  | ) |

Rolls back data written to the data provider.

See also
  :
  - beginTransaction()
  - commit()

## searchRecordsBulkImpl()

private AbstractDataProviderBulkRecordInterface DbDataProvider::DbTableDataProvider::searchRecordsBulkImpl | ( | int | block_size = `1000`,
|  | *hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

inline

Returns an iterator for zero or more records matching the search options.

Parameters

  block_size | the number of records in a read block; must be a positive number
  where_cond | the search criteria; will be processed by processFieldValues()
  search_options | the search options (see SearchOptions); will be processed by validateSearchOptions()

Exceptions

  INVALID-BLOCK-SIZE | the block size must be a positive number
  INVALID-OPERATION | the data provider does not support reading

## searchRecordsImpl()

DbTableRecordIterator DbDataProvider::DbTableDataProvider::searchRecordsImpl | ( | *hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

protected

Returns an iterator for zero or more records matching the search options.

Parameters

  where_cond | the search criteria; will be processed by processFieldValues()
  search_options | the search options (see SearchOptions) after processing by validateSearchOptions()

Note
  this method acquires a transaction lock if one is not already acquired; the iterator returned performs a rollback in the destructor if a new transaction lock was acquired by this call and DbTableRecordIterator::keepTransactionLock() is not called

## searchSingleRecordImpl()

*hash< auto > DbDataProvider::DbTableDataProvider::searchSingleRecordImpl | ( | hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

protected

Returns a single record matching the search options.

Parameters

  where_cond | the search criteria; will be processed by processFieldValues()
  search_options | the search options (see SearchOptions) after processing by validateSearchOptions()

Exceptions

  MULTIPLE-RECORDS-ERROR | multiple records found

## updateFieldImpl()

DbDataProvider::DbTableDataProvider::updateFieldImpl | ( | string | name,
|  | AbstractDataField | field,
|  | *hash< auto > | field_update_options
| ) |  |

protected

Updates an existing field.

Parameters

  name | the name of the current field to update
  field | the new definition of the field
  field_update_options | the options for adding the new field

Since
  DataProvider 2.0

## updateRecordsImpl()

int DbDataProvider::DbTableDataProvider::updateRecordsImpl | ( | hash< auto > | set,
|  | *hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

protected

Updates zero or more records matching the search options.

Parameters

  set | the hash of field data to set
  where_cond | a hash for identifying the record(s) to be updated
  search_options | the search options (see SearchOptions) after processing by validateSearchOptions()

Returns
  the number of records updated

Note
  this API will commit the row to the database unless the datasource was already in a transaction before this call

## updateSingleRecordImpl()

bool DbDataProvider::DbTableDataProvider::updateSingleRecordImpl | ( | hash< auto > | set,
|  | hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

protected

Updates a single record matching the search options.

Parameters

  set | the hash of field data to set
  where_cond | a hash for identifying the record to be update
  search_options | the search options (see SearchOptions) after processing by validateSearchOptions()

Exceptions

  UPDATE-SINGLE-RECORD-ERROR | if the update would update more than one record

Note
  this API will commit the row to the database unless the datasource was already in a transaction before this call

## upsertRecordImpl()

string DbDataProvider::DbTableDataProvider::upsertRecordImpl | ( | hash< auto > | rec,
|  | *hash< auto > | upsert_options
| ) |  |

Upserts the given record to the data provider.

Parameters

  rec | a hash representing a single input record
  upsert_options | the upsert options (see UpsertOptions) after processing by validateUpsertOptions()

Returns
  see DB Provider Upsert Result Codes for possible values

Note
  this API will commit the row to the database unless the datasource was already in a transaction before this call

## Member Data Documentation

## CreateOptions

const DbDataProvider::DbTableDataProvider::CreateOptions

Initial value:
= {
"returning": <DataProviderOptionInfo>{
"type": AbstractDataProviderType::get(AbstractDataProviderType::anyType),
"desc": "a string (giving the output name) or a hash describing the return parameters for an insert; "
"a hash will have the following keys: 'key': (required) the column name to return, and 'type' "
"(optional) the data type for the output placeholder buffer (ex: 'number')",
},
}

Create options; see details below.

The DbTableDataProvider class supports the following create option:

- `returning:` a list having elements of one of the two following types:
  - string: column names to return the value inserted
  - hash: a hash having the following keys:
    - `"key"`: (required) the column name to return
    - `"type"`: (optional) the data type for the output placeholder buffer (ex: Type::Number)

## MapperKeyInfo

const DbDataProvider::DbTableDataProvider::MapperKeyInfo

Initial value:
= Mapper::MapperKeyInfo + {
"sequence": <MapperRuntimeKeyInfo>{
"desc": "names the DB sequence that will be used to populate the field",
"value_type": "string",
"unique_roles": "*",
"returns_type": "int",
},
"sequence_currval": <MapperRuntimeKeyInfo>{
"desc": "names the DB sequence that will be used to populate the field; the current value of the "
"sequence is used; will not increment the sequence",
"value_type": "string",
"unique_roles": "*",
"returns_type": "int",
},
}

Mapper runtime key info; see details below.

The DbTableDataProvider class supports the following create option:

- `sequence:` names the DB sequence that will be used to populate the field
- `sequence_currval:` names the DB sequence that will be used to populate the field; the current value of the sequence is used; will not increment the sequence

## SearchOptions

const DbDataProvider::DbTableDataProvider::SearchOptions

Initial value:
= {
"columns": <DataProviderOptionInfo>{
"type": AbstractDataProviderType::get(AbstractDataProviderType::anyType),
"desc": "column argument for the select expression",
},
"limit": <DataProviderOptionInfo>{
"type": AbstractDataProviderType::get(IntType),
"desc": "the maximum number of records to return",
},
"offset": <DataProviderOptionInfo>{
"type": AbstractDataProviderType::get(IntType),
"desc": "the offset number in records to return",
},
"groupby": <DataProviderOptionInfo>{
"type": new QoreListDataType(new Type("softlist<auto>")),
"desc": "group by argument for the select expression",
},
"having": <DataProviderOptionInfo>{
"type": AbstractDataProviderType::get(AutoHashType),
"desc": "having argument for the select expression",
},
"orderby": <DataProviderOptionInfo>{
"type": new QoreListDataType(new Type("softlist<string>")),
"desc": "order by argument for the select expression",
},
"forupdate": <DataProviderOptionInfo>{
"type": AbstractDataProviderType::get(SoftBoolType),
"desc": "uses FOR UPDATE with the query to lock records selected",
},
}

Search options; see details below.

The DbTableDataProvider class supports the following search options:

- `columns:` column argument for the select expression; see SqlUtil select option columns for more information on this argument
- `limit:` the maximum number of records to return; see SqlUtil select option limit for more information on this argument
- `offset:` the offset number in records to return; see SqlUtil select option offset for more information on this argument
- `groupby:` group by argument for the select expression; see SqlUtil select option groupby for more information on this argument
- `having:` having argument for the select expression; see SqlUtil select option having for more information on this argument
- `orderby:` order by argument for the select expression; see SqlUtil select option orderby for more information on this argument
- `forupdate:` uses FOR UPDATE with the query to lock records selected; see SqlUtil select option forupdate for more information on this argument

## UpsertOptions

const DbDataProvider::DbTableDataProvider::UpsertOptions

Initial value:
= {
"upsert_strategy": <DataProviderOptionInfo>{
"type": AbstractDataProviderType::get(StringType),
"desc": "providers the upsert strategy; 'UpsertInsertFirst': try to insert first, if it fails, try "
"updating; 'UpsertUpdateFirst': try to update first, if it fails, try inserting; "
"'UpsertSelectFirst': try to select first, if it fails, insert, if it succeeds, update if "
"necessary; 'UpsertInsertOnly': only insert, never update, 'UpsertUpdateOnly': only update, "
"never insert; 'UpsertAuto' (the default) use the most efficient upsert for the underlying DB",
},
"omit_update": <DataProviderOptionInfo>{
"type": AbstractDataProviderType::get(new Type("softlist<string>")),
"desc": "allows for an asymmetrical upsert where a set of column values is inserted, but a smaller "
"set is updated in case the unique key values are present in the target table; the value of this "
"option should be set to the columns to omit in the update clause",
},
}

Upsert options; see details below.

The DbTableDataProvider class supports the following upsert options:

- `upsert_strategy:` an upsert strategu code; see: SqlUtil upsert strategy codes for more info
- `omit_update:` allows for an asymmetrical upsert where a set of column values is inserted, but a smaller set is updated in case the unique key values are present in the target table; the value of this option should be set to the columns to omit in the update clause