~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

<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Opening A New Database Connection</h2><blockquote><pre>int sqlite3_open(

121

const char *filename, /* Database filename (UTF-8) */

122

sqlite3 **ppDb /* OUT: SQLite db handle */

123

);

124

int sqlite3_open16(

125

const void *filename, /* Database filename (UTF-16) */

126

sqlite3 **ppDb /* OUT: SQLite db handle */

127

);

128

int sqlite3_open_v2(

129

const char *filename, /* Database filename (UTF-8) */

130

sqlite3 **ppDb, /* OUT: SQLite db handle */

131

int flags, /* Flags */

132

const char *zVfs /* Name of VFS module to use */

133

);

134

</pre></blockquote><p>

135

These routines open an SQLite database file as specified by the

136

filename argument. The filename argument is interpreted as UTF-8 for

137

sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte

138

order for sqlite3_open16(). A <a href="../c3ref/sqlite3.html">database connection</a> handle is usually

139

returned in *ppDb, even if an error occurs. The only exception is that

140

if SQLite is unable to allocate memory to hold the <a href="../c3ref/sqlite3.html">sqlite3</a> object,

141

a NULL will be written into *ppDb instead of a pointer to the <a href="../c3ref/sqlite3.html">sqlite3</a>

142

object. If the database is opened (and/or created) successfully, then

143

<a href="../c3ref/c_abort.html">SQLITE_OK</a> is returned. Otherwise an <a href="../c3ref/c_abort.html">error code</a> is returned. The

144

<a href="../c3ref/errcode.html">sqlite3_errmsg()</a> or <a href="../c3ref/errcode.html">sqlite3_errmsg16()</a> routines can be used to obtain

145

an English language description of the error following a failure of any

146

of the sqlite3_open() routines.</p>

147

148

<p>The default encoding for the database will be UTF-8 if

149

sqlite3_open() or sqlite3_open_v2() is called and

150

UTF-16 in the native byte order if sqlite3_open16() is used.</p>

151

152

<p>Whether or not an error occurs when it is opened, resources

153

associated with the <a href="../c3ref/sqlite3.html">database connection</a> handle should be released by

154

passing it to <a href="../c3ref/close.html">sqlite3_close()</a> when it is no longer required.</p>

155

156

<p>The sqlite3_open_v2() interface works like sqlite3_open()

157

except that it accepts two additional parameters for additional control

158

over the new database connection. The flags parameter to

159

sqlite3_open_v2() can take one of

160

the following three values, optionally combined with the

161

<a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOMUTEX</a>, <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_FULLMUTEX</a>, <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_SHAREDCACHE</a>,

162

<a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_PRIVATECACHE</a>, and/or <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a> flags:</p>

163

164

<p><dl>

165

<dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a></dt>

166

<dd>The database is opened in read-only mode. If the database does not

167

already exist, an error is returned.</dd></p>

168

169

<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a></dt>

170

<dd>The database is opened for reading and writing if possible, or reading

171

only if the file is write protected by the operating system. In either

172

case the database must already exist, otherwise an error is returned.</dd></p>

173

174

<p><dt><a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a> | <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_CREATE</a></dt>

175

<dd>The database is opened for reading and writing, and is created if

176

it does not already exist. This is the behavior that is always used for

177

sqlite3_open() and sqlite3_open16().</dd>

178

</dl></p>

179

180

<p>If the 3rd parameter to sqlite3_open_v2() is not one of the

181

combinations shown above optionally combined with other

182

<a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_* bits</a>

183

then the behavior is undefined.</p>

184

185

<p>If the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_NOMUTEX</a> flag is set, then the database connection

186

opens in the multi-thread <a href="../threadsafe.html">threading mode</a> as long as the single-thread

187

mode has not been set at compile-time or start-time. If the

188

<a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_FULLMUTEX</a> flag is set then the database connection opens

189

in the serialized <a href="../threadsafe.html">threading mode</a> unless single-thread was

190

previously selected at compile-time or start-time.

191

The <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_SHAREDCACHE</a> flag causes the database connection to be

192

eligible to use <a href="../sharedcache.html">shared cache mode</a>, regardless of whether or not shared

193

cache is enabled using <a href="../c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a>. The

194

<a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_PRIVATECACHE</a> flag causes the database connection to not

195

participate in <a href="../sharedcache.html">shared cache mode</a> even if it is enabled.</p>

196

197

<p>The fourth parameter to sqlite3_open_v2() is the name of the

198

<a href="../c3ref/vfs.html">sqlite3_vfs</a> object that defines the operating system interface that

199

the new database connection should use. If the fourth parameter is

200

a NULL pointer then the default <a href="../c3ref/vfs.html">sqlite3_vfs</a> object is used.</p>

201

202

<p>If the filename is ":memory:", then a private, temporary in-memory database

203

is created for the connection. This in-memory database will vanish when

204

the database connection is closed. Future versions of SQLite might

205

make use of additional special filenames that begin with the ":" character.

206

It is recommended that when a database filename actually does begin with

207

a ":" character you should prefix the filename with a pathname such as

208

"./" to avoid ambiguity.</p>

209

210

<p>If the filename is an empty string, then a private, temporary

211

on-disk database will be created. This private database will be

212

automatically deleted as soon as the database connection is closed.</p>

213

214

215

<h3>URI Filenames</h3></p>

216

217

<p>If <a href="../uri.html">URI filename</a> interpretation is enabled, and the filename argument

218

begins with "file:", then the filename is interpreted as a URI. URI

219

filename interpretation is enabled if the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a> flag is

220

set in the fourth argument to sqlite3_open_v2(), or if it has

221

been enabled globally using the <a href="../c3ref/c_config_getmalloc.html#sqliteconfiguri">SQLITE_CONFIG_URI</a> option with the

222

<a href="../c3ref/config.html">sqlite3_config()</a> method or by the <a href="../compile.html#use_uri">SQLITE_USE_URI</a> compile-time option.

223

As of SQLite version 3.7.7, URI filename interpretation is turned off

224

by default, but future releases of SQLite might enable URI filename

225

interpretation by default. See "<a href="../uri.html">URI filenames</a>" for additional

226

information.</p>

227

228

<p>URI filenames are parsed according to RFC 3986. If the URI contains an

229

authority, then it must be either an empty string or the string

230

"localhost". If the authority is not an empty string or "localhost", an

231

error is returned to the caller. The fragment component of a URI, if

232

present, is ignored.</p>

233

234

<p>SQLite uses the path component of the URI as the name of the disk file

235

which contains the database. If the path begins with a '/' character,

236

then it is interpreted as an absolute path. If the path does not begin

237

with a '/' (meaning that the authority section is omitted from the URI)

238

then the path is interpreted as a relative path.

239

On windows, the first component of an absolute path

240

is a drive specification (e.g. "C:").</p>

241

242

243

244

The query component of a URI may contain parameters that are interpreted

245

either by SQLite itself, or by a <a href="../vfs.html">custom VFS implementation</a>.

246

SQLite interprets the following three query parameters:</p>

247

248

<p><ul>

249

<li> <b>vfs</b>: The "vfs" parameter may be used to specify the name of

250

a VFS object that provides the operating system interface that should

251

be used to access the database file on disk. If this option is set to

252

an empty string the default VFS object is used. Specifying an unknown

253

VFS is an error. If sqlite3_open_v2() is used and the vfs option is

254

present, then the VFS specified by the option takes precedence over

255

the value passed as the fourth parameter to sqlite3_open_v2().</p>

256

257

<p><li> <b>mode</b>: The mode parameter may be set to either "ro", "rw",

258

"rwc", or "memory". Attempting to set it to any other value is

259

an error.

260

If "ro" is specified, then the database is opened for read-only

261

access, just as if the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a> flag had been set in the

262

third argument to sqlite3_prepare_v2(). If the mode option is set to

263

"rw", then the database is opened for read-write (but not create)

264

access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had

265

been set. Value "rwc" is equivalent to setting both

266

SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. If the mode option is

267

set to "memory" then a pure <a href="../inmemorydb.html">in-memory database</a> that never reads

268

or writes from disk is used. It is an error to specify a value for

269

the mode parameter that is less restrictive than that specified by

270

the flags passed in the third parameter to sqlite3_open_v2().</p>

271

272

<p><li> <b>cache</b>: The cache parameter may be set to either "shared" or

273

"private". Setting it to "shared" is equivalent to setting the

274

SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to

275

sqlite3_open_v2(). Setting the cache parameter to "private" is

276

equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.

277

If sqlite3_open_v2() is used and the "cache" parameter is present in

278

a URI filename, its value overrides any behaviour requested by setting

279

SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.

280

</ul></p>

281

282

<p>Specifying an unknown parameter in the query component of a URI is not an

283

error. Future versions of SQLite might understand additional query

284

parameters. See "<a href="../uri.html#coreqp">query parameters with special meaning to SQLite</a>" for

285

additional information.</p>

286

287

288

<h3>URI filename examples</h3></p>

289

290

291

<tr><th> URI filenames <th> Results

292

293

Open the file "data.db" in the current directory.

294

295

file:///home/fred/data.db <br>

296

file://localhost/home/fred/data.db <br> <td>

297

Open the database file "/home/fred/data.db".

298

<tr><td> file://darkstar/home/fred/data.db <td>

299

An error. "darkstar" is not a recognized authority.

300

301

file:///C:/Documents%20and%20Settings/fred/Desktop/data.db

302

<td> Windows only: Open the file "data.db" on fred's desktop on drive

303

C:. Note that the %20 escaping in this example is not strictly

304

necessary - space characters can be used literally

305

in URI filenames.

306

<tr><td> file:data.db?mode=ro&cache=private <td>

307

Open file "data.db" in the current directory for read-only access.

308

Regardless of whether or not shared-cache mode is enabled by

309

default, use a private cache.

310

<tr><td> file:/home/fred/data.db?vfs=unix-nolock <td>

311

Open file "/home/fred/data.db". Use the special VFS "unix-nolock".

312

<tr><td> file:data.db?mode=readonly <td>

313

An error. "readonly" is not a valid option for the "mode" parameter.

314

</table></p>

315

316

<p>URI hexadecimal escape sequences (%HH) are supported within the path and

317

query components of a URI. A hexadecimal escape sequence consists of a

318

percent sign - "%" - followed by exactly two hexadecimal digits

319

specifying an octet value. Before the path or query components of a

320

URI filename are interpreted, they are encoded using UTF-8 and all

321

hexadecimal escape sequences replaced by a single byte containing the

322

corresponding octet. If this process generates an invalid UTF-8 encoding,

323

the results are undefined.</p>

324

325

<p><b>Note to Windows users:</b> The encoding used for the filename argument

326

of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever

327

codepage is currently defined. Filenames containing international

328

characters must be converted to UTF-8 prior to passing them into

329

sqlite3_open() or sqlite3_open_v2().

330

</p><p>See also lists of

331

<a href="objlist.html">Objects</a>,

332

<a href="constlist.html">Constants</a>, and

333

<a href="funclist.html">Functions</a>.</p>