From 824a5bfcf059cb35de6226484667a5677a8c9558 Mon Sep 17 00:00:00 2001 From: drh <> Date: Fri, 31 Jan 2025 12:09:36 +0000 Subject: [PATCH] Improvements to the SQLITE_DBCONFIG option documentation. FossilOrigin-Name: 59f0ba10062a6ccfd56061a16af3436b9e1b9d23378bff3302bcf33bb3137cb9 --- manifest | 12 +++--- manifest.uuid | 2 +- src/sqlite.h.in | 105 ++++++++++++++++++++++++++++++------------------ 3 files changed, 74 insertions(+), 45 deletions(-) diff --git a/manifest b/manifest index a93ad027de..2ee13706dc 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Add\sthe\sSQLITE_DBCONFIG_ENABLE_COMMENTS\ssetting\s(default\son)\sto\senable\sor\ndisable\sthe\sability\sto\sinclude\scomments\sin\sSQL\sinput\stext. -D 2025-01-31T01:34:19.160 +C Improvements\sto\sthe\sSQLITE_DBCONFIG\soption\sdocumentation. +D 2025-01-31T12:09:36.393 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea F LICENSE.md e108e1e69ae8e8a59e93c455654b8ac9356a11720d3345df2a4743e9590fb20d @@ -782,7 +782,7 @@ F src/resolve.c c8a5372b97b2a2e972a280676f06ddb5b74e885d3b1f5ce383f839907b57ef68 F src/rowset.c 8432130e6c344b3401a8874c3cb49fefe6873fec593294de077afea2dce5ec97 F src/select.c 83e88fbb36f89b6703b348777491619554f0fd6f917c9fdf51e4c2e9cda6c04e F src/shell.c.in b377a59822f207106424f08aead37e78b609222e98f86f04cc8a03563ccf3237 -F src/sqlite.h.in 30a16e4f6c337803ab0917bb98d94015783a993c970ba56f5deed1dd8684e38f +F src/sqlite.h.in 6bdaf7c577fba45afef371ba69852de9965e23e8b13b9aa099d90281bf0c1e54 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8 F src/sqlite3ext.h 3f046c04ea3595d6bfda99b781926b17e672fd6d27da2ba6d8d8fc39981dcb54 F src/sqliteInt.h 7f1b070ea3b4ab3c192be553810684f686fdb03f62f90afa2da64d4d61d91ec3 @@ -2209,8 +2209,8 @@ F tool/version-info.c 3b36468a90faf1bbd59c65fd0eb66522d9f941eedd364fabccd7227350 F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7 F tool/warnings.sh 49a486c5069de041aedcbde4de178293e0463ae9918ecad7539eedf0ec77a139 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f -P 86ba57561a8d8c14e401c06b2345a9417053aa3a5f0c84e52460f23f5e6aa8d0 -R a8e75b45389fdcc75e19207c37dcdc78 +P 393749a2e22d5c8eba36e2106a35909420aa6316652d1ab4f18ef699247b6fba +R 13662bcaa4e43096d085a0dc17072d0e U drh -Z 58903bc3f8cbb45b4d2beab95c7e825d +Z e7786de21407765a3ba181d8f27262b9 # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index 604c9124fe..6c5aac8ed5 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -393749a2e22d5c8eba36e2106a35909420aa6316652d1ab4f18ef699247b6fba +59f0ba10062a6ccfd56061a16af3436b9e1b9d23378bff3302bcf33bb3137cb9 diff --git a/src/sqlite.h.in b/src/sqlite.h.in index a17c2c5b5f..58482f81cb 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -2223,8 +2223,12 @@ struct sqlite3_mem_methods { **
** [[SQLITE_DBCONFIG_LOOKASIDE]] **
SQLITE_DBCONFIG_LOOKASIDE
-**
^This option takes three additional arguments that determine the -** [lookaside memory allocator] configuration for the [database connection]. +**
The SQLITE_DBCONFIG_LOOKASIDE option is used to adjust the +** configuration of the lookaside memory allocator within a database +** connection. +** The arguments to the SQLITE_DBCONFIG_LOOKASIDE option are not +** in the [DBCONFIG arguments|usual format]. +** The SQLITE_DBCONFIG_LOOKASIDE option takes three arguments, not two. ** ^The first argument (the third parameter to [sqlite3_db_config()] is a ** pointer to a memory buffer to use for lookaside memory. ** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb @@ -2247,7 +2251,8 @@ struct sqlite3_mem_methods { ** [[SQLITE_DBCONFIG_ENABLE_FKEY]] **
SQLITE_DBCONFIG_ENABLE_FKEY
**
^This option is used to enable or disable the enforcement of -** [foreign key constraints]. There should be two additional arguments. +** [foreign key constraints]. This is the same setting that is +** enabled or disabled by the [PRAGMA foreign_keys] statement. ** The first argument is an integer which is 0 to disable FK enforcement, ** positive to enable FK enforcement or negative to leave FK enforcement ** unchanged. The second parameter is a pointer to an integer into which @@ -2269,13 +2274,13 @@ struct sqlite3_mem_methods { **

Originally this option disabled all triggers. ^(However, since ** SQLite version 3.35.0, TEMP triggers are still allowed even if ** this option is off. So, in other words, this option now only disables -** triggers in the main database schema or in the schemas of ATTACH-ed +** triggers in the main database schema or in the schemas of [ATTACH]-ed ** databases.)^

** ** [[SQLITE_DBCONFIG_ENABLE_VIEW]] **
SQLITE_DBCONFIG_ENABLE_VIEW
**
^This option is used to enable or disable [CREATE VIEW | views]. -** There should be two additional arguments. +** There must be two additional arguments. ** The first argument is an integer which is 0 to disable views, ** positive to enable views or negative to leave the setting unchanged. ** The second parameter is a pointer to an integer into which @@ -2294,7 +2299,7 @@ struct sqlite3_mem_methods { **
^This option is used to enable or disable the ** [fts3_tokenizer()] function which is part of the ** [FTS3] full-text search engine extension. -** There should be two additional arguments. +** There must be two additional arguments. ** The first argument is an integer which is 0 to disable fts3_tokenizer() or ** positive to enable fts3_tokenizer() or negative to leave the setting ** unchanged. @@ -2309,7 +2314,7 @@ struct sqlite3_mem_methods { ** interface independently of the [load_extension()] SQL function. ** The [sqlite3_enable_load_extension()] API enables or disables both the ** C-API [sqlite3_load_extension()] and the SQL function [load_extension()]. -** There should be two additional arguments. +** There must be two additional arguments. ** When the first argument to this interface is 1, then only the C-API is ** enabled and the SQL function remains disabled. If the first argument to ** this interface is 0, then both the C-API and the SQL function are disabled. @@ -2323,22 +2328,27 @@ struct sqlite3_mem_methods { ** ** [[SQLITE_DBCONFIG_MAINDBNAME]]
SQLITE_DBCONFIG_MAINDBNAME
**
^This option is used to change the name of the "main" database -** schema. ^The sole argument is a pointer to a constant UTF8 string -** which will become the new schema name in place of "main". ^SQLite -** does not make a copy of the new main schema name string, so the application -** must ensure that the argument passed into this DBCONFIG option is unchanged +** schema. This option does not follow the +** [DBCONFIG arguments|usual SQLITE_DBCONFIG argument format]. +** This option takes exactly one argument, which ust be a pointer +** to a constant UTF8 string which will become the new schema name +** in place of "main". ^SQLite does not make a copy of the new main +** schema name string, so the application must ensure that the argument +** passed into SQLITE_DBCONFIG MAINDBNAME is unchanged ** until after the database connection closes. **
** ** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]] **
SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
-**
Usually, when a database in wal mode is closed or detached from a -** database handle, SQLite checks if this will mean that there are now no -** connections at all to the database. If so, it performs a checkpoint -** operation before closing the connection. This option may be used to -** override this behavior. The first parameter passed to this operation -** is an integer - positive to disable checkpoints-on-close, or zero (the -** default) to enable them, and negative to leave the setting unchanged. +**
Usually, when a database in [WAL mode] is closed or detached from a +** database handle, SQLite checks if if there are other connections to the +** same database, and if there are no other database connection (if the +** connection being closed is the last open connection to the database), +** then SQLite performs a [checkpoint] before closing the connection and +** deletes the WAL file. The SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE option can +** be used to override that behavior. The first parameter passed to this +** operation is an integer - positive to disable checkpoints-on-close, or +** zero (the default) to enable them, and negative to leave the setting unchanged. ** The second parameter is a pointer to an integer ** into which is written 0 or 1 to indicate whether checkpoints-on-close ** have been disabled - 0 if they are not disabled, 1 if they are. @@ -2500,7 +2510,7 @@ struct sqlite3_mem_methods { ** statistics. For statistics to be collected, the flag must be set on ** the database handle both when the SQL statement is prepared and when it ** is stepped. The flag is set (collection of statistics is enabled) -** by default. This option takes two arguments: an integer and a pointer to +** by default.

This option takes two arguments: an integer and a pointer to ** an integer.. The first argument is 1, 0, or -1 to enable, disable, or ** leave unchanged the statement scanstatus option. If the second argument ** is not NULL, then the value of the statement scanstatus setting after @@ -2514,7 +2524,7 @@ struct sqlite3_mem_methods { ** in which tables and indexes are scanned so that the scans start at the end ** and work toward the beginning rather than starting at the beginning and ** working toward the end. Setting SQLITE_DBCONFIG_REVERSE_SCANORDER is the -** same as setting [PRAGMA reverse_unordered_selects]. This option takes +** same as setting [PRAGMA reverse_unordered_selects].

This option takes ** two arguments which are an integer and a pointer to an integer. The first ** argument is 1, 0, or -1 to enable, disable, or leave unchanged the ** reverse scan order flag, respectively. If the second argument is not NULL, @@ -2525,11 +2535,12 @@ struct sqlite3_mem_methods { ** ** [[SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE]] **

SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE
-**
The SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE option enables the ability -** of the [ATTACH DATABASE] SQL command to create a new database if the -** database filed named by the SQL command does not already exist. This -** ability of [ATTACH] to create a new database is enabled by default, but -** can be disabled, using the current DBCONFIG option if desired. +**
The SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE option enables or disables +** the ability of the [ATTACH DATABASE] SQL command to create a new database +** file if the database filed named in the ATTACH command does not already +** exist. This ability of ATTACH to create a new database is enabled by +** default. Applications can disable or reenable the ability for ATTACH to +** create new database files using this DBCONFIG option.

** This option takes two arguments which are an integer and a pointer ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or ** leave unchanged the attach-create flag, respectively. If the second @@ -2540,29 +2551,30 @@ struct sqlite3_mem_methods { ** ** [[SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE]] **

SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE
-**
The SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE option enables the ability -** of the [ATTACH DATABASE] SQL command to create a new database that is -** open for writing. This capability is enabled by default, but -** can be disabled, using the current DBCONFIG option if desired. If this -** capability is disabled, the [ATTACH] command will still work, but the -** database is opened read-only. If this option is disabled, then the -** ability to create a new database using [ATTACH] is also disabled, +**
The SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE option enables or disables the +** ability of the [ATTACH DATABASE] SQL command to open a database for writing. +** This capability is enabled by default. Applications can disable or +** reenable this capability using the current DBCONFIG option. If the +** the this capability is disabled, the [ATTACH] command will still work, +** but the database will be opened read-only. If this option is disabled, +** then the ability to create a new database using [ATTACH] is also disabled, ** regardless of the value of the [SQLITE_DBCONFIG_ENABLE_ATTACH_CREATE] -** option. +** option.

** This option takes two arguments which are an integer and a pointer ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or ** leave unchanged the ability to ATTACH another database for writing, ** respectively. If the second argument is not NULL, then 0 or 1 is written -** into the integer that the second argument points to depending on if the -** ability to ATTACH a read/write database is set +** into the integer to which the second argument points, depending on whether +** the ability to ATTACH a read/write database is enabled or disabled ** after processing the first argument. **

** -** [[SQLITE_DBCONFIG_ENABLE_ATTACH_WRITE]] +** [[SQLITE_DBCONFIG_ENABLE_COMMENTS]] **
SQLITE_DBCONFIG_ENABLE_COMMENTS
**
The SQLITE_DBCONFIG_ENABLE_COMMENTS option enables or disables the -** ability to include comments in SQL text. Comments are enabled by default, -** but can be disabled, using the current DBCONFIG option if desired. +** ability to include comments in SQL text. Comments are enabled by default. +** An application can disable or reenable comments in SQL text using this +** DBCONFIG option.

** This option takes two arguments which are an integer and a pointer ** to an integer. The first argument is 1, 0, or -1 to enable, disable, or ** leave unchanged the ability to use comments in SQL text, @@ -2572,6 +2584,23 @@ struct sqlite3_mem_methods { **

** **
+** +** [[DBCONFIG arguments]]

Arguments To SQLITE_DBCONFIG Options

+** +**

Most of the SQLITE_DBCONFIG options take two argument, an integer +** and a pointer to an integer. If the first integer argument is 1, then +** the option becomes enabled. If the first integer argument is 0, then the +** option is disabled. If the first argument is -1, then the option setting +** is unchanged. The second argument, the pointer to an integer, may be NULL. +** If the second argument is not NULL, then a value of 0 or 1 is written into +** the integer to which the second argument points, depending on whether the +** setting is disabled or enabled after applying any changes specified by +** the first argument. +** +**

While most SQLITE_DBCONFIG options use the argument format +** described in the previous paragraph, the [SQLITE_DBCONFIG_MAINDBNAME] +** and [SQLITE_DBCONFIG_LOOKASIDE] options are different. See the +** documentation of those exceptional options for details. */ #define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */ #define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */ -- 2.39.5