Qore DbDataProvider Module Reference  2.0
DbTableDataProvider.qc.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
3 
26 namespace DbDataProvider {
28 class DbTableDataProvider : public AbstractDataProvider {
29 
30 public:
32  const ProviderInfo = <DataProviderInfo>{
33  "type": "DbTableDataProvider",
34  "supports_read": True,
35  "supports_create": True,
36  "supports_update": True,
37  "supports_upsert": True,
38  "supports_delete": True,
39  "supports_native_search": True,
40  "supports_bulk_read": True,
41  "supports_bulk_create": True,
42  "supports_bulk_upsert": True,
43  "supports_children": False,
44  "supports_add_field": True,
45  "supports_update_field": True,
46  "supports_delete_field": True,
47  "supports_search_expressions": True,
48  "constructor_options": ConstructorOptions,
49  "search_options": SearchOptions,
50  "create_options": CreateOptions,
51  "upsert_options": UpsertOptions,
52  "expressions": (AbstractDataProvider::GenericExpressions - DP_SEARCH_OP_REGEX) + {
53  OP_LIKE: <DataProviderExpressionInfo>{
54  "type": DET_Operator,
55  "name": "like",
56  "label": OP_LIKE,
57  "symbol": "like",
58  "desc": "The SQL 'like' operator",
59  "args": (DataProviderSignatureStringType, DataProviderSignatureStringValueType),
60  "return_type": AbstractDataProviderTypeMap."bool",
61  },
62  },
63  "transaction_management": True,
64  "has_record": True,
65  "mapper_keys": MapperKeyInfo,
66  };
67 
69 
74  const MapperKeyInfo = Mapper::MapperKeyInfo + {
75  "sequence": <MapperRuntimeKeyInfo>{
76  "desc": "names the DB sequence that will be used to populate the field",
77  "value_type": "string",
78  "unique_roles": "*",
79  "returns_type": "int",
80  },
81  "sequence_currval": <MapperRuntimeKeyInfo>{
82  "desc": "names the DB sequence that will be used to populate the field; the current value of the "
83  "sequence is used; will not increment the sequence",
84  "value_type": "string",
85  "unique_roles": "*",
86  "returns_type": "int",
87  },
88  };
89 
92  "datasource": <DataProviderOptionInfo>{
93  "type": (
94  AbstractDataProviderType::get(StringType),
95  AbstractDataProviderType::get(new Type("AbstractDatasource")),
96  ),
97  "desc": "the datasource connection string or an abstract datasource object; in case a connection "
98  "string is given, then the \"table\" option also needs to be given as a string",
99  },
100  "table": <DataProviderOptionInfo>{
101  "type": (
102  AbstractDataProviderType::get(StringType),
103  AbstractDataProviderType::get(new Type("AbstractTable")),
104  ),
105  "required": True,
106  "desc": "the table name or table object; if a table string is provided, then the \"datasource\" "
107  "option must also be provided",
108  },
109  };
110 
112 
121  const CreateOptions = {
122  "returning": <DataProviderOptionInfo>{
123  "type": AbstractDataProviderType::get(AbstractDataProviderType::anyType),
124  "desc": "a string (giving the output name) or a hash describing the return parameters for an insert; "
125  "a hash will have the following keys: 'key': (required) the column name to return, and 'type' "
126  "(optional) the data type for the output placeholder buffer (ex: 'number')",
127  },
128  };
129 
131 
138  const UpsertOptions = {
139  "upsert_strategy": <DataProviderOptionInfo>{
140  "type": AbstractDataProviderType::get(StringType),
141  "desc": "providers the upsert strategy; 'UpsertInsertFirst': try to insert first, if it fails, try "
142  "updating; 'UpsertUpdateFirst': try to update first, if it fails, try inserting; "
143  "'UpsertSelectFirst': try to select first, if it fails, insert, if it succeeds, update if "
144  "necessary; 'UpsertInsertOnly': only insert, never update, 'UpsertUpdateOnly': only update, "
145  "never insert; 'UpsertAuto' (the default) use the most efficient upsert for the underlying DB",
146  },
147  "omit_update": <DataProviderOptionInfo>{
148  "type": AbstractDataProviderType::get(new Type("softlist<string>")),
149  "desc": "allows for an asymmetrical upsert where a set of column values is inserted, but a smaller "
150  "set is updated in case the unique key values are present in the target table; the value of this "
151  "option should be set to the columns to omit in the update clause",
152  },
153  };
154 
156 
179  const SearchOptions = {
180  "columns": <DataProviderOptionInfo>{
181  "type": AbstractDataProviderType::get(AbstractDataProviderType::anyType),
182  "desc": "column argument for the select expression",
183  },
184  "limit": <DataProviderOptionInfo>{
185  "type": AbstractDataProviderType::get(IntType),
186  "desc": "the maximum number of records to return",
187  },
188  "offset": <DataProviderOptionInfo>{
189  "type": AbstractDataProviderType::get(IntType),
190  "desc": "the offset number in records to return",
191  },
192  "groupby": <DataProviderOptionInfo>{
193  "type": new QoreListDataType(new Type("softlist<auto>")),
194  "desc": "group by argument for the select expression",
195  },
196  "having": <DataProviderOptionInfo>{
197  "type": AbstractDataProviderType::get(AutoHashType),
198  "desc": "having argument for the select expression",
199  },
200  "orderby": <DataProviderOptionInfo>{
201  "type": new QoreListDataType(new Type("softlist<string>")),
202  "desc": "order by argument for the select expression",
203  },
204  "forupdate": <DataProviderOptionInfo>{
205  "type": AbstractDataProviderType::get(SoftBoolType),
206  "desc": "uses FOR UPDATE with the query to lock records selected",
207  },
208  };
209 
211  const DbUpsertMap = {
212  AbstractTable::UR_Inserted: UpsertResultInserted,
213  AbstractTable::UR_Verified: UpsertResultVerified,
214  AbstractTable::UR_Updated: UpsertResultUpdated,
215  AbstractTable::UR_Unchanged: UpsertResultUnchanged,
216  AbstractTable::UR_Deleted: UpsertResultDeleted,
217  };
218 
219 protected:
221  AbstractTable table;
222 
224  AbstractDatabase db;
225 
227  Mutex db_lock();
228 
229 public:
230 
232  constructor(AbstractTable table, *Logger logger);
233 
234 
236  constructor(*hash<auto> options);
237 
238 
240  string getName();
241 
242 
244  *string getDesc();
245 
246 
248  hash<DataProviderInfo> getInfo();
249 
250 
252  *AbstractDataProvider getChildProviders();
253 
254 
256 
260 
261 
263 
271 
272 
274 
280 
281 
283 
289 
290 
292 
294  AbstractDataProviderBulkOperation getBulkInserter();
295 
296 
298 
300  AbstractDataProviderBulkOperation getBulkUpserter();
301 
302 
304 
306  *hash<string, hash<MapperRuntimeKeyInfo>> getMapperRuntimeKeys();
307 
308 
310  int doSequenceKey(string sequence_name);
311 
312 
314  int doSequenceCurrvalKey(string sequence_name);
315 
316 
318 protected:
319  *hash<string, AbstractDataField> getRecordTypeImpl(*hash<auto> search_options);
320 public:
321 
322 
324 
332 protected:
333  *hash<auto> createRecordImpl(hash<auto> rec, *hash<auto> create_options);
334 public:
335 
336 
338 
346  string upsertRecordImpl(hash<auto> rec, *hash<auto> upsert_options);
347 
348 
350 
355 protected:
356  *hash<auto> searchSingleRecordImpl(hash<auto> where_cond, *hash<auto> search_options);
357 public:
358 
359 
361 
368  private AbstractDataProviderBulkRecordInterface searchRecordsBulkImpl(int block_size = 1000,
369  *hash<auto> where_cond, *hash<auto> search_options) {
370  return new DbTableBulkRecordInterface(block_size, table, where_cond, search_options);
371  }
372 
374 
382 protected:
383  DbTableRecordIterator searchRecordsImpl(*hash<auto> where_cond, *hash<auto> search_options);
384 public:
385 
386 
388 
397 protected:
398  bool updateSingleRecordImpl(hash<auto> set, hash<auto> where_cond, *hash<auto> search_options);
399 public:
400 
401 
403 
412 protected:
413  int updateRecordsImpl(hash<auto> set, *hash<auto> where_cond, *hash<auto> search_options);
414 public:
415 
416 
418 
429 protected:
430  int deleteRecordsImpl(*hash<auto> where_cond, *hash<auto> search_options);
431 public:
432 
433 
435 protected:
436  hash<DataProviderInfo> getStaticInfoImpl();
437 public:
438 
439 
441 
449 protected:
450  addFieldImpl(AbstractDataField field, *hash<auto> field_add_options);
451 public:
452 
453 
455 
461 protected:
462  updateFieldImpl(string name, AbstractDataField field, *hash<auto> field_update_options);
463 public:
464 
465 
467 
472 protected:
473  deleteFieldImpl(string name, *hash<auto> field_delete_options);
474 public:
475 
476 
478 protected:
479  alignTable(hash<auto> table_desc);
480 public:
481 
482 
484 protected:
485  execDdlSql(list<auto> sqll);
486 public:
487 
488 };
489 };
Defines the record iterator class for Table-based iterators.
Definition: DbTableBulkRecordInterface.qc.dox.h:34
Defines a data provider based on a single SQL table.
Definition: DbTableDataProvider.qc.dox.h:28
execDdlSql(list< auto > sqll)
Executes the given DDL SQL string list.
addFieldImpl(AbstractDataField field, *hash< auto > field_add_options)
Creates a new field.
*hash< string, AbstractDataField > getRecordTypeImpl(*hash< auto > search_options)
Returns the description of the record type, if any.
*string getDesc()
Returns the data provider description.
string getName()
Returns the data provider name.
*AbstractDataProvider getChildProviders()
Returns child providers; return NOTHING if there are no child providers.
beginTransaction()
Begins a transaction in the datasource underlying the table.
const MapperKeyInfo
Mapper runtime key info; see details below.
Definition: DbTableDataProvider.qc.dox.h:74
const DbUpsertMap
Maps SqlUtil Upsert Result Codes to DB Provider Upsert Result Codes.
Definition: DbTableDataProvider.qc.dox.h:211
commit()
Commits data written to the data provider.
const ProviderInfo
Provider info.
Definition: DbTableDataProvider.qc.dox.h:32
string upsertRecordImpl(hash< auto > rec, *hash< auto > upsert_options)
Upserts the given record to the data provider.
int doSequenceCurrvalKey(string sequence_name)
Processes the sequence_currval runtime key in mappers.
const ConstructorOptions
Constructor options.
Definition: DbTableDataProvider.qc.dox.h:91
bool updateSingleRecordImpl(hash< auto > set, hash< auto > where_cond, *hash< auto > search_options)
Updates a single record matching the search options.
const SearchOptions
Search options; see details below.
Definition: DbTableDataProvider.qc.dox.h:179
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.
alignTable(hash< auto > table_desc)
Align table with the given description.
const CreateOptions
Create options; see details below.
Definition: DbTableDataProvider.qc.dox.h:121
int doSequenceKey(string sequence_name)
Processes the sequence runtime key in mappers.
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.
Definition: DbTableDataProvider.qc.dox.h:368
*hash< auto > searchSingleRecordImpl(hash< auto > where_cond, *hash< auto > search_options)
Returns a single record matching the search options.
AbstractDatabase db
the database object, if required
Definition: DbTableDataProvider.qc.dox.h:224
hash< DataProviderInfo > getInfo()
Returns data provider info.
AbstractDataProviderBulkOperation getBulkUpserter()
Returns a bulk upsert operation object for the data provider.
int deleteRecordsImpl(*hash< auto > where_cond, *hash< auto > search_options)
Deletes zero or more records.
AbstractTable table
the table
Definition: DbTableDataProvider.qc.dox.h:221
updateFieldImpl(string name, AbstractDataField field, *hash< auto > field_update_options)
Updates an existing field.
constructor(*hash< auto > options)
Creates the object from constructor options.
*hash< auto > createRecordImpl(hash< auto > rec, *hash< auto > create_options)
Writes the given record to the data provider.
constructor(AbstractTable table, *Logger logger)
Creates the object.
const UpsertOptions
Upsert options; see details below.
Definition: DbTableDataProvider.qc.dox.h:138
rollback()
Rolls back data written to the data provider.
deleteFieldImpl(string name, *hash< auto > field_delete_options)
Deletes an existing field.
bool requiresTransactionManagement()
Returns True if the data provider supports transaction management.
*hash< string, hash< MapperRuntimeKeyInfo > > getMapperRuntimeKeys()
Returns custom data mapper runtime keys.
int updateRecordsImpl(hash< auto > set, *hash< auto > where_cond, *hash< auto > search_options)
Updates zero or more records matching the search options.
AbstractDataProviderBulkOperation getBulkInserter()
Returns a bulk insert operation object for the data provider.
Defines the record iterator class for Table-based iterators.
Definition: DbTableRecordIterator.qc.dox.h:28
const True
const False
Qore AbstractDbRecordIterator class definition.
Definition: AbstractDbRecordIterator.qc.dox.h:26