summaryrefslogtreecommitdiffstats
path: root/www/inmemorydb.html
blob: df4e7320d6e1c39dd7033ecb6f032f34f2ffab9e (plain)
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
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="sqlite.css" rel="stylesheet">
<title>In-Memory Databases</title>
<!-- path= -->
</head>
<body>
<div class=nosearch>
<a href="index.html">
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='about.html'>About</a>
<li class='desktoponly'><a href="docs.html">Documentation</a>
<li class='desktoponly'><a href="download.html">Download</a>
<li class='wideonly'><a href='copyright.html'>License</a>
<li class='desktoponly'><a href="support.html">Support</a>
<li class='desktoponly'><a href="prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='about.html'>About</a>
<li><a href='docs.html'>Documentation</a>
<li><a href='download.html'>Download</a>
<li><a href='support.html'>Support</a>
<li><a href='prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>



<h1 align="center">In-Memory Databases</h1>

<p>An SQLite database is normally stored in a single ordinary disk
file. However, in certain circumstances, the database might be stored in
memory.</p>

<p>The most common way to force an SQLite database to exist purely 
in memory is to open the database using the special filename
"<b>:memory:</b>".  In other words, instead of passing the name of
a real disk file into one of the <a href="c3ref/open.html">sqlite3_open()</a>, <a href="c3ref/open.html">sqlite3_open16()</a>, or
<a href="c3ref/open.html">sqlite3_open_v2()</a> functions, pass in the string ":memory:".  For
example:</p>

<blockquote><pre>
rc = sqlite3_open(":memory:", &amp;db);
</pre></blockquote>

<p>When this is done, no disk file is opened.  
Instead, a new database is created
purely in memory.  The database ceases to exist as soon as the database
connection is closed.  Every :memory: database is distinct from every
other.  So, opening two database connections each with the filename
":memory:" will create two independent in-memory databases.</p>

<p>The special filename ":memory:" can be used anywhere that a database
filename is permitted.  For example, it can be used as the
<i>filename</i> in an <a href="lang_attach.html">ATTACH</a> command:</p>

<blockquote><pre>
ATTACH DATABASE ':memory:' AS aux1;
</pre></blockquote>

<p>Note that in order for the special ":memory:" name to apply and to
create a pure in-memory database, there must be no additional text in the
filename.  Thus, a disk-based database can be created in a file by prepending
a pathname, like this:  "./:memory:".</p>

<p>The special ":memory:" filename also works when using <a href="uri.html">URI filenames</a>.
For example:

<blockquote><pre>
rc = sqlite3_open("file::memory:", &amp;db);
</pre></blockquote>

Or,

<blockquote><pre>
ATTACH DATABASE 'file::memory:' AS aux1;
</pre></blockquote>

<a name="sharedmemdb"></a>

<h2>In-memory Databases And Shared Cache</h2>

<p>In-memory databases are allowed to use <a href="sharedcache.html">shared cache</a> if they are
opened using a <a href="uri.html">URI filename</a>.  If the unadorned ":memory:" name is used
to specify the in-memory database, then that database always has a private
cache and is only visible to the database connection that originally
opened it.  However, the same in-memory database can be opened by two or
more database connections as follows:

<blockquote><pre>
rc = sqlite3_open("file::memory:?cache=shared", &amp;db);
</pre></blockquote>

Or,

<blockquote><pre>
ATTACH DATABASE 'file::memory:?cache=shared' AS aux1;
</pre></blockquote>

<p>This allows separate database connections to share the same
in-memory database.  Of course, all database connections sharing the
in-memory database need to be in the same process.  The database is
automatically deleted and memory is reclaimed when the last connection
to the database closes.

<p>If two or more distinct but shareable in-memory databases are needed
in a single process, then the <a href="uri.html#coreqp">mode=memory</a> query parameter can
be used with a <a href="uri.html">URI filename</a> to create a named in-memory database:

<blockquote><pre>
rc = sqlite3_open("file:memdb1?mode=memory&amp;cache=shared", &amp;db);
</pre></blockquote>

Or,

<blockquote><pre>
ATTACH DATABASE 'file:memdb1?mode=memory&amp;cache=shared' AS aux1;
</pre></blockquote>

<p>When an in-memory database is named in this way, it will only share its
cache with another connection that uses exactly the same name.



<a name="temp_db"></a>

<h2>Temporary Databases</h2>

<p>When the name of the database file handed to <a href="c3ref/open.html">sqlite3_open()</a> or to
<a href="lang_attach.html">ATTACH</a> is an empty string, then a new temporary file is created to hold
the database.</p>

<blockquote><pre>
rc = sqlite3_open("", &amp;db);
</pre></blockquote>

<blockquote><pre>
ATTACH DATABASE '' AS aux2;
</pre></blockquote>

<p>A different temporary file is created each time so that, just as
with the special ":memory:" string, two database connections to temporary
databases each have their own private database.  Temporary databases are
automatically deleted when the connection that created them closes.</p>

<p>Even though a disk file is allocated for each temporary database, in
practice the temporary database usually resides in the in-memory pager cache
and hence there is very little difference between a pure in-memory database
created by ":memory:" and a temporary database created by an empty filename.
The sole difference is that a ":memory:" database must remain in memory
at all times whereas parts of a temporary database might be flushed to disk
if the database becomes large or if SQLite comes under memory pressure.</p>

<p>The previous paragraphs describe the behavior of temporary databases
under the default SQLite configuration.  An application can use the
<a href="pragma.html#pragma_temp_store">temp_store pragma</a> and the <a href="compile.html#temp_store">SQLITE_TEMP_STORE</a> compile-time parameter to
force temporary databases to behave as pure in-memory databases, if desired.
</p>
<p align="center"><small><i>This page last modified on  <a href="https://sqlite.org/docsrc/honeypot" id="mtimelink"  data-href="https://sqlite.org/docsrc/finfo/pages/inmemorydb.in?m=2e26d2c7a8">2022-04-18 02:55:50</a> UTC </small></i></p>