1// Package vfs wraps the C SQLite VFS API.
2package vfs
3
4import (
5 "context"
6 "io"
7
8 "github.com/tetratelabs/wazero/api"
9)
10
11// A VFS defines the interface between the SQLite core and the underlying operating system.
12//
13// Use sqlite3.ErrorCode or sqlite3.ExtendedErrorCode to return specific error codes to SQLite.
14//
15// https://sqlite.org/c3ref/vfs.html
16type VFS interface {
17 Open(name string, flags OpenFlag) (File, OpenFlag, error)
18 Delete(name string, syncDir bool) error
19 Access(name string, flags AccessFlag) (bool, error)
20 FullPathname(name string) (string, error)
21}
22
23// VFSFilename extends VFS with the ability to use Filename
24// objects for opening files.
25//
26// https://sqlite.org/c3ref/filename.html
27type VFSFilename interface {
28 VFS
29 OpenFilename(name *Filename, flags OpenFlag) (File, OpenFlag, error)
30}
31
32// A File represents an open file in the OS interface layer.
33//
34// Use sqlite3.ErrorCode or sqlite3.ExtendedErrorCode to return specific error codes to SQLite.
35// In particular, sqlite3.BUSY is necessary to correctly implement lock methods.
36//
37// https://sqlite.org/c3ref/io_methods.html
38type File interface {
39 Close() error
40 ReadAt(p []byte, off int64) (n int, err error)
41 WriteAt(p []byte, off int64) (n int, err error)
42 Truncate(size int64) error
43 Sync(flags SyncFlag) error
44 Size() (int64, error)
45 Lock(lock LockLevel) error
46 Unlock(lock LockLevel) error
47 CheckReservedLock() (bool, error)
48 SectorSize() int
49 DeviceCharacteristics() DeviceCharacteristic
50}
51
52// FileUnwrap should be implemented by a File
53// that wraps another File implementation.
54type FileUnwrap interface {
55 File
56 Unwrap() File
57}
58
59// FileLockState extends File to implement the
60// SQLITE_FCNTL_LOCKSTATE file control opcode.
61//
62// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntllockstate
63type FileLockState interface {
64 File
65 LockState() LockLevel
66}
67
68// FilePersistWAL extends File to implement the
69// SQLITE_FCNTL_PERSIST_WAL file control opcode.
70//
71// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpersistwal
72type FilePersistWAL interface {
73 File
74 PersistWAL() bool
75 SetPersistWAL(bool)
76}
77
78// FilePowersafeOverwrite extends File to implement the
79// SQLITE_FCNTL_POWERSAFE_OVERWRITE file control opcode.
80//
81// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpowersafeoverwrite
82type FilePowersafeOverwrite interface {
83 File
84 PowersafeOverwrite() bool
85 SetPowersafeOverwrite(bool)
86}
87
88// FileChunkSize extends File to implement the
89// SQLITE_FCNTL_CHUNK_SIZE file control opcode.
90//
91// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlchunksize
92type FileChunkSize interface {
93 File
94 ChunkSize(size int)
95}
96
97// FileSizeHint extends File to implement the
98// SQLITE_FCNTL_SIZE_HINT file control opcode.
99//
100// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlsizehint
101type FileSizeHint interface {
102 File
103 SizeHint(size int64) error
104}
105
106// FileHasMoved extends File to implement the
107// SQLITE_FCNTL_HAS_MOVED file control opcode.
108//
109// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlhasmoved
110type FileHasMoved interface {
111 File
112 HasMoved() (bool, error)
113}
114
115// FileOverwrite extends File to implement the
116// SQLITE_FCNTL_OVERWRITE file control opcode.
117//
118// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntloverwrite
119type FileOverwrite interface {
120 File
121 Overwrite() error
122}
123
124// FileSync extends File to implement the
125// SQLITE_FCNTL_SYNC file control opcode.
126//
127// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlsync
128type FileSync interface {
129 File
130 SyncSuper(super string) error
131}
132
133// FileCommitPhaseTwo extends File to implement the
134// SQLITE_FCNTL_COMMIT_PHASETWO file control opcode.
135//
136// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlcommitphasetwo
137type FileCommitPhaseTwo interface {
138 File
139 CommitPhaseTwo() error
140}
141
142// FileBatchAtomicWrite extends File to implement the
143// SQLITE_FCNTL_BEGIN_ATOMIC_WRITE, SQLITE_FCNTL_COMMIT_ATOMIC_WRITE
144// and SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE file control opcodes.
145//
146// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlbeginatomicwrite
147type FileBatchAtomicWrite interface {
148 File
149 BeginAtomicWrite() error
150 CommitAtomicWrite() error
151 RollbackAtomicWrite() error
152}
153
154// FileCheckpoint extends File to implement the
155// SQLITE_FCNTL_CKPT_START and SQLITE_FCNTL_CKPT_DONE
156// file control opcodes.
157//
158// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlckptstart
159type FileCheckpoint interface {
160 File
161 CheckpointStart()
162 CheckpointDone()
163}
164
165// FilePragma extends File to implement the
166// SQLITE_FCNTL_PRAGMA file control opcode.
167//
168// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpragma
169type FilePragma interface {
170 File
171 Pragma(name, value string) (string, error)
172}
173
174// FileBusyHandler extends File to implement the
175// SQLITE_FCNTL_BUSYHANDLER file control opcode.
176//
177// https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlbusyhandler
178type FileBusyHandler interface {
179 File
180 BusyHandler(func() bool)
181}
182
183// FileSharedMemory extends File to possibly implement
184// shared-memory for the WAL-index.
185// The same shared-memory instance must be returned
186// for the entire life of the file.
187// It's OK for SharedMemory to return nil.
188type FileSharedMemory interface {
189 File
190 SharedMemory() SharedMemory
191}
192
193// SharedMemory is a shared-memory WAL-index implementation.
194// Use [NewSharedMemory] to create a shared-memory.
195type SharedMemory interface {
196 shmMap(context.Context, api.Module, int32, int32, bool) (ptr_t, _ErrorCode)
197 shmLock(int32, int32, _ShmFlag) _ErrorCode
198 shmUnmap(bool)
199 shmBarrier()
200 io.Closer
201}
202
203type blockingSharedMemory interface {
204 SharedMemory
205 shmEnableBlocking(block bool)
206}
207
208type fileControl interface {
209 File
210 fileControl(ctx context.Context, mod api.Module, op _FcntlOpcode, pArg ptr_t) _ErrorCode
211}
212
213type filePDB interface {
214 File
215 SetDB(any)
216}