Qore DbDataProvider Module Reference  1.0
DbTableDataProvider.qc.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
3 
25 // minimum required Qore version
26 // assume local scope for variables, do not use "$" signs
27 // require type definitions everywhere
29 // enable all warnings
30 
32 namespace DbDataProvider {
34 class DbTableDataProvider : public AbstractDataProvider {
35 
36 public:
38  const ProviderInfo = <DataProviderInfo>{
39  "type": "DbTableDataProvider",
40  "supports_read": True,
41  "supports_create": True,
42  "supports_update": True,
43  "supports_upsert": True,
44  "supports_delete": True,
45  "supports_native_search": True,
46  "supports_bulk_read": True,
47  "supports_bulk_create": True,
48  "supports_bulk_upsert": True,
49  "supports_children": False,
50  "constructor_options": ConstructorOptions,
51  "search_options": SearchOptions,
52  "create_options": CreateOptions,
53  "upsert_options": UpsertOptions,
54  "transaction_management": True,
55  "has_record": True,
56  "mapper_keys": MapperKeyInfo,
57  };
58 
60  const MapperKeyInfo = Mapper::MapperKeyInfo + {
61  "sequence": <MapperRuntimeKeyInfo>{
62  "desc": "names the DB sequence that will be used to populate the field",
63  "value_type": "string",
64  "unique_roles": "*",
65  "returns_type": "int",
66  },
67  "sequence_currval": <MapperRuntimeKeyInfo>{
68  "desc": "names the DB sequence that will be used to populate the field; the current value of the "
69  "sequence is used; will not increment the sequence",
70  "value_type": "string",
71  "unique_roles": "*",
72  "returns_type": "int",
73  },
74  };
75 
78  "datasource": <DataProviderOptionInfo>{
79  "type": (
80  AbstractDataProviderType::get(StringType),
81  AbstractDataProviderType::get(new Type("AbstractDatasource")),
82  ),
83  "desc": "the datasource connection string or an abstract datasource object; in case a connection "
84  "string is given, then the \"table\" option also needs to be given as a string",
85  },
86  "table": <DataProviderOptionInfo>{
87  "type": (
88  AbstractDataProviderType::get(StringType),
89  AbstractDataProviderType::get(new Type("AbstractTable")),
90  ),
91  "required": True,
92  "desc": "the table name or table object; if a table string is provided, then the \"datasource\" "
93  "option must also be provided",
94  },
95  };
96 
98  const CreateOptions = {
99  "returning": <DataProviderOptionInfo>{
100  "type": AbstractDataProviderType::get(AbstractDataProviderType::anyType),
101  "desc": "a string (giving the output name) or a hash describing the return parameters for an insert; "
102  "a hash will have the following keys: 'key': (required) the column name to return, and 'type' "
103  "(optional) the data type for the output placeholder buffer (ex: 'number')",
104  },
105  };
106 
108  const UpsertOptions = {
109  "upsert_strategy": <DataProviderOptionInfo>{
110  "type": AbstractDataProviderType::get(StringType),
111  "desc": "providers the upsert strategy; 'UpsertInsertFirst': try to insert first, if it fails, try "
112  "updating; 'UpsertUpdateFirst': try to update first, if it fails, try inserting; "
113  "'UpsertSelectFirst': try to select first, if it fails, insert, if it succeeds, update if "
114  "necessary; 'UpsertInsertOnly': only insert, never update, 'UpsertUpdateOnly': only update, "
115  "never insert; 'UpsertAuto' (the default) use the most efficient upsert for the underlying DB",
116  },
117  "omit_update": <DataProviderOptionInfo>{
118  "type": AbstractDataProviderType::get(new Type("softlist<string>")),
119  "desc": "allows for an asymmetrical upsert where a set of column values is inserted, but a smaller "
120  "set is updated in case the unique key values are present in the target table; the value of this "
121  "option should be set to the columns to omit in the update clause",
122  },
123  };
124 
126  const SearchOptions = {
127  "columns": <DataProviderOptionInfo>{
128  "type": AbstractDataProviderType::get(AbstractDataProviderType::anyType),
129  "desc": "column argument for the select expression",
130  },
131  "limit": <DataProviderOptionInfo>{
132  "type": AbstractDataProviderType::get(IntType),
133  "desc": "the maximum number of records to return",
134  },
135  "offset": <DataProviderOptionInfo>{
136  "type": AbstractDataProviderType::get(IntType),
137  "desc": "the offset number in records to return",
138  },
139  "groupby": <DataProviderOptionInfo>{
140  "type": new QoreListDataType(new Type("softlist<auto>")),
141  "desc": "group by argument for the select expression",
142  },
143  "having": <DataProviderOptionInfo>{
144  "type": AbstractDataProviderType::get(AutoHashType),
145  "desc": "having argument for the select expression",
146  },
147  "orderby": <DataProviderOptionInfo>{
148  "type": new QoreListDataType(new Type("softlist<string>")),
149  "desc": "order by argument for the select expression",
150  },
151  "forupdate": <DataProviderOptionInfo>{
152  "type": AbstractDataProviderType::get(SoftBoolType),
153  "desc": "uses FOR UPDATE with the query to lock records selected",
154  },
155  };
156 
158  const DbUpsertMap = {
159  AbstractTable::UR_Inserted: UpsertResultInserted,
160  AbstractTable::UR_Verified: UpsertResultVerified,
161  AbstractTable::UR_Updated: UpsertResultUpdated,
162  AbstractTable::UR_Unchanged: UpsertResultUnchanged,
163  AbstractTable::UR_Deleted: UpsertResultDeleted,
164  };
165 
166 protected:
168  AbstractTable table;
169 
171  AbstractDatabase db;
172 
174  Mutex db_lock();
175 
176 public:
177 
179  constructor(AbstractTable table);
180 
181 
183  constructor(*hash<auto> options);
184 
185 
187  string getName();
188 
189 
191  *AbstractDataProvider getChildProviders();
192 
193 
195 
199 
200 
202 
205 
206 
208 
211 
212 
214 
216  AbstractDataProviderBulkOperation getBulkInserter();
217 
218 
220 
222  AbstractDataProviderBulkOperation getBulkUpserter();
223 
224 
226 
228  *hash<string, hash<MapperRuntimeKeyInfo>> getMapperRuntimeKeys();
229 
230 
232 protected:
233  *hash<string, AbstractDataField> getRecordTypeImpl(*hash<auto> search_options);
234 public:
235 
236 
238 
246 protected:
247  *hash<auto> createRecordImpl(hash<auto> rec, *hash<auto> create_options);
248 public:
249 
250 
252 
260  string upsertRecordImpl(hash<auto> rec, *hash<auto> upsert_options);
261 
262 
264 
268 protected:
269  *hash<auto> searchSingleRecordImpl(hash<auto> where_cond, *hash<auto> search_options);
270 public:
271 
272 
274 
281 protected:
282  AbstractDataProviderBulkRecordInterface searchRecordsBulkImpl(int block_size = 1000, *hash<auto> where_cond, *hash<auto> search_options);
283 public:
284 
285 
287 
294 protected:
295  DbTableRecordIterator searchRecordsImpl(*hash<auto> where_cond, *hash<auto> search_options);
296 public:
297 
298 
300 
309 protected:
310  bool updateSingleRecordImpl(hash<auto> set, hash<auto> where_cond, *hash<auto> search_options);
311 public:
312 
313 
315 
324 protected:
325  int updateRecordsImpl(hash<auto> set, *hash<auto> where_cond, *hash<auto> search_options);
326 public:
327 
328 
330 
341 protected:
342  int deleteRecordsImpl(*hash<auto> where_cond, *hash<auto> search_options);
343 public:
344 
345 
347 protected:
348  hash<DataProviderInfo> getStaticInfoImpl();
349 public:
350 
351 
353  int doSequenceKey(string sequence_name);
354 
355 
357  int doSequenceCurrvalKey(string sequence_name);
358 
359 };
360 };
DbDataProvider::DbTableDataProvider::rollback
rollback()
Rolls back data written to the data provider.
DbDataProvider::DbTableDataProvider::getName
string getName()
Returns the data provider name.
DbDataProvider::DbTableDataProvider::doSequenceKey
int doSequenceKey(string sequence_name)
Processes the sequence runtime key in mappers.
DbDataProvider::DbTableDataProvider::getBulkInserter
AbstractDataProviderBulkOperation getBulkInserter()
Returns a bulk insert operation object for the data provider.
DbDataProvider::DbTableDataProvider::SearchOptions
const SearchOptions
Search options.
Definition: DbTableDataProvider.qc.dox.h:126
DbDataProvider::DbTableDataProvider::db
AbstractDatabase db
the database object, if required
Definition: DbTableDataProvider.qc.dox.h:171
True
const True
DbDataProvider::DbTableDataProvider::updateRecordsImpl
int updateRecordsImpl(hash< auto > set, *hash< auto > where_cond, *hash< auto > search_options)
Updates zero or more records matching the search options.
DbDataProvider::DbTableDataProvider::MapperKeyInfo
const MapperKeyInfo
Mapper runtime key info.
Definition: DbTableDataProvider.qc.dox.h:60
DbDataProvider::DbTableDataProvider::requiresTransactionManagement
bool requiresTransactionManagement()
Returns True if the data provider supports transaction management.
DbDataProvider::DbTableDataProvider::CreateOptions
const CreateOptions
Create options.
Definition: DbTableDataProvider.qc.dox.h:98
DbDataProvider::DbTableDataProvider::getChildProviders
*AbstractDataProvider getChildProviders()
Returns child providers; return NOTHING if there are no child providers.
DbDataProvider::DbTableRecordIterator
Defines the record iterator class for Table-based iterators.
Definition: DbTableRecordIterator.qc.dox.h:34
DbDataProvider::DbTableDataProvider::deleteRecordsImpl
int deleteRecordsImpl(*hash< auto > where_cond, *hash< auto > search_options)
Deletes zero or more records.
DbDataProvider::DbTableDataProvider::searchRecordsImpl
DbTableRecordIterator searchRecordsImpl(*hash< auto > where_cond, *hash< auto > search_options)
Returns an iterator for zero or more records matching the search options.
DbDataProvider::DbTableDataProvider::upsertRecordImpl
string upsertRecordImpl(hash< auto > rec, *hash< auto > upsert_options)
Upserts the given record to the data provider.
DbDataProvider::DbTableDataProvider::DbUpsertMap
const DbUpsertMap
Maps SqlUtil Upsert Result Codes to DB Provider Upsert Result Codes.
Definition: DbTableDataProvider.qc.dox.h:158
DbDataProvider::DbTableDataProvider::searchSingleRecordImpl
*hash< auto > searchSingleRecordImpl(hash< auto > where_cond, *hash< auto > search_options)
Returns a single record matching the search options.
DbDataProvider::DbTableDataProvider::UpsertOptions
const UpsertOptions
Upsert options.
Definition: DbTableDataProvider.qc.dox.h:108
DbDataProvider::DbTableDataProvider::updateSingleRecordImpl
bool updateSingleRecordImpl(hash< auto > set, hash< auto > where_cond, *hash< auto > search_options)
Updates a single record matching the search options.
DbDataProvider::DbTableDataProvider::doSequenceCurrvalKey
int doSequenceCurrvalKey(string sequence_name)
Processes the sequence_currval runtime key in mappers.
DbDataProvider::DbTableDataProvider::ConstructorOptions
const ConstructorOptions
Constructor options.
Definition: DbTableDataProvider.qc.dox.h:77
False
const False
DbDataProvider::DbTableDataProvider::getBulkUpserter
AbstractDataProviderBulkOperation getBulkUpserter()
Returns a bulk upsert operation object for the data provider.
DbDataProvider::DbTableDataProvider::constructor
constructor(*hash< auto > options)
Creates the object from constructor options.
DbDataProvider::DbTableDataProvider::getStaticInfoImpl
hash< DataProviderInfo > getStaticInfoImpl()
Returns data provider static info.
DbDataProvider::DbTableDataProvider
Defines a data provider based on a single SQL table.
Definition: DbTableDataProvider.qc.dox.h:34
DbDataProvider::DbTableDataProvider::ProviderInfo
const ProviderInfo
Provider info.
Definition: DbTableDataProvider.qc.dox.h:38
DbDataProvider::DbTableDataProvider::createRecordImpl
*hash< auto > createRecordImpl(hash< auto > rec, *hash< auto > create_options)
Writes the given record to the data provider.
DbDataProvider::DbTableDataProvider::getMapperRuntimeKeys
*hash< string, hash< MapperRuntimeKeyInfo > > getMapperRuntimeKeys()
Returns custom data mapper runtime keys.
DbDataProvider
Qore AbstractDbRecordIterator class definition.
Definition: AbstractDbRecordIterator.qc.dox.h:32
DbDataProvider::DbTableDataProvider::searchRecordsBulkImpl
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.
DbDataProvider::DbTableDataProvider::getRecordTypeImpl
*hash< string, AbstractDataField > getRecordTypeImpl(*hash< auto > search_options)
Returns the description of the record type, if any.
DbDataProvider::DbTableDataProvider::table
AbstractTable table
the table
Definition: DbTableDataProvider.qc.dox.h:168
DbDataProvider::DbTableDataProvider::commit
commit()
Commits data written to the data provider.
DbDataProvider::DbTableDataProvider::constructor
constructor(AbstractTable table)
Creates the object.
DbDataProvider::DbTableDataProvider::db_lock
Mutex db_lock()
lock for "db"