1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
|
<!DOCTYPE html>
<html lang="en" data-bs-theme="light">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="shortcut icon" href="../img/favicon.ico">
<title>Utilities - SOCI (4.1.2)</title>
<link href="../css/bootstrap.min.css" rel="stylesheet">
<link href="../css/fontawesome.min.css" rel="stylesheet">
<link href="../css/brands.min.css" rel="stylesheet">
<link href="../css/solid.min.css" rel="stylesheet">
<link href="../css/v4-font-face.min.css" rel="stylesheet">
<link href="../css/base.css" rel="stylesheet">
<link id="hljs-light" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" >
<link id="hljs-dark" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github-dark.min.css" disabled>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>
</head>
<body>
<div class="navbar fixed-top navbar-expand-lg navbar-dark bg-primary">
<div class="container">
<a class="navbar-brand" href="..">SOCI (4.1.2)</a>
<!-- Expander button -->
<button type="button" class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#navbar-collapse" aria-controls="navbar-collapse" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<!-- Expanded navigation -->
<div id="navbar-collapse" class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li class="nav-item">
<a href=".." class="nav-link">Home</a>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Overview</a>
<ul class="dropdown-menu">
<li>
<a href="../quickstart/" class="dropdown-item">Getting Started</a>
</li>
<li>
<a href="../installation/" class="dropdown-item">Installation</a>
</li>
<li>
<a href="../structure/" class="dropdown-item">Library Structure</a>
</li>
<li>
<a href="../license/" class="dropdown-item">License</a>
</li>
<li>
<a href="../faq/" class="dropdown-item">FAQ</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">User Guide</a>
<ul class="dropdown-menu">
<li>
<a href="../connections/" class="dropdown-item">Connections</a>
</li>
<li>
<a href="../queries/" class="dropdown-item">Queries</a>
</li>
<li>
<a href="../binding/" class="dropdown-item">Data Binding</a>
</li>
<li>
<a href="../indicators/" class="dropdown-item">Data Indicators</a>
</li>
<li>
<a href="../types/" class="dropdown-item">Data Types</a>
</li>
<li>
<a href="../lobs/" class="dropdown-item">LOBs</a>
</li>
<li>
<a href="../statements/" class="dropdown-item">Statements</a>
</li>
<li>
<a href="../transactions/" class="dropdown-item">Transactions</a>
</li>
<li>
<a href="../procedures/" class="dropdown-item">Procedures</a>
</li>
<li>
<a href="../errors/" class="dropdown-item">Errors</a>
</li>
<li>
<a href="../logging/" class="dropdown-item">Logging</a>
</li>
<li>
<a href="../interfaces/" class="dropdown-item">Interfaces</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Backends</a>
<ul class="dropdown-menu">
<li>
<a href="../backends/" class="dropdown-item">Features</a>
</li>
<li>
<a href="../backends/db2/" class="dropdown-item">DB2</a>
</li>
<li>
<a href="../backends/firebird/" class="dropdown-item">Firebird</a>
</li>
<li>
<a href="../backends/mysql/" class="dropdown-item">MySQL</a>
</li>
<li>
<a href="../backends/odbc/" class="dropdown-item">ODBC</a>
</li>
<li>
<a href="../backends/oracle/" class="dropdown-item">Oracle</a>
</li>
<li>
<a href="../backends/postgresql/" class="dropdown-item">PostgreSQL</a>
</li>
<li>
<a href="../backends/sqlite3/" class="dropdown-item">SQLite3</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle active" aria-current="page" role="button" data-bs-toggle="dropdown" aria-expanded="false">Miscellaneous</a>
<ul class="dropdown-menu">
<li>
<a href="../beyond/" class="dropdown-item">Beyond SQL</a>
</li>
<li>
<a href="../multithreading/" class="dropdown-item">Multi-threading</a>
</li>
<li>
<a href="../boost/" class="dropdown-item">Boost</a>
</li>
<li>
<a href="./" class="dropdown-item active" aria-current="page">Utilities</a>
</li>
<li>
<a href="../vagrant/" class="dropdown-item">Vagrant</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">API</a>
<ul class="dropdown-menu">
<li>
<a href="../api/client/" class="dropdown-item">Client API</a>
</li>
<li>
<a href="../api/backend/" class="dropdown-item">Backend API</a>
</li>
<li class="dropdown-submenu">
<a href="#" class="dropdown-item">Ada</a>
<ul class="dropdown-menu">
<li>
<a href="../languages/ada/" class="dropdown-item">Ada Bindings</a>
</li>
<li>
<a href="../languages/ada/concepts/" class="dropdown-item">Ada Concepts</a>
</li>
<li>
<a href="../languages/ada/idioms/" class="dropdown-item">Ada Idioms</a>
</li>
<li>
<a href="../languages/ada/reference/" class="dropdown-item">Ada API Reference</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav ms-md-auto">
<li class="nav-item">
<a href="#" class="nav-link" data-bs-toggle="modal" data-bs-target="#mkdocs_search_modal">
<i class="fa fa-search"></i> Search
</a>
</li>
<li class="nav-item">
<a rel="prev" href="../boost/" class="nav-link">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
<li class="nav-item">
<a rel="next" href="../vagrant/" class="nav-link">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
<li class="nav-item">
<a href="https://github.com/SOCI/soci/edit/master/docs/utilities.md" class="nav-link"><i class="fa-brands fa-github"></i> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-3"><div class="navbar-expand-md bs-sidebar hidden-print affix" role="complementary">
<div class="navbar-header">
<button type="button" class="navbar-toggler collapsed" data-bs-toggle="collapse" data-bs-target="#toc-collapse" title="Table of Contents">
<span class="fa fa-angle-down"></span>
</button>
</div>
<div id="toc-collapse" class="navbar-collapse collapse card bg-body-tertiary">
<ul class="nav flex-column">
<li class="nav-item" data-bs-level="1"><a href="#utilities" class="nav-link">Utilities</a>
<ul class="nav flex-column">
<li class="nav-item" data-bs-level="2"><a href="#ddl" class="nav-link">DDL</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#dml" class="nav-link">DML</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#database-metadata" class="nav-link">Database Metadata</a>
<ul class="nav flex-column">
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div></div>
<div class="col-md-9" role="main">
<h1 id="utilities">Utilities</h1>
<p>SOCI provides a portable abstraction for selection of database queries.</p>
<h2 id="ddl">DDL</h2>
<p>SOCI supports some basic methods to construct portable DDL queries. That is, instead of writing explicit SQL statement for creating or modifying tables, it is possible to use dedicated SOCI functions, which prepare appropriate DDL statements behind the scenes, thus enabling the user application to create basic database structures in a way that is portable across different database servers. Note that the actual support for these functions depends on the actual backend implementation.</p>
<p>It is possible to create a new table in a single statement:</p>
<pre><code class="language-cpp">sql.create_table("t1").column("i", soci::db_int32).column("j", soci::db_int32);
</code></pre>
<p>Above, table "t1" will be created with two columns ("i", "j") of type integer.</p>
<p>It is also possible to build similar statements piece by piece, which is useful if the table structure is computed dynamically:</p>
<pre><code class="language-cpp">{
soci::ddl_type ddl = sql.create_table("t2");
ddl.column("i", soci::db_int32);
ddl.column("j", soci::db_int32);
ddl.column("k", soci::db_int32)("not null");
ddl.primary_key("t2_pk", "j");
}
</code></pre>
<p>The actual statement is executed at the end of above block, when the ddl object goes out of scope. The "not null" constraint was added to the definition of column "k" explicitly and in fact any piece of SQL can be inserted this way - with the obvious caveat of having limited portability (the "not null" piece seems to be universaly portable).</p>
<p>Columns can be added to and dropped from already existing tables as well:</p>
<pre><code class="language-cpp">sql.add_column("t1", "k", soci::db_int32);
// or with constraint:
//sql.add_column("t1", "k", soci::db_int32)("not null");
sql.drop_column("t1", "i");
</code></pre>
<p>If needed, precision and scale can be defined with additional integer arguments to functions that create columns:</p>
<pre><code class="language-cpp">sql.add_column("t1", "s", soci::db_string, precision);
sql.add_column("t1", "d", soci::db_double, precision, scale);
</code></pre>
<p>Tables with foreign keys to each other can be also created:</p>
<pre><code class="language-cpp">{
soci::ddl_type ddl = sql.create_table("t3");
ddl.column("x", soci::db_int32);
ddl.column("y", soci::db_int32);
ddl.foreign_key("t3_fk", "x", "t2", "j");
}
</code></pre>
<p>Tables can be dropped, too:</p>
<pre><code class="language-cpp">sql.drop_table("t1");
sql.drop_table("t3");
sql.drop_table("t2");
</code></pre>
<p>Note that due to the differences in the set of types that are actually supported on the target database server, the type mappings, as well as precision and scales, might be different, even in the way that makes them impossible to portably recover with metadata queries.</p>
<p>In the category of portability utilities, the following functions are also available:</p>
<pre><code class="language-cpp">sql.empty_blob()
</code></pre>
<p>the above call returns the string containing expression that represents an empty BLOB value in the given target backend. This expression can be used as part of a bigger SQL statement, for example:</p>
<pre><code class="language-cpp">sql << "insert into my_table (x) values (" + sql.empty_blob() + ")";
</code></pre>
<p>and:</p>
<pre><code class="language-cpp">sql.nvl()
</code></pre>
<p>the above call returns the string containing the name of the SQL function that implements the NVL or COALESCE operation in the given target backend, for example:</p>
<pre><code class="language-cpp">sql << "select name, " + sql.nvl() + "(phone, \'UNKNOWN\') from phone_book";
</code></pre>
<p>Note: <code>empty_blob</code> and <code>nvl</code> are implemented in Oracle, PostgreSQL and SQLite3 backends; for other backends their behaviour is as for PostgreSQL.</p>
<h2 id="dml">DML</h2>
<p>Only two related functions are currently available in this category:
<code>get_dummy_from_clause()</code> can be used to construct select statements that don't
operate on any table in a portable way, as while some databases allow simply
omitting the from clause in this case, others -- e.g. Oracle -- still require
providing some syntactically valid from clause even if it is not used. To use
this function, simply append the result of this function to the statement:</p>
<pre><code class="language-cpp">double databasePi;
session << ("select 4*atan(1)" + session.get_dummy_from_clause()),
into(databasePi);
</code></pre>
<p>If just the name of the dummy table is needed, and not the full clause, you can
use <code>get_dummy_from_table()</code> to obtain it.</p>
<p>Notice that both functions require the session to be connected as their result
depends on the database it is connected to.</p>
<h2 id="database-metadata">Database Metadata</h2>
<p>It is possible to portably query the database server to obtain basic metadata information.</p>
<p>In order to get the list of table names in the current schema:</p>
<pre><code class="language-cpp">std::vector<std::string> names(100);
sql.get_table_names(), into(names);
</code></pre>
<p>alternatively:</p>
<pre><code class="language-cpp">std::string name;
soci::statement st = (sql.prepare_table_names(), into(name));
st.execute();
while (st.fetch())
{
// ...
}
</code></pre>
<p>Similarly, to get the description of all columns in a given table:</p>
<pre><code class="language-cpp">soci::column_info ci;
soci::statement st = (sql.prepare_column_descriptions(table_name), into(ci));
st.execute();
while (st.fetch())
{
// ci fields describe each column in turn
}
</code></pre>
<p>The <code>table_name</code> can contain a schema part in dot-notation. If a schema is part of the
<code>table_name</code>, then that specific table will be queried for its columns. If the
<code>table_name</code> only holds a table name then the current schema will be used.</p>
<p>Examples:</p>
<pre><code class="language-cpp">soci::column_info ci;
soci::statement st1 = (sql.prepare_column_descriptions("table_without_schema"), into(ci));
soci::statement st2 = (sql.prepare_column_descriptions("schema.table"), into(ci));
</code></pre></div>
</div>
</div>
<footer class="col-md-12">
<hr>
<p>Copyright © 2017-2025 <a href="https://soci.sourceforge.net/people.html">SOCI Team</a>.</p>
<p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</p>
</footer>
<script src="../js/bootstrap.bundle.min.js"></script>
<script>
var base_url = "..",
shortcuts = {"help": 191, "next": 78, "previous": 80, "search": 83};
</script>
<script src="../js/base.js"></script>
<script src="../search/main.js"></script>
<div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="searchModalLabel" aria-hidden="true">
<div class="modal-dialog modal-lg">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="searchModalLabel">Search</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<p>From here you can search these documents. Enter your search terms below.</p>
<form>
<div class="form-group">
<input type="search" class="form-control" placeholder="Search..." id="mkdocs-search-query" title="Type search term here">
</div>
</form>
<div id="mkdocs-search-results" data-no-results-text="No results found"></div>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div><div class="modal" id="mkdocs_keyboard_modal" tabindex="-1" role="dialog" aria-labelledby="keyboardModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<table class="table">
<thead>
<tr>
<th style="width: 20%;">Keys</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td class="help shortcut"><kbd>?</kbd></td>
<td>Open this help</td>
</tr>
<tr>
<td class="next shortcut"><kbd>n</kbd></td>
<td>Next page</td>
</tr>
<tr>
<td class="prev shortcut"><kbd>p</kbd></td>
<td>Previous page</td>
</tr>
<tr>
<td class="search shortcut"><kbd>s</kbd></td>
<td>Search</td>
</tr>
</tbody>
</table>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div>
</body>
</html>
|
