~ubuntu-branches/ubuntu/wily/sqlite3/wily

onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">

112

113

</form>

114

</div>

115

</table>

116

</div></div></div></div>

117

</td></tr></table>

118

119

120

121

122

123

<h1>1.0 Compilation Options For SQLite</h1>

124

125

126

For most purposes, SQLite can be built just fine using the default

127

compilation options. However, if required, the compile-time options

128

documented below can be used to

129

<a href="#omitfeatures">omit SQLite features</a> (resulting in

130

a <a href="footprint.html#relfootprint">smaller compiled library size</a>) or to change the

131

<a href="#defaults">default values</a> of some parameters.

132

133

134

135

Every effort has been made to ensure that the various combinations

136

of compilation options work harmoniously and produce a working library.

137

Nevertheless, it is strongly recommended that the SQLite test-suite

138

be executed to check for errors before using an SQLite library built

139

with non-standard compilation options.

140

141

142

<h2>1.1 Options To Set Default Parameter Values</h2>

143

144

145

SQLITE_DEFAULT_AUTOVACUUM=<0 or 1 or 2><blockquote>

146

This macro determines if SQLite creates databases with the

147

<a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a> flag set by default to OFF (0), FULL (1), or

148

INCREMENTAL (2). The default value is 0 meaning that databases

149

are created with auto-vacuum turned off.

150

In any case the compile-time default may be overridden by the

151

<a href="pragma.html#pragma_auto_vacuum">PRAGMA auto_vacuum</a> command.

152

</blockquote><a name="default_cache_size"></a>

153

SQLITE_DEFAULT_CACHE_SIZE=<pages><blockquote>

154

This macro sets the default size of the page-cache for each attached

155

database, in pages. This can be overridden by the

156

<a href="pragma.html#pragma_cache_size">PRAGMA cache_size</a> command. The default value is 2000.

157

</blockquote><a name="default_file_format"></a>

158

SQLITE_DEFAULT_FILE_FORMAT=<1 or 4><blockquote>

159

The default <a href="fileformat2.html#schemaformat">schema format number</a> used by SQLite when creating

160

new database files is set by this macro. The schema formats are all

161

very similar. The difference between formats 1 and 4 is that format

162

4 understands <a href="lang_createindex.html#descidx">descending indices</a> and has a tighter encoding for

163

boolean values.

164

165

All versions of SQLite since 3.3.0 (2006-01-10)

166

can read and write any schema format

167

between 1 and 4. But older versions of SQLite might not be able to

168

read formats greater than 1. So that older versions of SQLite will

169

be able to read and write database files created by newer versions

170

of SQLite, the default schema format was set to 1 for SQLite versions

171

through 3.7.9 (2011-11-01). Beginning with version 3.7.10, the default

172

schema format is 4.

173

174

The schema format number for a new database can be set at runtime using

175

the <a href="pragma.html#pragma_legacy_file_format">PRAGMA legacy_file_format</a> command.

176

</blockquote><a name="default_file_permissions"></a>

177

SQLITE_DEFAULT_FILE_PERMISSIONS=N<blockquote>

178

The default numeric file permissions for newly created database files

179

under unix. If not specified, the default is 0644 which means that

180

the files is globally readable but only writable by the creator.

181

</blockquote><a name="default_foreign_keys"></a>

182

SQLITE_DEFAULT_FOREIGN_KEYS=<0 or 1><blockquote>

183

This macro determines whether enforcement of

184

<a href="foreignkeys.html">foreign key constraints</a> is enabled or disabled by default for

185

new database connections. Each database connection can always turn

186

enforcement of foreign key constraints on and off and run-time using

187

the <a href="pragma.html#pragma_foreign_keys">foreign_keys pragma</a>. Enforcement of foreign key constraints

188

is normally off by default, but if this compile-time parameter is

189

set to 1, enforcement of foreign key constraints will be on by default.

190

</blockquote><a name="default_journal_size_limit"></a>

191

SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT=<bytes><blockquote>

192

This option sets the size limit on <a href="lockingv3.html#rollback">rollback journal</a> files in

193

<a href="pragma.html#pragma_journal_mode">persistent journal mode</a> and

194

<a href="pragma.html#pragma_locking_mode">exclusive locking mode</a> and on the size of the

195

write-ahead log file in <a href="wal.html">WAL mode</a>. When this

196

compile-time option is omitted there is no upper bound on the

197

size of the rollback journals or write-ahead logs.

198

The journal file size limit

199

can be changed at run-time using the <a href="pragma.html#pragma_journal_size_limit">journal_size_limit pragma</a>.

200

</blockquote><a name="default_locking_mode"></a>

201

SQLITE_DEFAULT_LOCKING_MODE=<1 or 0><blockquote>

202

If set to 1, then the default <a href="pragma.html#pragma_locking_mode">locking_mode</a> is set to EXCLUSIVE.

203

If omitted or set to 0 then the default <a href="pragma.html#pragma_locking_mode">locking_mode</a> is NORMAL.

204

</blockquote><a name="default_memstatus"></a>

205

SQLITE_DEFAULT_MEMSTATUS=<1 or 0><blockquote>

206

This macro is used to determine whether or not the features enabled and

207

disabled using the SQLITE_CONFIG_MEMSTATUS argument to <a href="c3ref/config.html">sqlite3_config()</a>

208

are available by default. The default value is 1 (<a href="c3ref/c_config_getmalloc.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a>

209

related features enabled).

210

</blockquote><a name="default_page_size"></a>

211

SQLITE_DEFAULT_PAGE_SIZE=<bytes><blockquote>

212

This macro is used to set the default page-size used when a

213

database is created. The value assigned must be a power of 2. The

214

default value is 1024. The compile-time default may be overridden at

215

runtime by the <a href="pragma.html#pragma_page_size">PRAGMA page_size</a> command.

216

</blockquote><a name="default_temp_cache_size"></a>

217

SQLITE_DEFAULT_TEMP_CACHE_SIZE=<pages><blockquote>

218

This macro sets the default size of the page-cache for temporary files

219

created by SQLite to store intermediate results, in pages. It does

220

not affect the page-cache for the temp database, where tables created

221

using <a href="lang_createtable.html">CREATE TEMP TABLE</a> are stored. The default value

222

is 500.

223

</blockquote><a name="default_wal_autocheckpoint"></a>

224

SQLITE_DEFAULT_WAL_AUTOCHECKPOINT=<pages><blockquote>

225

This macro sets the default page count for the <a href="wal.html">WAL</a>

226

<a href="wal.html#ckpt">automatic checkpointing</a> feature. If unspecified,

227

the default page count is 1000.

228

</blockquote><a name="max_schema_retry"></a>

229

SQLITE_MAX_SCHEMA_RETRY=N<blockquote>

230

Whenever the database schema changes, prepared statements are automatically

231

reprepared to accommodate the new schema. There is a race condition here

232

in that if one thread is constantly changing the schema, another thread

233

might spin on reparses and repreparations of a prepared statement and

234

never get any real work done. This parameter prevents an infinite loop

235

by forcing the spinning thread to give up after a fixed number of attempts

236

at recompiling the prepared statement. The default setting is 5 which is

237

more than adequate for most applications. But in some obscure cases, it

238

is useful to raise this parameter to 100 or more to prevent spurious

239

<a href="c3ref/c_abort.html">SQLITE_SCHEMA</a> errors when running <a href="c3ref/step.html">sqlite3_step()</a>.

240

</blockquote><a name="powersafe_overwrite"></a>

241

SQLITE_POWERSAFE_OVERWRITE=<0 or 1><blockquote>

242

This option changes the default assumption about <a href="psow.html">powersafe overwrite</a>

243

for the underlying filesystems for the unix and windows <a href="vfs.html">VFSes</a>.

244

Setting SQLITE_POWERSAFE_OVERWRITE to 1 causes SQLite to assume that

245

application-level writes cannot changes bytes outside the range of

246

bytes written even if the write occurs just before a power loss.

247

With SQLITE_POWERSAFE_OVERWRITE set to 0, SQLite assumes that other

248

bytes in the same sector with a written byte might be changed or

249

damaged by a power loss.

250

</blockquote><a name="yystackdepth"></a>

251

YYSTACKDEPTH=<max_depth><blockquote>

252

This macro sets the maximum depth of the LALR(1) stack used by

253

the SQL parser within SQLite. The default value is 100. A typical

254

application will use less than about 20 levels of the stack.

255

Developers whose applications contain SQL statements that

256

need more than 100 LALR(1) stack entries should seriously

257

consider refactoring their SQL as it is likely to be well beyond

258

the ability of any human to comprehend.

259

</blockquote>

260

261

<h2>1.2 Options To Set Size Limits</h2>

262

263

There are compile-time options that will set upper bounds

264

on the sizes of various structures in SQLite. The compile-time

265

options normally set a hard upper bound that can be changed

266

at run-time on individual <a href="c3ref/sqlite3.html">database connections</a> using the

267

<a href="c3ref/limit.html">sqlite3_limit()</a> interface.

268

269

The compile-time options for setting upper bounds are

270

<a href="limits.html">documented separately</a>. The following is a list of

271

the available settings:

272

273

<ul>

274

<li> <a href="limits.html#max_attached">SQLITE_MAX_ATTACHED</a> </li>

275

<li> <a href="limits.html#max_column">SQLITE_MAX_COLUMN</a> </li>

276

<li> <a href="limits.html#max_compound_select">SQLITE_MAX_COMPOUND_SELECT</a> </li>

277

<li> <a href="limits.html#max_expr_depth">SQLITE_MAX_EXPR_DEPTH</a> </li>

278

<li> <a href="limits.html#max_function_arg">SQLITE_MAX_FUNCTION_ARG</a> </li>

279

<li> <a href="limits.html#max_length">SQLITE_MAX_LENGTH</a> </li>

280

<li> <a href="limits.html#max_like_pattern_length">SQLITE_MAX_LIKE_PATTERN_LENGTH</a> </li>

281

<li> <a href="limits.html#max_page_count">SQLITE_MAX_PAGE_COUNT</a> </li>

282

<li> <a href="limits.html#max_sql_length">SQLITE_MAX_SQL_LENGTH</a> </li>

283

<li> <a href="limits.html#max_variable_number">SQLITE_MAX_VARIABLE_NUMBER</a> </li>

284

</ul>

285

286

287

<h2>1.3 Options To Control Operating Characteristics</h2>

288

289

290

SQLITE_4_BYTE_ALIGNED_MALLOC<blockquote>

291

On most systems, the malloc() system call returns a buffer that is

292

aligned to an 8-byte boundary. But on some systems (ex: windows) malloc()

293

returns 4-byte aligned pointer. This compile-time option must be used

294

on systems that return 4-byte aligned pointers from malloc().

295

</blockquote><a name="case_sensitive_like"></a>

296

SQLITE_CASE_SENSITIVE_LIKE<blockquote>

297

If this option is present, then the built-in <a href="lang_expr.html#like">LIKE</a> operator will be

298

case sensitive. This same effect can be achieved at run-time using

299

the <a href="pragma.html#pragma_case_sensitive_like">case_sensitive_like pragma</a>.

300

</blockquote><a name="direct_overflow_read"></a>

301

SQLITE_DIRECT_OVERFLOW_READ<blockquote>

302

When this option is present, content contained in

303

<a href="fileformat2.html#ovflpgs">overflow pages</a> of the database file is read directly from disk,

304

bypassing the <a href="c3ref/pcache_methods2.html">page cache</a>, during read transactions. In applications

305

that do a lot of reads of large BLOBs, this option might improve read

306

performance.

307

</blockquote><a name="have_isnan"></a>

308

SQLITE_HAVE_ISNAN<blockquote>

309

If this option is present, then SQLite will use the isnan() function from

310

the system math library. Without this option (the default behavior)

311

SQLite uses its own internal implementation of isnan(). SQLite uses

312

its own internal isnan() implementation by default because of past

313

problems with system isnan() functions.

314

</blockquote><a name="os_other"></a>

315

SQLITE_OS_OTHER=<0 or 1><blockquote>

316

The option causes SQLite to omit its built-in operating system interfaces

317

for Unix, Windows, and OS/2. The resulting library will have no default

318

<a href="c3ref/vfs.html">operating system interface</a>. Applications must use

319

<a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> to register an appropriate interface before

320

using SQLite. Applications must also supply implementations for the

321

<a href="c3ref/initialize.html">sqlite3_os_init()</a> and <a href="c3ref/initialize.html">sqlite3_os_end()</a> interfaces. The usual practice

322

is for the supplied <a href="c3ref/initialize.html">sqlite3_os_init()</a> to invoke <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>.

323

SQLite will automatically invoke <a href="c3ref/initialize.html">sqlite3_os_init()</a> when it initializes.

324

325

This option is typically used when building SQLite for an embedded

326

platform with a custom operating system.

327

</blockquote><a name="secure_delete"></a>

328

SQLITE_SECURE_DELETE<blockquote>

329

This compile-time option changes the default setting of the

330

<a href="pragma.html#pragma_secure_delete">secure_delete pragma</a>. When this option is not used, secure_delete defaults

331

to off. When this option is present, secure_delete defaults to on.

332

333

The secure_delete setting causes deleted content to be overwritten with

334

zeros. There is a small performance penalty for this since additional I/O

335

must occur. On the other hand, secure_delete can prevent sensitive

336

information from lingering in unused parts of the database file after it

337

has allegedly been deleted. See the documentation on the

338

<a href="pragma.html#pragma_secure_delete">secure_delete pragma</a> for additional information.

339

</blockquote><a name="threadsafe"></a>

340

SQLITE_THREADSAFE=<0 or 1 or 2><blockquote>

341

This option controls whether or not code is included in SQLite to

342

enable it to operate safely in a multithreaded environment. The

343

default is SQLITE_THREADSAFE=1 which is safe for use in a multithreaded

344

environment. When compiled with SQLITE_THREADSAFE=0 all mutexing code

345

is omitted and it is unsafe to use SQLite in a multithreaded program.

346

When compiled with SQLITE_THREADSAFE=2, SQLite can be used in a multithreaded

347

program so long as no two threads attempt to use the same

348

<a href="c3ref/sqlite3.html">database connection</a> (or any <a href="c3ref/stmt.html">prepared statements</a> derived from

349

that database connection) at the same time.

350

351

To put it another way, SQLITE_THREADSAFE=1 sets the default

352

<a href="threadsafe.html">threading mode</a> to Serialized. SQLITE_THREADSAFE=2 sets the default

353

<a href="threadsafe.html">threading mode</a> to Multi-threaded. And SQLITE_THREADSAFE=0 sets the

354

<a href="threadsafe.html">threading mode</a> to Single-threaded.

355

356

The value of SQLITE_THREADSAFE can be determined at run-time

357

using the <a href="c3ref/threadsafe.html">sqlite3_threadsafe()</a> interface.

358

359

When SQLite has been compiled with SQLITE_THREADSAFE=1 or

360

SQLITE_THREADSAFE=2 then the <a href="threadsafe.html">threading mode</a>

361

can be altered at run-time using the <a href="c3ref/config.html">sqlite3_config()</a> interface together

362

with one of these verbs:

363

364

<ul>

365

<li><a href="c3ref/c_config_getmalloc.html#sqliteconfigsinglethread">SQLITE_CONFIG_SINGLETHREAD</a>

366

<li><a href="c3ref/c_config_getmalloc.html#sqliteconfigmultithread">SQLITE_CONFIG_MULTITHREAD</a>

367

<li><a href="c3ref/c_config_getmalloc.html#sqliteconfigserialized">SQLITE_CONFIG_SERIALIZED</a>

368

</ul>

369

370

The <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOMUTEX</a> and

371

<a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_FULLMUTEX</a> flags to <a href="c3ref/open.html">sqlite3_open_v2()</a> can also be used

372

to adjust the <a href="threadsafe.html">threading mode</a> of individual <a href="c3ref/sqlite3.html">database connections</a>

373

at run-time.

374

375

Note that when SQLite is compiled with SQLITE_THREADSAFE=0, the code

376

to make SQLite threadsafe is omitted from the build. When this occurs,

377

it is impossible to change the <a href="threadsafe.html">threading mode</a> at start-time or run-time.

378

379

See the <a href="threadsafe.html">threading mode</a> documentation for additional information

380

on aspects of using SQLite in a multithreaded environment.

381

</blockquote><a name="temp_store"></a>

382

SQLITE_TEMP_STORE=<0 through 3><blockquote>

383

This option controls whether temporary files are stored on disk or

384

in memory. The meanings for various settings of this compile-time

385

option are as follows:

386

387

388

<tr><th>SQLITE_TEMP_STORE</th><th>Meaning</th></tr>

389

<tr><td align="center">0</td><td>Always use temporary files</td></tr>

390

<tr><td align="center">1</td><td>Use files by default but allow the

391

<a href="pragma.html#pragma_temp_store">PRAGMA temp_store</a> command to override</td></tr>

392

<tr><td align="center">2</td><td>Use memory by default but allow the

393

<a href="pragma.html#pragma_temp_store">PRAGMA temp_store</a> command to override</td></tr>

394

<tr><td align="center">3</td><td>Always use memory</td></tr>

395

</table>

396

397

The default setting is 1.

398

Additional information can be found in <a href="tempfiles.html#tempstore">tempfiles.html</a>.

399

</blockquote><a name="use_uri"></a>

400

SQLITE_USE_URI<blockquote>

401

This option causes the <a href="uri.html">URI filename</a> process logic to be enabled by

402

default.

403

</blockquote>

404

405

406

<h2>1.4 Options To Enable Features Normally Turned Off</h2>

407

408

409

SQLITE_ENABLE_8_3_NAMES=<1 or 2><blockquote>

410

If this C-preprocessor macro is defined, then extra code is

411

included that allows SQLite to function on a filesystem that

412

only support 8+3 filenames. If the value of this macro is 1,

413

then the default behavior is to continue to use long filenames and

414

to only use 8+3 filenames if the

415

database connection is opened using <a href="uri.html">URI filenames</a> with

416

the "<tt>8_3_names=1</tt>" query parameter. If the value of

417

this macro is 2, then the use of 8+3 filenames becomes the default

418

but may be disabled on using the <tt>8_3_names=0</tt> query parameter.

419

See

420

</blockquote><a name="enable_atomic_write"></a>

421

SQLITE_ENABLE_ATOMIC_WRITE<blockquote>

422

If this C-preprocessor macro is defined and if the

423

xDeviceCharacteristics method of <a href="c3ref/io_methods.html">sqlite3_io_methods</a> object for

424

a database file reports (via one of the <a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a> bits)

425

that the filesystem supports atomic writes and if a transaction

426

involves a change to only a single page of the database file,

427

then the transaction commits with just a single write request of

428

a single page of the database and no rollback journal is created

429

or written. On filesystems that support atomic writes, this

430

optimization can result in significant speed improvements for

431

small updates. However, few filesystems support this capability

432

and the code paths that check for this capability slow down write

433

performance on systems that lack atomic write capability, so this

434

feature is disabled by default.

435

</blockquote><a name="enable_column_metadata"></a>

436

SQLITE_ENABLE_COLUMN_METADATA<blockquote>

437

When this C-preprocessor macro is defined, SQLite includes some

438

additional APIs that provide convenient access to meta-data about

439

tables and queries. The APIs that are enabled by this option are:

440

441

<ul>

442

<li> <a href="c3ref/column_database_name.html">sqlite3_column_database_name()</a> </li>

443

<li> <a href="c3ref/column_database_name.html">sqlite3_column_database_name16()</a> </li>

444

<li> <a href="c3ref/column_database_name.html">sqlite3_column_table_name()</a> </li>

445

<li> <a href="c3ref/column_database_name.html">sqlite3_column_table_name16()</a> </li>

446

<li> <a href="c3ref/column_database_name.html">sqlite3_column_origin_name()</a> </li>

447

<li> <a href="c3ref/column_database_name.html">sqlite3_column_origin_name16()</a> </li>

448

<li> <a href="c3ref/table_column_metadata.html">sqlite3_table_column_metadata()</a> </li>

449

</ul>

450

</blockquote><a name="enable_fts3"></a>

451

SQLITE_ENABLE_FTS3<blockquote>

452

When this option is defined in the <a href="amalgamation.html">amalgamation</a>, version 3

453

of the full-text search engine is added to the build automatically.

454

</blockquote><a name="enable_fts3_parenthesis"></a>

455

SQLITE_ENABLE_FTS3_PARENTHESIS<blockquote>

456

This option modifies the query pattern parser in FTS3 such that it

457

supports operators AND and NOT (in addition to the usual OR and NEAR)

458

and also allows query expressions to contain nested parenthesis.

459

</blockquote><a name="enable_fts4"></a>

460

SQLITE_ENABLE_FTS4<blockquote>

461

When this option is defined in the <a href="amalgamation.html">amalgamation</a>, versions 3 and 4

462

of the full-text search engine is added to the build automatically.

463

</blockquote><a name="enable_icu"></a>

464

SQLITE_ENABLE_ICU<blockquote>

465

This option causes the

466

<a href="http://www.icu-project.org/">International Components for Unicode</a>

467

or "ICU" extension to SQLite to be added to the build.

468

</blockquote><a name="enable_iotrace"></a>

469

SQLITE_ENABLE_IOTRACE<blockquote>

470

When both the SQLite core and the <a href="sqlite.html">Command Line Interface</a> (CLI) are both

471

compiled with this option, then the CLI provides an extra command

472

named ".iotrace" that provides a low-level log of I/O activity.

473

This option is experimental and may be discontinued in a future release.

474

</blockquote><a name="enable_locking_style"></a>

475

SQLITE_ENABLE_LOCKING_STYLE<blockquote>

476

This option enables additional logic in the OS interface layer for

477

Mac OS X. The additional logic attempts to determine the type of the

478

underlying filesystem and choose and alternative locking strategy

479

that works correctly for that filesystem type. Five locking strategies

480

are available:

481

482

<ul>

483

<li> POSIX locking style. This is the default locking style and the

484

style used by other (non Mac OS X) Unixes. Locks are obtained and

485

released using the fcntl() system call.

486

487

<li> AFP locking style. This locking style is used for network file

488

systems that use the AFP (Apple Filing Protocol) protocol. Locks

489

are obtained by calling the library function _AFPFSSetLock().

490

491

<li> Flock locking style. This is used for file-systems that do not

492

support POSIX locking style. Locks are obtained and released using

493

the flock() system call.

494

495

<li> Dot-file locking style. This locking style is used when neither

496

flock nor POSIX locking styles are supported by the file system.

497

Database locks are obtained by creating and entry in the file-system

498

at a well-known location relative to the database file (a "dot-file")

499

and relinquished by deleting the same file.

500

501

<li> No locking style. If none of the above can be supported, this

502

locking style is used. No database locking mechanism is used. When

503

this system is used it is not safe for a single database to be

504

accessed by multiple clients.

505

</ul>

506

507

Additionally, five extra <a href="vfs.html">VFS</a> implementations are provided as well as the

508

default. By specifying one of the extra VFS implementations

509

when calling <a href="c3ref/open.html">sqlite3_open_v2()</a>, an application may bypass the file-system

510

detection logic and explicitly select one of the above locking styles. The

511

five extra <a href="vfs.html">VFS</a> implementations are called "unix-posix", "unix-afp",

512

"unix-flock", "unix-dotfile" and "unix-none".

513

</blockquote><a name="enable_memory_management"></a>

514

SQLITE_ENABLE_MEMORY_MANAGEMENT<blockquote>

515

This option adds extra logic to SQLite that allows it to release unused

516

memory upon request. This option must be enabled in order for the

517

<a href="c3ref/release_memory.html">sqlite3_release_memory()</a> interface to work. If this compile-time

518

option is not used, the <a href="c3ref/release_memory.html">sqlite3_release_memory()</a> interface is a

519

no-op.

520

</blockquote><a name="enable_memsys3"></a>

521

SQLITE_ENABLE_MEMSYS3<blockquote>

522

This option includes code in SQLite that implements an alternative

523

memory allocator. This alternative memory allocator is only engaged

524

when the <a href="c3ref/c_config_getmalloc.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a> option to <a href="c3ref/config.html">sqlite3_config()</a> is used to

525

supply a large chunk of memory from which all memory allocations are

526

taken.

527

The MEMSYS3 memory allocator uses a hybrid allocation algorithm

528

patterned after dlmalloc(). Only one of SQLITE_ENABLE_MEMSYS3 and

529

SQLITE_ENABLE_MEMSYS5 may be enabled at once.

530

</blockquote><a name="enable_memsys5"></a>

531

SQLITE_ENABLE_MEMSYS5<blockquote>

532

This option includes code in SQLite that implements an alternative

533

memory allocator. This alternative memory allocator is only engaged

534

when the <a href="c3ref/c_config_getmalloc.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a> option to <a href="c3ref/config.html">sqlite3_config()</a> is used to

535

supply a large chunk of memory from which all memory allocations are

536

taken.

537

The MEMSYS5 module rounds all allocations up to the next power

538

of two and uses a first-fit, buddy-allocator algorithm

539

that provides strong guarantees against fragmentation and breakdown

540

subject to certain operating constraints.

541

</blockquote><a name="enable_rtree"></a>

542

SQLITE_ENABLE_RTREE<blockquote>

543

This option causes SQLite to include support for the

544

<a href="rtree.html">R*Tree index extension</a>.

545

</blockquote><a name="rtree_int_only"></a>

546

SQLITE_RTREE_INT_ONLY<blockquote>

547

If this option is used together with <a href="compile.html#enable_rtree">SQLITE_ENABLE_RTREE</a> then the

548

<a href="rtree.html">R*Tree extension</a> will only store 32-bit signed integer

549

coordinates and all internal computations will be done using integers

550

instead of floating point numbers.

551

</blockquote><a name="enable_stat2"></a>

552

SQLITE_ENABLE_STAT2<blockquote>

553

This option used to cause the <a href="lang_analyze.html">ANALYZE</a> command to collect

554

index histogram data in the sqlite_stat2 table. But that

555

functionality was superceded by <a href="compile.html#enable_stat3">SQLITE_ENABLE_STAT3</a> as of

556

SQLite version 3.7.9. The SQLITE_ENABLE_STAT2 compile-time option

557

is now a no-op.

558

</blockquote><a name="enable_stat3"></a>

559

SQLITE_ENABLE_STAT3<blockquote>

560

This option adds additional logic to the <a href="lang_analyze.html">ANALYZE</a> command and to

561

the <a href="optoverview.html">query planner</a> that can help SQLite to chose a better query plan

562

under certain situations. The <a href="lang_analyze.html">ANALYZE</a> command is enhanced to collect

563

histogram data from each index and store that data

564

in the sqlite_stat3 table. The query planner will then use the

565

histogram data to help it make better index choices.

566

</blockquote><a name="enable_tree_explain"></a>

567

SQLITE_ENABLE_TREE_EXPLAIN<blockquote>

568

This option adds support for the <a href="c3ref/c_testctrl_always.html">SQLITE_TESTCTRL_EXPLAIN_STMT</a> test-control

569

in the SQLite core. When the <a href="sqlite.html">command-line shell</a> is also compiled with

570

this option, the ".explain" dot-command enables a mode that uses the

571

<a href="c3ref/c_testctrl_always.html">SQLITE_TESTCTRL_EXPLAIN_STMT</a> interface to display an ASCII-art diagram

572

of the parse tree for each SQL query statement that is run in the shell.

573

This mechanism is useful for debugging the SQLite parser and code

574

generator. This whole mechanism is highly experimental and could change

575

drastically or be eliminated in future releases of SQLite.

576

</blockquote><a name="enable_update_delete_limit"></a>

577

SQLITE_ENABLE_UPDATE_DELETE_LIMIT<blockquote>

578

This option enables an optional ORDER BY and LIMIT clause on

579

<a href="lang_update.html">UPDATE</a> and <a href="lang_delete.html">DELETE</a> statements.

580

581

If this option is defined, then it must also be

582

defined when using the 'lemon' tool to generate a parse.c

583

file. Because of this, this option may only be used when the library is built

584

from source, not from the <a href="amalgamation.html">amalgamation</a> or from the collection of

585

pre-packaged C files provided for non-Unix like platforms on the website.

586

587

</blockquote><a name="enable_unlock_notify"></a>

588

SQLITE_ENABLE_UNLOCK_NOTIFY<blockquote>

589

This option enables the <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> interface and

590

its associated functionality. See the documentation titled

591

<a href="unlock_notify.html">Using the SQLite Unlock Notification Feature</a> for additional

592

information.

593

</blockquote><a name="soundex"></a>

594

SQLITE_SOUNDEX<blockquote>

595

This option enables the <a href="lang_corefunc.html#soundex">soundex() SQL function</a>.

596

</blockquote><a name="yytrackmaxstackdepth"></a>

597

YYTRACKMAXSTACKDEPTH<blockquote>

598

This option causes the LALR(1) parser stack depth to be tracked

599

and reported using the <a href="c3ref/status.html">sqlite3_status</a>(<a href="c3ref/c_status_malloc_count.html#sqlitestatusparserstack">SQLITE_STATUS_PARSER_STACK</a>,...)

600

interface. SQLite's LALR(1) parser has a fixed stack depth

601

(determined at compile-time using the <a href="compile.html#yystackdepth">YYSTACKDEPTH</a> options).

602

This option can be used to help determine if an application is

603

getting close to exceeding the maximum LALR(1) stack depth.

604

</blockquote>

605

606

607

<h2>1.5 Options To Disable Features Normally Turned On</h2>

608

609

610

SQLITE_DISABLE_LFS<blockquote>

611

If this C-preprocessor macro is defined, large file support

612

is disabled.

613

</blockquote><a name="disable_dirsync"></a>

614

SQLITE_DISABLE_DIRSYNC<blockquote>

615

If this C-preprocessor macro is defined, directory syncs

616

are disabled. SQLite typically attempts to sync the parent

617

directory when a file is deleted to ensure the directory

618

entries are updated immediately on disk.

619

</blockquote><a name="disable_fts3_unicode"></a>

620

SQLITE_DISABLE_FTS3_UNICODE<blockquote>

621

If this C-preprocessor macro is defined, the <a href="fts3.html#unicode61">unicode61</a> tokenizer

622

in <a href="fts3.html">FTS3</a> is omitted from the build and is unavailable to

623

applications.

624

</blockquote>

625

626

627

628

<h2>1.6 Options To Omit Features</h2>

629

630

The following options can used to

631

<a href="footprint.html#relfootprint">reduce the size of the compiled library</a>

632

by omitting unused features. This is probably only useful

633

in embedded systems where space is especially tight, as even with all

634

features included the SQLite library is relatively small. Don't forget

635

to tell your compiler to optimize for binary size! (the -Os option if

636

using GCC). Telling your compiler to optimize for size usually has

637

a much larger impact on library footprint than employing any of these

638

compile-time options. You should also verify that

639

<a href="#debugoptions">debugging options</a> are disabled.

640

641

The macros in this section do not require values. The following

642

compilation switches all have the same effect:

643

-DSQLITE_OMIT_ALTERTABLE

644

-DSQLITE_OMIT_ALTERTABLE=1

645

-DSQLITE_OMIT_ALTERTABLE=0

646

647

648

If any of these options are defined, then the same set of SQLITE_OMIT_*

649

options must also be defined when using the 'lemon' tool to generate the

650

parse.c file and when compiling the 'mkkeywordhash' tool which generates

651

the keywordhash.h file.

652

Because of this, these options may only be used when the library is built

653

from canonical source, not from the <a href="amalgamation.html">amalgamation</a> or from the collection of

654

pre-packaged C files provided for non-Unix like platforms on the website.

655

Any SQLITE_OMIT_* options which can be used directly with the <a href="amalgamation.html">amalgamation</a>

656

are listed below, however, the warnings in the following paragraph should be noted.

657

658

659

660

Important Note: The SQLITE_OMIT_* options do not work with the

661

<a href="amalgamation.html">amalgamation</a> or with pre-packaged C code files. SQLITE_OMIT_* compile-time

662

options only work correctly when SQLite is built from canonical source files.

663

664

</blockquote>

665

666

667

Special versions of the SQLite amalgamation that do work with a

668

predetermined set of SQLITE_OMIT_* options can be generated. To do so,

669

make a copy of the Makefile.linux-gcc makefile template in the canonical

670

source code distribution. Change the name of your copy to simply "Makefile".

671

Then edit "Makefile" to set up appropriate compile-time options. Then

672

type:

673

<blockquote><tt>make clean; make sqlite3.c</tt></blockquote>

674

The resulting "sqlite3.c" amalgamation code file (and its associated

675

header file "sqlite3.h") can then be moved to a non-unix platform

676

for final compilation using a native compiler.

677

678

All of the SQLITE_OMIT_* options are unsupported.

679

680

681

Important Note:

682

The SQLITE_OMIT_* compile-time options are unsupported.

683

</blockquote>

684

685

686

The SQLITE_OMIT_* compile-time options are usually untested and

687

are almost certainly untested in combination.

688

Any or all of these options may be removed from the code in future releases

689

and without warning. For any particular release, some of these

690

options may cause compile-time or run-time failures, particularly

691

when used in combination with other options.

692

693

694

SQLITE_OMIT_ALTERTABLE<blockquote>

695

When this option is defined, the

696

<a href="lang_altertable.html">ALTER TABLE</a> command is not included in the

697

library. Executing an <a href="lang_altertable.html">ALTER TABLE</a> statement causes a parse error.

698

</blockquote><a name="omit_analyze"></a>

699

SQLITE_OMIT_ANALYZE<blockquote>

700

When this option is defined, the <a href="lang_analyze.html">ANALYZE</a> command is omitted from

701

the build.

702

</blockquote><a name="omit_attach"></a>

703

SQLITE_OMIT_ATTACH<blockquote>

704

When this option is defined, the <a href="lang_attach.html">ATTACH</a> and <a href="lang_detach.html">DETACH</a> commands are

705

omitted from the build.

706

</blockquote><a name="omit_authorization"></a>

707

SQLITE_OMIT_AUTHORIZATION<blockquote>

708

Defining this option omits the authorization callback feature from the

709

library. The <a href="c3ref/set_authorizer.html">sqlite3_set_authorizer()</a> API function is not present

710

in the library.

711

</blockquote><a name="omit_autoincrement"></a>

712

SQLITE_OMIT_AUTOINCREMENT<blockquote>

713

This option is used to omit the

714

<a href="autoinc.html">AUTOINCREMENT</a> functionality. When this

715

is macro is defined, columns declared as

716

"<a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a> AUTOINCREMENT"

717

behave in the same way as columns declared as "<a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a>" when a

718

NULL is inserted. The sqlite_sequence system table is neither created, nor

719

respected if it already exists.

720

</blockquote><a name="omit_autoinit"></a>

721

SQLITE_OMIT_AUTOINIT<blockquote>

722

For backwards compatibility with older versions of SQLite that lack

723

the <a href="c3ref/initialize.html">sqlite3_initialize()</a> interface, the <a href="c3ref/initialize.html">sqlite3_initialize()</a> interface

724

is called automatically upon entry to certain key interfaces such as

725

<a href="c3ref/open.html">sqlite3_open()</a>, <a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>, and <a href="c3ref/mprintf.html">sqlite3_mprintf()</a>.

726

The overhead of invoking <a href="c3ref/initialize.html">sqlite3_initialize()</a> automatically in this

727

way may be omitted by building SQLite with the SQLITE_OMIT_AUTOINIT

728

C-preprocessor macro. When built using SQLITE_OMIT_AUTOINIT, SQLite

729

will not automatically initialize itself and the application is required

730

to invoke <a href="c3ref/initialize.html">sqlite3_initialize()</a> directly prior to beginning use of the

731

SQLite library.

732

</blockquote><a name="omit_automatic_index"></a>

733

SQLITE_OMIT_AUTOMATIC_INDEX<blockquote>

734

This option is used to omit the

735

<a href="optoverview.html#autoindex">automatic indexing</a> functionality.

736

</blockquote><a name="omit_autoreset"></a>

737

SQLITE_OMIT_AUTORESET<blockquote>

738

By default, the <a href="c3ref/step.html">sqlite3_step()</a> interface will automatically invoke

739

<a href="c3ref/reset.html">sqlite3_reset()</a> to reset the <a href="c3ref/stmt.html">prepared statement</a> if necessary. This

740

compile-time option changes that behavior so that <a href="c3ref/step.html">sqlite3_step()</a> will

741

return <a href="c3ref/c_abort.html">SQLITE_MISUSE</a> if it called again after returning anything other

742

than <a href="c3ref/c_abort.html">SQLITE_ROW</a>, <a href="c3ref/c_abort.html">SQLITE_BUSY</a>, or <a href="c3ref/c_abort.html">SQLITE_LOCKED</a> unless there was an

743

intervening call to <a href="c3ref/reset.html">sqlite3_reset()</a>.

744

745

In SQLite version 3.6.23.1 and earlier, <a href="c3ref/step.html">sqlite3_step()</a> used to always

746

return <a href="c3ref/c_abort.html">SQLITE_MISUSE</a> if it was invoked again after returning anything

747

other than <a href="c3ref/c_abort.html">SQLITE_ROW</a> without an intervening call to <a href="c3ref/reset.html">sqlite3_reset()</a>.

748

This caused problems on some poorly written smartphone applications which

749

did not correctly handle the <a href="c3ref/c_abort.html">SQLITE_LOCKED</a> and <a href="c3ref/c_abort.html">SQLITE_BUSY</a> error

750

returns. Rather than fix the many defective smartphone applications,

751

the behavior of SQLite was changed in 3.6.23.2 to automatically reset

752

the prepared statement. But that changed caused issues in other

753

improperly implemented applications that were actually looking

754

for an <a href="c3ref/c_abort.html">SQLITE_MISUSE</a> return to terminate their query loops. (Anytime

755

an application gets an SQLITE_MISUSE error code from SQLite, that means the

756

application is misusing the SQLite interface and is thus incorrectly

757

implemented.) The SQLITE_OMIT_AUTORESET interface was added to SQLite

758

version 3.7.5 in an effort to get all of the (broken)

759

applications to work again without having to actually fix the applications.

760

</blockquote><a name="omit_autovacuum"></a>

761

SQLITE_OMIT_AUTOVACUUM<blockquote>

762

If this option is defined, the library cannot create or write to

763

databases that support <a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a>.

764

Executing a <a href="pragma.html#pragma_auto_vacuum">PRAGMA auto_vacuum</a> statement is not an error

765

(since unknown PRAGMAs are silently ignored), but does not return a value

766

or modify the auto-vacuum flag in the database file. If a database that

767

supports auto-vacuum is opened by a library compiled with this option, it

768

is automatically opened in read-only mode.

769

</blockquote><a name="omit_between_optimization"></a>

770

SQLITE_OMIT_BETWEEN_OPTIMIZATION<blockquote>

771

This option disables the use of indices with WHERE clause terms

772

that employ the BETWEEN operator.

773

</blockquote><a name="omit_blob_literal"></a>

774

SQLITE_OMIT_BLOB_LITERAL<blockquote>

775

When this option is defined, it is not possible to specify a blob in

776

an SQL statement using the X'ABCD' syntax.

777

</blockquote><a name="omit_btreecount"></a>

778

SQLITE_OMIT_BTREECOUNT<blockquote>

779

When this option is defined, an optimization that accelerates counting

780

all entries in a table (in other words, an optimization that helps

781

"SELECT count(*) FROM table" run faster) is omitted.

782

</blockquote><a name="omit_builtin_test"></a>

783

SQLITE_OMIT_BUILTIN_TEST<blockquote>

784

A standard SQLite build includes a small amount of logic controlled

785

by the <a href="c3ref/test_control.html">sqlite3_test_control()</a> interface that is used to exercise

786

parts of the SQLite core that are difficult to control and measure using

787

the standard API. This option omits that built-in test logic.

788

</blockquote><a name="omit_cast"></a>

789

SQLITE_OMIT_CAST<blockquote>

790

This option causes SQLite to omit support for the CAST operator.

791

</blockquote><a name="omit_check"></a>

792

SQLITE_OMIT_CHECK<blockquote>

793

This option causes SQLite to omit support for CHECK constraints.

794

The parser will still accept CHECK constraints in SQL statements,

795

they will just not be enforced.

796

</blockquote><a name="omit_compileoption_diags"></a>

797

SQLITE_OMIT_COMPILEOPTION_DIAGS<blockquote>

798

This option is used to omit the compile-time option diagnostics available

799

in SQLite, including the <a href="c3ref/compileoption_get.html">sqlite3_compileoption_used()</a> and

800

<a href="c3ref/compileoption_get.html">sqlite3_compileoption_get()</a> C/C++ functions, the

801

<a href="lang_corefunc.html#sqlite_compileoption_used">sqlite_compileoption_used()</a> and <a href="lang_corefunc.html#sqlite_compileoption_get">sqlite_compileoption_get()</a> SQL functions,

802

and the <a href="pragma.html#pragma_compile_options">compile_options pragma</a>.

803

</blockquote><a name="omit_complete"></a>

804

SQLITE_OMIT_COMPLETE<blockquote>

805

This option causes the <a href="c3ref/complete.html">sqlite3_complete()</a> and <a href="c3ref/complete.html">sqlite3_complete16()</a>

806

interfaces to be omitted.

807

</blockquote><a name="omit_compound_select"></a>

808

SQLITE_OMIT_COMPOUND_SELECT<blockquote>

809

This option is used to omit the compound <a href="lang_select.html">SELECT</a> functionality.

810

<a href="lang_select.html">SELECT</a> statements that use the

811

UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will

812

cause a parse error.

813

814

An <a href="lang_insert.html">INSERT</a> statement with multiple values in the VALUES clause is

815

implemented internally as a compound SELECT. Hence, this option also

816

disables the ability to insert more than a single row using an

817

INSERT INTO ... VALUES ... statement.

818

</blockquote><a name="omit_datetime_funcs"></a>

819

SQLITE_OMIT_DATETIME_FUNCS<blockquote>

820

If this option is defined, SQLite's built-in date and time manipulation

821

functions are omitted. Specifically, the SQL functions julianday(), date(),

822

time(), datetime() and strftime() are not available. The default column

823

values CURRENT_TIME, CURRENT_DATE and CURRENT_TIMESTAMP are still available.

824

</blockquote><a name="omit_decltype"></a>

825

SQLITE_OMIT_DECLTYPE<blockquote>

826

This option causes SQLite to omit support for the

827

<a href="c3ref/column_decltype.html">sqlite3_column_decltype()</a> and <a href="c3ref/column_decltype.html">sqlite3_column_decltype16()</a>

828

interfaces.

829

</blockquote><a name="omit_deprecated"></a>

830

SQLITE_OMIT_DEPRECATED<blockquote>

831

This option causes SQLite to omit support for interfaces

832

marked as deprecated. This includes

833

<a href="c3ref/aggregate_count.html">sqlite3_aggregate_count()</a>,

834

<a href="c3ref/aggregate_count.html">sqlite3_expired()</a>,

835

<a href="c3ref/aggregate_count.html">sqlite3_transfer_bindings()</a>,

836

<a href="c3ref/aggregate_count.html">sqlite3_global_recover()</a>,

837

<a href="c3ref/aggregate_count.html">sqlite3_thread_cleanup()</a> and

838

<a href="c3ref/aggregate_count.html">sqlite3_memory_alarm()</a> interfaces.

839

</blockquote><a name="omit_diskio"></a>

840

SQLITE_OMIT_DISKIO<blockquote>

841

This option omits all support for writing to the disk and forces

842

databases to exist in memory only. This option has not been

843

maintained and probably does not work with newer versions of SQLite.

844

</blockquote><a name="omit_explain"></a>

845

SQLITE_OMIT_EXPLAIN<blockquote>

846

Defining this option causes the <a href="lang_explain.html">EXPLAIN</a> command to be omitted from the

847

library. Attempting to execute an <a href="lang_explain.html">EXPLAIN</a> statement will cause a parse

848

error.

849

</blockquote><a name="omit_flag_pragmas"></a>

850

SQLITE_OMIT_FLAG_PRAGMAS<blockquote>

851

This option omits support for a subset of <a href="pragma.html#syntax">PRAGMA</a> commands that

852

query and set boolean properties.

853

</blockquote><a name="omit_floating_point"></a>

854

SQLITE_OMIT_FLOATING_POINT<blockquote>

855

This option is used to omit floating-point number support from the SQLite

856

library. When specified, specifying a floating point number as a literal

857

(i.e. "1.01") results in a parse error.

858

859

In the future, this option may also disable other floating point

860

functionality, for example the <a href="c3ref/result_blob.html">sqlite3_result_double()</a>,

861

<a href="c3ref/bind_blob.html">sqlite3_bind_double()</a>, <a href="c3ref/value_blob.html">sqlite3_value_double()</a> and

862

<a href="c3ref/column_blob.html">sqlite3_column_double()</a> API functions.

863

864

</blockquote><a name="omit_foreign_key"></a>

865

SQLITE_OMIT_FOREIGN_KEY<blockquote>

866

If this option is defined, then <a href="foreignkeys.html">foreign key constraint</a> syntax is

867

not recognized.

868

</blockquote><a name="omit_get_table"></a>

869

SQLITE_OMIT_GET_TABLE<blockquote>

870

This option causes support for <a href="c3ref/free_table.html">sqlite3_get_table()</a> and

871

<a href="c3ref/free_table.html">sqlite3_free_table()</a> to be omitted.

872

</blockquote><a name="omit_incrblob"></a>

873

SQLITE_OMIT_INCRBLOB<blockquote>

874

This option causes support for <a href="c3ref/blob.html">incremental BLOB I/O</a>

875

to be omitted.

876

</blockquote><a name="omit_integrity_check"></a>

877

SQLITE_OMIT_INTEGRITY_CHECK<blockquote>

878

This option omits support for the <a href="pragma.html#pragma_integrity_check">integrity_check pragma</a>.

879

</blockquote><a name="omit_like_optimization"></a>

880

SQLITE_OMIT_LIKE_OPTIMIZATION<blockquote>

881

This option disables the ability of SQLite to use indices to help

882

resolve <a href="lang_expr.html#like">LIKE</a> and <a href="lang_expr.html#glob">GLOB</a> operators in a WHERE clause.

883

</blockquote><a name="omit_load_extension"></a>

884

SQLITE_OMIT_LOAD_EXTENSION<blockquote>

885

This option omits the entire extension loading mechanism from

886

SQLite, including <a href="c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a> and

887

<a href="c3ref/load_extension.html">sqlite3_load_extension()</a> interfaces.

888

</blockquote><a name="omit_localtime"></a>

889

SQLITE_OMIT_LOCALTIME<blockquote>

890

This option omits the "localtime" modifier from the date and time

891

functions. This option is sometimes useful when trying to compile

892

the date and time functions on a platform that does not support the

893

concept of local time.

894

</blockquote><a name="omit_lookaside"></a>

895

SQLITE_OMIT_LOOKASIDE<blockquote>

896

This option omits the <a href="malloc.html#lookaside">lookaside memory allocator</a>.

897

</blockquote><a name="omit_memorydb"></a>

898

SQLITE_OMIT_MEMORYDB<blockquote>

899

When this is defined, the library does not respect the special database

900

name ":memory:" (normally used to create an <a href="inmemorydb.html">in-memory database</a>). If

901

":memory:" is passed to <a href="c3ref/open.html">sqlite3_open()</a>, <a href="c3ref/open.html">sqlite3_open16()</a>, or

902

<a href="c3ref/open.html">sqlite3_open_v2()</a>, a file with this name will be

903

opened or created.

904

</blockquote><a name="omit_merge_sort"></a>

905

SQLITE_OMIT_MERGE_SORT<blockquote>

906

Beginning with SQLite <a href="releaselog/3_7_8.html">version 3.7.8</a>, large sort operations such as

907

used by <a href="lang_createindex.html">CREATE INDEX</a> commands are implemented using an external

908

merge sort rather than insertions into a B-Tree. This results in better

909

cache locality and an order-of-magnitude speed improvement for sorts that

910

are larger than the filesystem cache. On the other hand, the merge sort

911

logic uses some code space and is slightly (1%) slower for <a href="lang_createindex.html">CREATE INDEX</a>

912

on small tables. The external merge sort can be disabled using this

913

compile-time option.

914

</blockquote><a name="omit_or_optimization"></a>

915

SQLITE_OMIT_OR_OPTIMIZATION<blockquote>

916

This option disables the ability of SQLite to use an index together

917

with terms of a WHERE clause connected by the OR operator.

918

</blockquote><a name="omit_pager_pragmas"></a>

919

SQLITE_OMIT_PAGER_PRAGMAS<blockquote>

920

Defining this option omits pragmas related to the pager subsystem from

921

the build.

922

</blockquote><a name="omit_pragma"></a>

923

SQLITE_OMIT_PRAGMA<blockquote>

924

This option is used to omit the <a href="pragma.html#syntax">PRAGMA</a> command

925

from the library. Note that it is useful to define the macros that omit

926

specific pragmas in addition to this, as they may also remove supporting code

927

in other sub-systems. This macro removes the <a href="pragma.html#syntax">PRAGMA</a> command only.

928

</blockquote><a name="omit_progress_callback"></a>

929

SQLITE_OMIT_PROGRESS_CALLBACK<blockquote>

930

This option may be defined to omit the capability to issue "progress"

931

callbacks during long-running SQL statements. The

932

<a href="c3ref/progress_handler.html">sqlite3_progress_handler()</a>

933

API function is not present in the library.

934

</blockquote><a name="omit_quickbalance"></a>

935

SQLITE_OMIT_QUICKBALANCE<blockquote>

936

This option omits an alternative, faster B-Tree balancing routine.

937

Using this option makes SQLite slightly smaller at the expense of

938

making it run slightly slower.

939

</blockquote><a name="omit_reindex"></a>

940

SQLITE_OMIT_REINDEX<blockquote>

941

When this option is defined, the <a href="lang_reindex.html">REINDEX</a>

942

command is not included in the library.

943

Executing a <a href="lang_reindex.html">REINDEX</a> statement causes

944

a parse error.

945

</blockquote><a name="omit_schema_pragmas"></a>

946

SQLITE_OMIT_SCHEMA_PRAGMAS<blockquote>

947

Defining this option omits pragmas for querying the database schema from

948

the build.

949

</blockquote><a name="omit_schema_version_pragmas"></a>

950

SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS<blockquote>

951

Defining this option omits pragmas for querying and modifying the

952

database schema version and user version from the build. Specifically, the

953

<a href="pragma.html#pragma_schema_version">schema_version</a> and <a href="pragma.html#pragma_schema_version">user_version</a> PRAGMAs are omitted.

954

</blockquote><a name="omit_shared_cache"></a>

955

SQLITE_OMIT_SHARED_CACHE<blockquote>

956

This option builds SQLite without support for shared-cache mode.

957

The <a href="c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a> is omitted along with a fair

958

amount of logic within the B-Tree subsystem associated with shared

959

cache management.

960

</blockquote><a name="omit_subquery"></a>

961

SQLITE_OMIT_SUBQUERY<blockquote>

962

If defined, support for sub-selects and the IN() operator are omitted.

963

</blockquote><a name="omit_tcl_variable"></a>

964

SQLITE_OMIT_TCL_VARIABLE<blockquote>

965

If this macro is defined, then the special "$<variable-name>" syntax

966

used to automatically bind SQL variables to TCL variables is omitted.

967

</blockquote><a name="omit_tempdb"></a>

968

SQLITE_OMIT_TEMPDB<blockquote>

969

This option omits support for TEMP or TEMPORARY tables.

970

</blockquote><a name="omit_trace"></a>

971

SQLITE_OMIT_TRACE<blockquote>

972

This option omits support for the <a href="c3ref/profile.html">sqlite3_profile()</a> and

973

<a href="c3ref/profile.html">sqlite3_trace()</a> interfaces and their associated logic.

974

</blockquote><a name="omit_trigger"></a>

975

SQLITE_OMIT_TRIGGER<blockquote>

976

Defining this option omits support for TRIGGER objects. Neither the

977

<a href="lang_createtrigger.html">CREATE TRIGGER</a> or <a href="lang_droptrigger.html">DROP TRIGGER</a>

978

commands are available in this case, and attempting to execute

979

either will result in a parse error.

980

This option also disables enforcement of <a href="foreignkeys.html">foreign key constraints</a>,

981

since the code that implements triggers and which is omitted by this

982

option is also used to implement <a href="foreignkeys.html#fk_actions">foreign key actions</a>.

983

</blockquote><a name="omit_truncate_optimization"></a>

984

SQLITE_OMIT_TRUNCATE_OPTIMIZATION<blockquote>

985

A default build of SQLite, if a <a href="lang_delete.html">DELETE</a> statement has no WHERE clause

986

and operates on a table with no triggers, an optimization occurs that

987

causes the DELETE to occur by dropping and recreating the table.

988

Dropping and recreating a table is usually much faster than deleting

989

the table content row by row. This is the "truncate optimization".

990

</blockquote><a name="omit_utf16"></a>

991

SQLITE_OMIT_UTF16<blockquote>

992

This macro is used to omit support for UTF16 text encoding. When this is

993

defined all API functions that return or accept UTF16 encoded text are

994

unavailable. These functions can be identified by the fact that they end

995

with '16', for example <a href="c3ref/prepare.html">sqlite3_prepare16()</a>, <a href="c3ref/column_blob.html">sqlite3_column_text16()</a> and

996

<a href="c3ref/bind_blob.html">sqlite3_bind_text16()</a>.

997

</blockquote><a name="omit_vacuum"></a>

998

SQLITE_OMIT_VACUUM<blockquote>

999

When this option is defined, the <a href="lang_vacuum.html">VACUUM</a>

1000

command is not included in the library.

1001

Executing a <a href="lang_vacuum.html">VACUUM</a> statement causes

1002

a parse error.

1003

</blockquote><a name="omit_view"></a>

1004

SQLITE_OMIT_VIEW<blockquote>

1005

Defining this option omits support for VIEW objects. Neither the

1006

<a href="lang_createview.html">CREATE VIEW</a> nor the <a href="lang_dropview.html">DROP VIEW</a>

1007

commands are available in this case, and

1008

attempting to execute either will result in a parse error.

1009

1010

WARNING: If this macro is defined, it will not be possible to open a database

1011

for which the schema contains VIEW objects.

1012

</blockquote><a name="omit_virtualtable"></a>

1013

SQLITE_OMIT_VIRTUALTABLE<blockquote>

1014

This option omits support for the <a href="c3ref/vtab.html">Virtual Table</a>

1015

mechanism in SQLite.

1016

</blockquote><a name="omit_wal"></a>

1017

SQLITE_OMIT_WAL<blockquote>

1018

This option omits the "<a href="wal.html">write-ahead log</a>" (a.k.a. "<a href="wal.html">WAL</a>") capability.

1019

</blockquote><a name="omit_wsd"></a>

1020

SQLITE_OMIT_WSD<blockquote>

1021

This options builds a version of the SQLite library that contains no

1022

Writable Static Data (WSD). WSD is global variables and/or static

1023

variables. Some platforms do not support WSD, and this option is necessary

1024

in order for SQLite to work those platforms.

1025

1026

Unlike other OMIT options which make the SQLite library smaller,

1027

this option actually increases the size of SQLite and makes it run

1028

a little slower. Only use this option if SQLite is being built for an

1029

embedded target that does not support WSD.

1030

</blockquote><a name="omit_xfer_opt"></a>

1031

SQLITE_OMIT_XFER_OPT<blockquote>

1032

This option omits support for optimizations that help statements

1033

of the form "INSERT INTO ... SELECT ..." run faster.

1034

</blockquote><a name="zero_malloc"></a>

1035

SQLITE_ZERO_MALLOC<blockquote>

1036

This option omits both the <a href="malloc.html#defaultalloc">default memory allocator</a> and the

1037

<a href="malloc.html#memdebug">debugging memory allocator</a> from the build and substitutes a stub

1038

memory allocator that always fails. SQLite will not run with this

1039

stub memory allocator since it will be unable to allocate memory. But

1040

this stub can be replaced at start-time using

1041

<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>,...) or

1042

<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a>,...).

1043

So the net effect of this compile-time option is that it allows SQLite

1044

to be compiled and linked against a system library that does not support

1045

malloc(), free(), and/or realloc().

1046

</blockquote>

1047

1048

<h2>1.7 Analysis and Debugging Options</h2>

1049

1050

SQLITE_DEBUG<blockquote>

1051

The SQLite source code contains literally thousands of assert() statements

1052

used to verify internal assumptions and subroutine preconditions and

1053

postconditions. These assert() statements are normally turned off

1054

(they generate no code) since turning them on makes SQLite run approximately

1055

three times slower. But for testing and analysis, it is useful to turn

1056

the assert() statements on. The SQLITE_DEBUG compile-time option does this.

1057

SQLITE_DEBUG also turns on some other debugging features.

1058

</blockquote><a name="memdebug"></a>

1059

SQLITE_MEMDEBUG<blockquote>

1060

The SQLITE_MEMDEBUG option causes an instrumented

1061

<a href="malloc.html#memdebug">debugging memory allocator</a>

1062

to be used as the default memory allocator within SQLite. The

1063

instrumented memory allocator checks for misuse of dynamically allocated

1064

memory. Examples of misuse include using memory after it is freed,

1065

writing off the ends of a memory allocation, freeing memory not previously

1066

obtained from the memory allocator, or failing to initialize newly

1067

allocated memory.

1068

</blockquote>

1069