Opens or creates a database. Databases can be held in memory or on disk. You need read or write permissions to access the database, as it is stored on disk as a normal disk file.
DbName - a unique ID you choose to identify this database for all other operations on it (Eg. "db").
Filename - the file name on disk. The special filename ":memory:" opens an in-memory database. This can be used to manipulate data (or play with SQL) without actually writing to disk.
Warning - the SQLite documentation suggests that you choose one of:
Open_ReadOnly (1)
Open_ReadWrite (2) or
Open_ReadWrite + Open_Create (6)
If not, the behaviour of the open may be undefined.
Use DatabaseClose to close the database when you are finished with it.
If the database is still open when the world file is closed, the database is automatically closed.
It is not an error to re-open the same database ID of an existing, open, database, provided the disk file name is the same. This will be treated as a no-operation, so that triggers and aliases can open the database without having to check first if it was already open.
Note: Available in version 4.40 onwards.
Lua example
DatabaseOpen ("db", -- database ID
GetInfo (66) .. "mytestdb.sqlite", -- file name
6) -- flags
-- do stuff with the database here
DatabaseClose ("db") -- close it
Lua notes
The Flags parameter can be omitted, and defaults to 6 (Open_ReadWrite + Open_Create).
The return codes are available in the sqlite3 table in Lua, as follows:
sqlite3.OK = 0
sqlite3.INTEGER = 1
sqlite3.INTERNAL = 2
sqlite3.PERM = 3
sqlite3.ABORT = 4
sqlite3.BUSY = 5
sqlite3.LOCKED = 6
sqlite3.NOMEM = 7
sqlite3.READONLY = 8
sqlite3.INTERRUPT = 9
sqlite3.IOERR = 10
sqlite3.CORRUPT = 11
sqlite3.NOTFOUND = 12
sqlite3.FULL = 13
sqlite3.CANTOPEN = 14
sqlite3.PROTOCOL = 15
sqlite3.EMPTY = 16
sqlite3.SCHEMA = 17
sqlite3.TOOBIG = 18
sqlite3.CONSTRAINT = 19
sqlite3.MISMATCH = 20
sqlite3.MISUSE = 21
sqlite3.NOLFS = 22
sqlite3.FORMAT = 24
sqlite3.RANGE = 25
sqlite3.NOTADB = 26
sqlite3.ROW = 100
sqlite3.DONE = 101
Returns
0 : success
-6 : Database already exists under a different disk name
Otherwise, an SQLite error code, and the database ID cannot be used