Debian Codegraph @

www/shortnames.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="sqlite.css" rel="stylesheet">
6 <title>8+3 Filenames</title>
7 <!-- path= -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="index.html">
12 <img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='about.html'>About</a>
23 <li class='desktoponly'><a href="docs.html">Documentation</a>
24 <li class='desktoponly'><a href="download.html">Download</a>
25 <li class='wideonly'><a href='copyright.html'>License</a>
26 <li class='desktoponly'><a href="support.html">Support</a>
27 <li class='desktoponly'><a href="prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='about.html'>About</a>
35 <li><a href='docs.html'>Documentation</a>
36 <li><a href='download.html'>Download</a>
37 <li><a href='support.html'>Support</a>
38 <li><a href='prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118
119
120
121 <h1 align="center">SQLite And 8+3 Filenames</h1>
122
123 <p>
124 The default configuration of SQLite assumes the underlying filesystem
125 supports long filenames.
126 </p>
127
128 <p>
129 SQLite does not impose any naming requirements on database files.
130 SQLite will happily work with a database file that has any filename extension
131 or with no extension at all.
132 When auxiliary files are needed for a <a href="lockingv3.html#rollback">rollback journal</a> or
133 a <a href="wal.html">write-ahead log</a> or for one of the other kinds of
134 <a href="tempfiles.html">temporary disk files</a>, then the name for the auxiliary file is normally
135 constructed by appending a suffix onto the end of the database file name.
136 For example, if the original database is call "<tt>app.db</tt>" then
137 the <a href="lockingv3.html#rollback">rollback journal</a> will be called "<tt>app.db-journal</tt>"
138 and the <a href="wal.html">write-ahead log</a> will be called "<tt>app.db-wal</tt>".
139 This approach to auxiliary file naming works great on systems that
140 support long filenames. But on systems that impose 8+3 filename
141 constraints, the auxiliary files do not fit the 8+3 format even though
142 the original database file does.
143 </p>
144
145
146 <h2>Changing Filesystems</h2>
147
148 <p>
149 The recommended fix for this problem is to select a different
150 filesystem. These days, there is a huge selection of high-performance,
151 reliable, patent-free filesystems that support long filenames.
152 Where possible, it is recommended that embedded devices use one
153 of these other filesystems. This will avoid compatibility issues
154 and the danger of
155 <a href="shortnames.html#db83corrupt">database corruption caused by inconsistent use of 8+3 filenames</a>.
156 </p>
157
158 <h2>Adjusting SQLite To Use 8+3 Filenames</h2>
159
160 <p>
161 Some devices are compelled to use an older filesystem with 8+3
162 filename restrictions for backwards compatibility, or due
163 to other non-technical factors. In such situations, SQLite can be
164 coerced into using auxiliary files that fit the 8+3 pattern as follows:
165 </p>
166
167 <ol>
168 <li><p>Compile the SQLite library with either the compile-time
169 options <a href="compile.html#enable_8_3_names">SQLITE_ENABLE_8_3_NAMES=1</a> or
170 <a href="compile.html#enable_8_3_names">SQLITE_ENABLE_8_3_NAMES=2</a>.
171 Support for 8+3 filenames is not included in SQLite by default
172 because it does introduce some overhead. The overhead is tiny,
173 but even so, we do not want to burden the billions of SQLite
174 applications that do not need 8+3 filename support.</p>
175
176 <li><p>If the <a href="compile.html#enable_8_3_names">SQLITE_ENABLE_8_3_NAMES=1</a> option
177 is used, then SQLite is capable of using 8+3 filenames but that
178 capability is disabled and must be enabled separately for each
179 database connection by using
180 <a href="uri.html">URI filenames</a> when <a href="c3ref/open.html">opening</a> or
181 <a href="lang_attach.html">ATTACH-ing</a> the database files and include the
182 "<tt>8_3_names=1</tt>" query parameter in the URI. If SQLite
183 is compiled with
184 <a href="compile.html#enable_8_3_names">SQLITE_ENABLE_8_3_NAMES=2</a> then
185 8+3 filenames are enabled by default and this step can be
186 skipped.</p>
187
188 <li><p>Make sure that database filenames follow the 8+3 filename
189 format and that they do not have an empty name or extension.
190 In other words, the database filename must contain between
191 1 and 8 characters in the base name and between 1 and 3 characters
192 in the extension. Blank extensions are not allowed.</p>
193 </ol>
194
195 <p>
196 When the steps above are used, SQLite will shorten filename extensions
197 by only using the last 3 characters of
198 the extension. Thus, for example, a file that would normally be called
199 "<tt>app.db-journal</tt>" is shortened to just "<tt>app.nal</tt>".
200 Similarly, "<tt>app.db-wal</tt>" will become "<tt>app.wal</tt>" and
201 "<tt>app.db-shm</tt>" becomes "<tt>app.shm</tt>".
202 </p>
203
204 <p>
205 Note that it is very important that the database filename have some kind
206 of extension. If there is no extension, then SQLite creates auxiliary
207 filenames by appending to the base name of the file. Thus, a database
208 named "<tt>db01</tt>" would have a <a href="lockingv3.html#rollback">rollback journal</a> file named
209 "<tt>db01-journal</tt>". And as this filename has no extension to shorten
210 to 3 characters, it will be used as-is, and will violate 8+3 naming rules.
211 </p>
212
213 <a name="db83corrupt"></a>
214
215 <h2>Database Corruption Warning</h2>
216
217 <p>
218 If a database file is accessed using 8+3 naming rather than the default
219 long filename, then it must be consistently accessed
220 using 8+3 naming by every database
221 connection every time it is opened, or else there is a risk of database
222 corruption.
223 The auxiliary <a href="lockingv3.html#rollback">rollback journal</a> and <a href="wal.html">write-ahead log</a> files are essential
224 to SQLite for being able to recover from a crash. If an application is
225 using 8+3 names and crashes, then the information needed to safely recover
226 from the crash is stored in files with the "<tt>.nal</tt>" or
227 "<tt>.wal</tt>" extension. If the next application to open the database
228 does not specify the "<tt>8_3_names=1</tt>" URI parameter, then SQLite
229 will use the long filenames to try to locate the rollback journal or
230 write-ahead log files. It will not find them, since they were saved using
231 8+3 names by the application that crashed, and hence the database will not
232 be properly recovered and will likely go corrupt.
233 </p>
234
235 <p>
236 Using a database file with 8+3 filenames in some cases while in
237 other cases using long filenames is equivalent to
238 <a href="howtocorrupt.html#delhotjrnl">deleting a hot journal</a>.
239 </p>
240 <p align="center"><small><i>This page was last updated on 2026-04-21 10:28:59Z </small></i></p>
241