SQLite

Check-in [2640f518de]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update the FAQ to describe how moving sqlite3 handles across threads is not safe with SQLITE_ENABLE_MEMORY_MANAGEMENT. Tickets #2357 and #2463. (CVS 4136)
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 2640f518deba1d196201fac903ec4d3ab26d4bb3
User & Date: drh 2007-06-27 00:08:40.000
Context
2007-06-27
00:36
Set the connection error code when sqlite3_blob_read() or sqlite3_blob_write() fail. Ticket #2464. (CVS 4137) (check-in: 3bd990be3c user: drh tags: trunk)
00:08
Update the FAQ to describe how moving sqlite3 handles across threads is not safe with SQLITE_ENABLE_MEMORY_MANAGEMENT. Tickets #2357 and #2463. (CVS 4136) (check-in: 2640f518de user: drh tags: trunk)
2007-06-26
22:55
Make sure the TCL bindings always use Tcl_GetWideIntFromObj() even if the reported type is "int" because on x86-64 and "int" type is 64-bits. Ticket #2465. (CVS 4135) (check-in: 5c93324b93 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to www/faq.tcl.
1
2
3
4
5
6
7
8
9
10
11
#
# Run this script to generated a faq.html output file
#
set rcsid {$Id: faq.tcl,v 1.37 2007/06/09 09:53:51 drh Exp $}
source common.tcl
header {SQLite Frequently Asked Questions</title>}

set cnt 1
proc faq {question answer} {
  set ::faq($::cnt) [list [string trim $question] [string trim $answer]]
  incr ::cnt



|







1
2
3
4
5
6
7
8
9
10
11
#
# Run this script to generated a faq.html output file
#
set rcsid {$Id: faq.tcl,v 1.38 2007/06/27 00:08:40 drh Exp $}
source common.tcl
header {SQLite Frequently Asked Questions</title>}

set cnt 1
proc faq {question answer} {
  set ::faq($::cnt) [list [string trim $question] [string trim $answer]]
  incr ::cnt
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
  consider using a client/server database.  But experience suggests that
  most applications need much less concurrency than their designers imagine.
  </p>

  <p>When SQLite tries to access a file that is locked by another
  process, the default behavior is to return SQLITE_BUSY.  You can
  adjust this behavior from C code using the 
  <a href="capi3ref#sqlite3_busy_handler">sqlite3_busy_handler()</a> or
  <a href="capi3ref#sqlite3_busy_timeout">sqlite3_busy_timeout()</a>
  API functions.</p>
}

faq {
  Is SQLite threadsafe?
} {
  <p>Yes.  Sometimes.  In order to be thread-safe, SQLite must be compiled
  with the THREADSAFE preprocessor macro set to 1.  In the default
  distribution, the windows binaries are compiled to be threadsafe but
  the linux binaries are not.  If you want to change this, you'll have to
  recompile.</p>

  <p>"Threadsafe" in the previous paragraph means that two or more threads
  can run SQLite at the same time on different "<b>sqlite3</b>" structures
  returned from separate calls to 
  <a href="capi3ref#sqlite3_open">sqlite3_open()</a>.  It is never safe
  to use the same <b>sqlite3</b> structure pointer in two
  or more threads.</p>

  <p>Prior to version 3.3.1,
  an <b>sqlite3</b> structure could only be used in the same thread
  that called <a href="capi3ref#sqlite3_open">sqlite3_open</a> to create it.

  You could not open a
  database in one thread then pass the handle off to another thread for
  it to use.  This was due to limitations (bugs?) in many common threading
  implementations such as on RedHat9.  Specifically, an fcntl() lock
  created by one thread cannot be removed or modified by a different
  thread on the troublesome systems.  And since SQLite uses fcntl()
  locks heavily for concurrency control, serious problems arose if you 
  start moving database connections across threads.</p>

  <p>The restriction on moving database connections across threads
  was relaxed somewhat in version 3.3.1.  With that and subsequent
  versions, it is safe to move a connection handle across threads
  as long as the connection is not holding any fcntl() locks.  You
  can safely assume that no locks are being held if no
  transaction is pending and all statements have been finalized.</p>












  <p>Under UNIX, you should not carry an open SQLite database across
  a fork() system call into the child process.  Problems will result
  if you do.</p>
}

faq {
  How do I list all tables/indices contained in an SQLite database







|
|















|





|
>
















>
>
>
>
>
>
>
>
>
>
>







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
  consider using a client/server database.  But experience suggests that
  most applications need much less concurrency than their designers imagine.
  </p>

  <p>When SQLite tries to access a file that is locked by another
  process, the default behavior is to return SQLITE_BUSY.  You can
  adjust this behavior from C code using the 
  <a href="capi3ref.html#sqlite3_busy_handler">sqlite3_busy_handler()</a> or
  <a href="capi3ref.html#sqlite3_busy_timeout">sqlite3_busy_timeout()</a>
  API functions.</p>
}

faq {
  Is SQLite threadsafe?
} {
  <p>Yes.  Sometimes.  In order to be thread-safe, SQLite must be compiled
  with the THREADSAFE preprocessor macro set to 1.  In the default
  distribution, the windows binaries are compiled to be threadsafe but
  the linux binaries are not.  If you want to change this, you'll have to
  recompile.</p>

  <p>"Threadsafe" in the previous paragraph means that two or more threads
  can run SQLite at the same time on different "<b>sqlite3</b>" structures
  returned from separate calls to 
  <a href="capi3ref.html#sqlite3_open">sqlite3_open()</a>.  It is never safe
  to use the same <b>sqlite3</b> structure pointer in two
  or more threads.</p>

  <p>Prior to version 3.3.1,
  an <b>sqlite3</b> structure could only be used in the same thread
  that called <a href="capi3ref.html#sqlite3_open">sqlite3_open</a>
  to create it.
  You could not open a
  database in one thread then pass the handle off to another thread for
  it to use.  This was due to limitations (bugs?) in many common threading
  implementations such as on RedHat9.  Specifically, an fcntl() lock
  created by one thread cannot be removed or modified by a different
  thread on the troublesome systems.  And since SQLite uses fcntl()
  locks heavily for concurrency control, serious problems arose if you 
  start moving database connections across threads.</p>

  <p>The restriction on moving database connections across threads
  was relaxed somewhat in version 3.3.1.  With that and subsequent
  versions, it is safe to move a connection handle across threads
  as long as the connection is not holding any fcntl() locks.  You
  can safely assume that no locks are being held if no
  transaction is pending and all statements have been finalized.</p>

  <p>If you turn on
  <a href="capi3ref.html#sqlite3_enable_shared_cache">shared cache</a>
  mode or if you compile with the -DSQLITE_ENABLE_MEMORY_MANAGEMENT=1
  option, then you can never move an <b>sqlite3</b> pointer across
  threads.  The <b>sqlite3</b> pointer must only be used in the same
  thread in which it was created by 
  <a href="capi3ref.html#sqlite3_open">sqlite3_open()</a>.  If you
  break the rules and use an <b>sqlite3</b> in more than one thread
  under these circumstances, then you will likely corrupt some
  internal data structures resulting in a crash.</p>

  <p>Under UNIX, you should not carry an open SQLite database across
  a fork() system call into the child process.  Problems will result
  if you do.</p>
}

faq {
  How do I list all tables/indices contained in an SQLite database