quack_rs/file_system.rs
1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! File system access (`DuckDB` 1.5.0+).
7//!
8//! This module exposes `DuckDB`'s virtual file system (VFS) to extensions, so a
9//! custom table function, replacement scan, or copy function can read and write
10//! files through the *same* abstraction `DuckDB` uses internally. That means
11//! transparently honouring `httpfs` (`s3://`, `http://`), in-memory files, and
12//! any other registered file system — rather than reaching for `std::fs` and
13//! only ever seeing local disk.
14//!
15//! # Obtaining a [`FileSystem`]
16//!
17//! Get one from a [`ClientContext`] (which you can obtain from most function
18//! callbacks):
19//!
20//! ```rust,no_run
21//! use quack_rs::client_context::ClientContext;
22//! use quack_rs::file_system::{FileOpenOptions, FileSystem};
23//!
24//! # fn demo(ctx: &ClientContext) -> Option<()> {
25//! let fs = FileSystem::from_client_context(ctx)?;
26//! let opts = FileOpenOptions::read_only();
27//! let handle = fs.open(c"data.csv", &opts).ok()?;
28//! let mut contents = Vec::new();
29//! handle.read_to_end(&mut contents).ok()?;
30//! # Some(())
31//! # }
32//! ```
33
34use std::ffi::CStr;
35use std::marker::PhantomData;
36use std::os::raw::c_void;
37
38use libduckdb_sys::{
39 duckdb_client_context_get_file_system, duckdb_create_file_open_options,
40 duckdb_destroy_file_handle, duckdb_destroy_file_open_options, duckdb_destroy_file_system,
41 duckdb_file_flag, duckdb_file_flag_DUCKDB_FILE_FLAG_APPEND,
42 duckdb_file_flag_DUCKDB_FILE_FLAG_CREATE, duckdb_file_flag_DUCKDB_FILE_FLAG_CREATE_NEW,
43 duckdb_file_flag_DUCKDB_FILE_FLAG_READ, duckdb_file_flag_DUCKDB_FILE_FLAG_WRITE,
44 duckdb_file_handle, duckdb_file_handle_close, duckdb_file_handle_error_data,
45 duckdb_file_handle_read, duckdb_file_handle_seek, duckdb_file_handle_size,
46 duckdb_file_handle_sync, duckdb_file_handle_tell, duckdb_file_handle_write,
47 duckdb_file_open_options, duckdb_file_open_options_set_flag, duckdb_file_system,
48 duckdb_file_system_error_data, duckdb_file_system_open, DuckDBSuccess,
49};
50
51use crate::client_context::ClientContext;
52use crate::error_data::ErrorData;
53
54/// A file-open mode flag, mirroring `duckdb_file_flag`.
55#[derive(Debug, Clone, Copy, PartialEq, Eq)]
56#[non_exhaustive]
57pub enum FileFlag {
58 /// Open for reading.
59 Read,
60 /// Open for writing.
61 Write,
62 /// Create the file if it does not exist. Requires [`Write`][Self::Write].
63 Create,
64 /// Create the file, failing if it already exists. Requires
65 /// [`Write`][Self::Write].
66 ///
67 /// Setting it also sets [`Create`][Self::Create]: `DuckDB` maps it to
68 /// `FILE_FLAGS_EXCLUSIVE_CREATE`, which only means "fail if it exists" in
69 /// combination with `FILE_FLAGS_FILE_CREATE` (`O_EXCL` without `O_CREAT`
70 /// is ignored by `open(2)`), and on its own neither created a missing file
71 /// nor refused an existing one.
72 ///
73 /// # Windows: an existing file is not refused
74 ///
75 /// `DuckDB`'s local file system on Windows ignores the exclusive flag: it
76 /// opens with `OPEN_ALWAYS` whenever `Create` is set
77 /// (`LocalFileSystem::OpenFile` in `src/common/local_file_system.cpp`,
78 /// checked in `DuckDB` 1.5.5), so an existing file is opened, not
79 /// truncated, and no error is returned. A missing file is still created.
80 /// Do not rely on `CreateNew` for mutual exclusion on Windows.
81 CreateNew,
82 /// Open in append mode.
83 Append,
84}
85
86impl FileFlag {
87 /// Converts to the `DuckDB` C API constant.
88 #[must_use]
89 const fn to_raw(self) -> duckdb_file_flag {
90 match self {
91 Self::Read => duckdb_file_flag_DUCKDB_FILE_FLAG_READ,
92 Self::Write => duckdb_file_flag_DUCKDB_FILE_FLAG_WRITE,
93 Self::Create => duckdb_file_flag_DUCKDB_FILE_FLAG_CREATE,
94 Self::CreateNew => duckdb_file_flag_DUCKDB_FILE_FLAG_CREATE_NEW,
95 Self::Append => duckdb_file_flag_DUCKDB_FILE_FLAG_APPEND,
96 }
97 }
98}
99
100/// RAII wrapper for `duckdb_file_open_options`.
101///
102/// Describes how a file should be opened. Automatically destroyed when dropped.
103pub struct FileOpenOptions {
104 options: duckdb_file_open_options,
105}
106
107impl FileOpenOptions {
108 /// Creates an empty set of file-open options.
109 #[must_use]
110 pub fn new() -> Self {
111 // SAFETY: duckdb_create_file_open_options allocates an owned handle.
112 let options = unsafe { duckdb_create_file_open_options() };
113 Self { options }
114 }
115
116 /// Creates options configured for read-only access.
117 #[must_use]
118 pub fn read_only() -> Self {
119 let opts = Self::new();
120 opts.set_flag(FileFlag::Read, true);
121 opts
122 }
123
124 /// Creates options configured for writing, creating the file if needed.
125 #[must_use]
126 pub fn write_create() -> Self {
127 let opts = Self::new();
128 opts.set_flag(FileFlag::Write, true);
129 opts.set_flag(FileFlag::Create, true);
130 opts
131 }
132
133 /// Sets a file-open flag, returning `true` on success.
134 ///
135 /// Setting [`FileFlag::CreateNew`] also sets [`FileFlag::Create`]; see
136 /// there.
137 ///
138 /// # `value == false` does not clear a flag
139 ///
140 /// `duckdb_file_open_options_set_flag` ORs the flag in and ignores
141 /// `value` (`src/main/capi/file_system-c.cpp`), so a flag cannot be
142 /// unset once set. To change your mind, build a fresh `FileOpenOptions`.
143 pub fn set_flag(&self, flag: FileFlag, value: bool) -> bool {
144 if self.options.is_null() {
145 return false;
146 }
147 if flag == FileFlag::CreateNew && value && !self.set_flag(FileFlag::Create, true) {
148 return false;
149 }
150 // SAFETY: self.options is a valid duckdb_file_open_options.
151 let state =
152 unsafe { duckdb_file_open_options_set_flag(self.options, flag.to_raw(), value) };
153 state == DuckDBSuccess
154 }
155
156 /// Returns the raw handle without consuming the options.
157 #[inline]
158 #[must_use]
159 pub const fn as_raw(&self) -> duckdb_file_open_options {
160 self.options
161 }
162}
163
164impl Default for FileOpenOptions {
165 fn default() -> Self {
166 Self::new()
167 }
168}
169
170impl Drop for FileOpenOptions {
171 fn drop(&mut self) {
172 if !self.options.is_null() {
173 // SAFETY: self.options is a valid handle that we own.
174 unsafe { duckdb_destroy_file_open_options(&raw mut self.options) };
175 }
176 }
177}
178
179/// RAII wrapper for a `duckdb_file_system`.
180///
181/// Automatically destroyed when dropped.
182///
183/// # Lifetime
184///
185/// `duckdb_client_context_get_file_system` does not hand out an owned file
186/// system: its wrapper holds a *reference* to the connection's client file
187/// system, which the connection's `ClientContext` owns and frees when the
188/// connection closes. Using the handle after that is a heap use-after-free, so
189/// a `FileSystem` borrows the [`ClientContext`] it came from for `'ctx`.
190///
191/// ```rust,compile_fail,E0505
192/// use quack_rs::client_context::ClientContext;
193/// use quack_rs::file_system::{FileOpenOptions, FileSystem};
194///
195/// fn demo(ctx: ClientContext) {
196/// let fs = FileSystem::from_client_context(&ctx).unwrap();
197/// drop(ctx); // error[E0505]: cannot move out of `ctx` because it is borrowed
198/// let _ = fs.open(c"data.csv", &FileOpenOptions::read_only());
199/// }
200/// ```
201///
202/// [`FileHandle`]s opened through it borrow it in turn, so a handle cannot
203/// outlive the file system, the client context, or — through the context's
204/// contract — the connection and database behind them.
205pub struct FileSystem<'ctx> {
206 fs: duckdb_file_system,
207 _context: PhantomData<&'ctx ClientContext>,
208}
209
210impl<'ctx> FileSystem<'ctx> {
211 /// Obtains the file system associated with a [`ClientContext`].
212 ///
213 /// The result borrows `context`; see the type-level docs for why.
214 ///
215 /// Returns `None` if `DuckDB` does not provide one.
216 #[must_use]
217 pub fn from_client_context(context: &'ctx ClientContext) -> Option<Self> {
218 // SAFETY: context.as_raw() is a valid duckdb_client_context.
219 let fs = unsafe { duckdb_client_context_get_file_system(context.as_raw()) };
220 if fs.is_null() {
221 None
222 } else {
223 Some(Self {
224 fs,
225 _context: PhantomData,
226 })
227 }
228 }
229
230 /// Wraps a raw `duckdb_file_system` handle, taking ownership.
231 ///
232 /// # Safety
233 ///
234 /// `fs` must be a valid, non-null `duckdb_file_system` handle that the caller
235 /// no longer manages, and the connection whose client context it was
236 /// obtained from must stay open for all of `'ctx` — the handle refers to
237 /// that connection's file system, which is freed when it closes.
238 #[inline]
239 #[must_use]
240 pub const unsafe fn from_raw(fs: duckdb_file_system) -> Self {
241 Self {
242 fs,
243 _context: PhantomData,
244 }
245 }
246
247 /// Returns the raw handle.
248 #[inline]
249 #[must_use]
250 pub const fn as_raw(&self) -> duckdb_file_system {
251 self.fs
252 }
253
254 /// Opens `path` with the given `options`.
255 ///
256 /// The handle borrows this file system; see [`FileHandle`].
257 ///
258 /// # Errors
259 ///
260 /// Returns the structured [`ErrorData`] if the file cannot be opened.
261 pub fn open(
262 &self,
263 path: &CStr,
264 options: &FileOpenOptions,
265 ) -> Result<FileHandle<'_>, ErrorData> {
266 let mut handle: duckdb_file_handle = std::ptr::null_mut();
267 // SAFETY: self.fs, path, and options.as_raw() are all valid; handle is a
268 // valid out-pointer.
269 let state = unsafe {
270 duckdb_file_system_open(self.fs, path.as_ptr(), options.as_raw(), &raw mut handle)
271 };
272 if state == DuckDBSuccess && !handle.is_null() {
273 // SAFETY: open succeeded, so handle is a valid owned file handle.
274 Ok(unsafe { FileHandle::from_raw(handle) })
275 } else {
276 Err(self.error_data())
277 }
278 }
279
280 /// Returns the structured error from the most recent failed operation.
281 #[must_use]
282 pub fn error_data(&self) -> ErrorData {
283 // SAFETY: self.fs is valid; the call returns an owned error data handle.
284 let raw = unsafe { duckdb_file_system_error_data(self.fs) };
285 // SAFETY: raw is an owned duckdb_error_data (possibly null).
286 unsafe { ErrorData::from_raw(raw) }
287 }
288}
289
290impl Drop for FileSystem<'_> {
291 fn drop(&mut self) {
292 if !self.fs.is_null() {
293 // SAFETY: self.fs is a valid handle that we own.
294 unsafe { duckdb_destroy_file_system(&raw mut self.fs) };
295 }
296 }
297}
298
299/// Buffer growth step for [`FileHandle::read_to_end`] when the handle cannot
300/// report a size — 64 KiB, matching the order of magnitude of `DuckDB`'s own
301/// file-read buffers.
302const CHUNK: usize = 64 * 1024;
303
304/// RAII wrapper for an open `duckdb_file_handle`.
305///
306/// Automatically closed and destroyed when dropped.
307///
308/// # Lifetime
309///
310/// A handle refers to the database's underlying file system: once the
311/// database is closed (`duckdb_close` on the last reference), every method is
312/// a use-after-free — valgrind reports an invalid read in
313/// `duckdb::FileHandle::Read`. The handle therefore borrows the
314/// [`FileSystem`] that opened it for `'fs`, which in turn borrows the
315/// [`ClientContext`] whose contract keeps the connection (and so the
316/// database) open. Using a handle after its file system is gone does not
317/// compile:
318///
319/// ```rust,compile_fail,E0505
320/// use quack_rs::client_context::ClientContext;
321/// use quack_rs::file_system::{FileOpenOptions, FileSystem};
322///
323/// fn demo(ctx: &ClientContext) {
324/// let fs = FileSystem::from_client_context(ctx).unwrap();
325/// let handle = fs.open(c"data.csv", &FileOpenOptions::read_only()).unwrap();
326/// drop(fs); // error[E0505]: cannot move out of `fs` because it is borrowed
327/// let _ = handle.size();
328/// }
329/// ```
330///
331/// # Threads
332///
333/// A `FileHandle` is [`Send`]: it may be moved to, used on and dropped on
334/// another thread. It is not [`Sync`], so two threads cannot use one at
335/// the same time; share it behind a [`Mutex`](std::sync::Mutex). See the
336/// `unsafe impl Send` below for the reasoning.
337///
338/// ```rust,compile_fail
339/// fn assert_sync<T: Sync>() {}
340/// assert_sync::<quack_rs::file_system::FileHandle<'static>>();
341/// ```
342///
343/// # Keeping a file open across callbacks
344///
345/// A `COPY ... TO` writer opens its file in `global_init`, writes it in
346/// `sink` and closes it in `finalize`, so the handle has to live in the
347/// statement's global state, which is `'static` and shared by every sink
348/// thread. The borrow above cannot express that the state is destroyed while
349/// the statement — and so the connection and database — are still alive, so
350/// end it explicitly, once, and keep the handle in a `Mutex`:
351///
352/// ```rust,no_run
353/// use std::sync::Mutex;
354/// use quack_rs::copy_function::CopyGlobalInitInfo;
355/// use quack_rs::file_system::{FileHandle, FileOpenOptions, FileSystem};
356///
357/// struct Writer {
358/// file: Mutex<FileHandle<'static>>,
359/// }
360///
361/// # fn global_init(info: &CopyGlobalInitInfo) -> Result<(), String> {
362/// // SAFETY: the context is only used inside this callback.
363/// let ctx = unsafe { info.get_client_context() };
364/// let fs = FileSystem::from_client_context(&ctx).ok_or("no file system")?;
365/// // SAFETY: DuckDB copies the path out before the callback returns.
366/// let path = unsafe { info.get_file_path() }.map_err(|e| e.to_string())?;
367/// let path = std::ffi::CString::new(path).map_err(|e| e.to_string())?;
368/// let file = fs.open(&path, &FileOpenOptions::write_create()).map_err(|e| e.to_string())?;
369/// // SAFETY: the handle ends up in this statement's global state, which
370/// // DuckDB destroys before the statement finishes, while the connection and
371/// // the database it was opened against are still open.
372/// let file: FileHandle<'static> = unsafe { FileHandle::from_raw(file.into_raw()) };
373/// info.set_global_state_typed(Writer { file: Mutex::new(file) });
374/// # Ok(())
375/// # }
376/// ```
377///
378/// `sink` then reads it with `global_state_ref::<Writer>()` and locks the
379/// mutex to write; dropping the state closes the file.
380pub struct FileHandle<'fs> {
381 handle: duckdb_file_handle,
382 _file_system: PhantomData<&'fs ()>,
383}
384
385// SAFETY: a `duckdb_file_handle` is a heap `CFileHandle { ErrorData
386// error_data; unique_ptr<FileHandle> handle; }` (`file_system-c.cpp`,
387// byte-identical in 1.5.6 and 2.0.0), and nothing in it is tied to the thread
388// that created it: `duckdb::FileHandle` holds a reference to the database's
389// file system (one object shared by every connection and thread), the path
390// and the open flags, and a local file's `UnixFileHandle` adds only its file
391// descriptor and a position kept for logging (`local_file_system.cpp`). No
392// call in `file_system-c.cpp` reads thread-local state. Moving a handle to
393// another thread and using or dropping it there is therefore sound.
394// Concurrent use is not — every call writes `error_data` without
395// synchronisation, and `Read`/`Write` move one shared file position — so
396// `Sync` is not implemented. The `'fs` borrow is unaffected: a moved handle
397// still cannot outlive its file system. The live test
398// `a_file_handle_is_used_and_dropped_on_another_thread` opens a file on one
399// thread and writes, reads and drops it on another.
400unsafe impl Send for FileHandle<'_> {}
401
402impl FileHandle<'_> {
403 /// Wraps a raw `duckdb_file_handle`, taking ownership.
404 ///
405 /// # Safety
406 ///
407 /// `handle` must be a valid, non-null `duckdb_file_handle` that the caller no
408 /// longer manages, and the database it was opened against must stay open
409 /// for the whole of the lifetime the caller picks for the result.
410 #[inline]
411 #[must_use]
412 pub const unsafe fn from_raw(handle: duckdb_file_handle) -> Self {
413 Self {
414 handle,
415 _file_system: PhantomData,
416 }
417 }
418
419 /// Returns the raw handle.
420 #[inline]
421 #[must_use]
422 pub const fn as_raw(&self) -> duckdb_file_handle {
423 self.handle
424 }
425
426 /// Consumes the `FileHandle` and returns the raw handle without closing
427 /// it, the inverse of [`from_raw`][Self::from_raw].
428 ///
429 /// The caller takes over closing (`duckdb_file_handle_close`) and
430 /// destroying (`duckdb_destroy_file_handle`) it — or hands it back to
431 /// `from_raw`, which is how a handle is moved into state that outlives
432 /// this borrow (see [Keeping a file open across
433 /// callbacks](Self#keeping-a-file-open-across-callbacks)).
434 #[inline]
435 #[must_use]
436 pub const fn into_raw(self) -> duckdb_file_handle {
437 let raw = self.handle;
438 std::mem::forget(self);
439 raw
440 }
441
442 /// Reads up to `buf.len()` bytes into `buf`, returning the number of bytes
443 /// read (0 at end of file).
444 ///
445 /// # Errors
446 ///
447 /// Returns the structured [`ErrorData`] on read failure.
448 pub fn read(&self, buf: &mut [u8]) -> Result<usize, ErrorData> {
449 let size = i64::try_from(buf.len()).unwrap_or(i64::MAX);
450 // SAFETY: self.handle is valid; buf is writable for `size` bytes.
451 let n = unsafe {
452 duckdb_file_handle_read(self.handle, buf.as_mut_ptr().cast::<c_void>(), size)
453 };
454 if n < 0 {
455 Err(self.error_data())
456 } else {
457 Ok(usize::try_from(n).unwrap_or(0))
458 }
459 }
460
461 /// Writes up to `buf.len()` bytes from `buf`, returning the number written.
462 ///
463 /// # Errors
464 ///
465 /// Returns the structured [`ErrorData`] on write failure.
466 pub fn write(&self, buf: &[u8]) -> Result<usize, ErrorData> {
467 let size = i64::try_from(buf.len()).unwrap_or(i64::MAX);
468 // SAFETY: self.handle is valid; buf is readable for `size` bytes.
469 let n =
470 unsafe { duckdb_file_handle_write(self.handle, buf.as_ptr().cast::<c_void>(), size) };
471 if n < 0 {
472 Err(self.error_data())
473 } else {
474 Ok(usize::try_from(n).unwrap_or(0))
475 }
476 }
477
478 /// Reads exactly `buf.len()` bytes, or fails.
479 ///
480 /// `duckdb_file_handle_read` returns "the number of bytes **actually**
481 /// read", so a single `read` can come up short on any file system — and
482 /// `httpfs` is exactly where that happens. This loops until the buffer is
483 /// full.
484 ///
485 /// # Errors
486 ///
487 /// Returns the structured [`ErrorData`] on read failure, or a
488 /// [`DuckDbErrorType::Io`][crate::error_data::DuckDbErrorType::Io] error if
489 /// the file ends before `buf` is filled.
490 pub fn read_exact(&self, buf: &mut [u8]) -> Result<(), ErrorData> {
491 let mut filled = 0;
492 while filled < buf.len() {
493 let read = self.read(&mut buf[filled..])?;
494 if read == 0 {
495 return Err(ErrorData::new(
496 crate::error_data::DuckDbErrorType::Io,
497 &format!(
498 "unexpected end of file: wanted {} bytes, got {filled}",
499 buf.len()
500 ),
501 ));
502 }
503 filled += read;
504 }
505 Ok(())
506 }
507
508 /// Appends the rest of the file to `buf`, returning how many bytes were
509 /// added.
510 ///
511 /// Reads from the current position to end of file, looping over short reads.
512 ///
513 /// # Errors
514 ///
515 /// Returns the structured [`ErrorData`] on read failure.
516 pub fn read_to_end(&self, buf: &mut Vec<u8>) -> Result<usize, ErrorData> {
517 // Start from the remaining length when the handle can report it, so the
518 // common case is a single allocation, but never rely on it: a stream may
519 // report no size at all.
520 let remaining = match (self.size(), self.tell()) {
521 (Ok(size), Ok(position)) => size.saturating_sub(position),
522 _ => 0,
523 };
524 reserve_for_read(buf, remaining);
525
526 let start = buf.len();
527 loop {
528 let filled = buf.len();
529 buf.resize(filled + CHUNK, 0);
530 let read = match self.read(&mut buf[filled..]) {
531 Ok(read) => read,
532 Err(error) => {
533 buf.truncate(filled);
534 return Err(error);
535 }
536 };
537 buf.truncate(filled + read);
538 if read == 0 {
539 return Ok(buf.len() - start);
540 }
541 }
542 }
543
544 /// Writes all of `buf`, or fails.
545 ///
546 /// Like [`read_exact`][Self::read_exact], this exists because
547 /// `duckdb_file_handle_write` reports the number of bytes *actually*
548 /// written.
549 ///
550 /// # Errors
551 ///
552 /// Returns the structured [`ErrorData`] on write failure, or a
553 /// [`DuckDbErrorType::Io`][crate::error_data::DuckDbErrorType::Io] error if
554 /// `DuckDB` stops accepting bytes before the buffer is drained.
555 pub fn write_all(&self, buf: &[u8]) -> Result<(), ErrorData> {
556 let mut written = 0;
557 while written < buf.len() {
558 let n = self.write(&buf[written..])?;
559 if n == 0 {
560 return Err(ErrorData::new(
561 crate::error_data::DuckDbErrorType::Io,
562 &format!("write stalled: wanted {} bytes, wrote {written}", buf.len()),
563 ));
564 }
565 written += n;
566 }
567 Ok(())
568 }
569
570 /// Seeks to an absolute byte `position`.
571 ///
572 /// # Errors
573 ///
574 /// Returns the structured [`ErrorData`] if the seek fails, and an
575 /// `InvalidInput` error, without calling `DuckDB`, for a position past
576 /// `i64::MAX`, which `DuckDB`'s seek cannot take (it used to be clamped,
577 /// and a file system that accepts that offset returned `Ok`).
578 pub fn seek(&self, position: u64) -> Result<(), ErrorData> {
579 let Ok(pos) = i64::try_from(position) else {
580 return Err(ErrorData::new(
581 crate::error_data::DuckDbErrorType::InvalidInput,
582 &format!("FileHandle::seek: position {position} is past i64::MAX"),
583 ));
584 };
585 // SAFETY: self.handle is valid.
586 let state = unsafe { duckdb_file_handle_seek(self.handle, pos) };
587 self.check(state)
588 }
589
590 /// Returns the current byte offset within the file.
591 ///
592 /// # Errors
593 ///
594 /// Returns the structured [`ErrorData`] if `DuckDB` cannot report the
595 /// position. The C API signals that with a negative return value, which is
596 /// far too easy to clamp to zero by accident.
597 pub fn tell(&self) -> Result<u64, ErrorData> {
598 // SAFETY: self.handle is valid.
599 let position = unsafe { duckdb_file_handle_tell(self.handle) };
600 u64::try_from(position).map_err(|_| self.error_data())
601 }
602
603 /// Returns the total size of the file in bytes.
604 ///
605 /// # Errors
606 ///
607 /// Returns the structured [`ErrorData`] if `DuckDB` cannot report the size.
608 pub fn size(&self) -> Result<u64, ErrorData> {
609 // SAFETY: self.handle is valid.
610 let size = unsafe { duckdb_file_handle_size(self.handle) };
611 u64::try_from(size).map_err(|_| self.error_data())
612 }
613
614 /// Flushes buffered writes to durable storage.
615 ///
616 /// # Errors
617 ///
618 /// Returns the structured [`ErrorData`] if the sync fails.
619 pub fn sync(&self) -> Result<(), ErrorData> {
620 // SAFETY: self.handle is valid.
621 let state = unsafe { duckdb_file_handle_sync(self.handle) };
622 self.check(state)
623 }
624
625 /// Closes the file. The handle is still destroyed on drop.
626 ///
627 /// # Errors
628 ///
629 /// Returns the structured [`ErrorData`] if the close fails. Dropping the
630 /// handle then tries to close it once more, and leaks it if that fails
631 /// too: destroying it would retry the close where an exception aborts the
632 /// process.
633 pub fn close(&self) -> Result<(), ErrorData> {
634 // SAFETY: self.handle is valid.
635 let state = unsafe { duckdb_file_handle_close(self.handle) };
636 self.check(state)
637 }
638
639 /// Returns the structured error from the most recent failed operation.
640 #[must_use]
641 pub fn error_data(&self) -> ErrorData {
642 // SAFETY: self.handle is valid; the call returns an owned error data.
643 let raw = unsafe { duckdb_file_handle_error_data(self.handle) };
644 // SAFETY: raw is an owned duckdb_error_data (possibly null).
645 unsafe { ErrorData::from_raw(raw) }
646 }
647
648 /// Converts a `duckdb_state` into a `Result`, reading the handle's error
649 /// data on failure.
650 fn check(&self, state: libduckdb_sys::duckdb_state) -> Result<(), ErrorData> {
651 if state == DuckDBSuccess {
652 Ok(())
653 } else {
654 Err(self.error_data())
655 }
656 }
657}
658
659impl Drop for FileHandle<'_> {
660 fn drop(&mut self) {
661 if self.handle.is_null() {
662 return;
663 }
664 // `duckdb_destroy_file_handle` calls `Close()` outside any `try`
665 // (`file_system-c.cpp`), so a close that throws — possible for a
666 // handle from an extension's file system — would escape the C API
667 // and abort the process. `duckdb_file_handle_close` catches, so it
668 // closes first; destroy's second `Close()` is then a no-op for
669 // `DuckDB`'s own handles (`local_file_system.cpp`). If the close
670 // failed, destroy would retry it with no `try`, so the handle is
671 // leaked instead. Call [`close`][FileHandle::close] first to see
672 // the error.
673 // SAFETY: self.handle is a valid handle that we own.
674 let state = unsafe { duckdb_file_handle_close(self.handle) };
675 if state == DuckDBSuccess {
676 // SAFETY: as above; destroy nulls the handle.
677 unsafe { duckdb_destroy_file_handle(&raw mut self.handle) };
678 }
679 }
680}
681
682crate::debug_repr::impl_handle_debug!(FileOpenOptions.options);
683
684impl core::fmt::Debug for FileSystem<'_> {
685 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
686 f.debug_struct("FileSystem").field("fs", &self.fs).finish()
687 }
688}
689
690impl core::fmt::Debug for FileHandle<'_> {
691 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
692 f.debug_struct("FileHandle")
693 .field("handle", &self.handle)
694 .finish()
695 }
696}
697
698/// The most [`FileHandle::read_to_end`] reserves up front from the size the
699/// file reports; past it the buffer grows as data actually arrives.
700const MAX_READ_RESERVE: usize = 256 * 1024 * 1024;
701
702/// Reserves room for a read the file says is `remaining` bytes long.
703///
704/// The size is a hint, not a promise: a remote file system reports whatever
705/// the server's `Content-Length` says, and an infallible `reserve` of an
706/// impossible size aborts the whole process. So the hint is capped at
707/// [`MAX_READ_RESERVE`] and a failed reservation falls back to one chunk.
708fn reserve_for_read(buf: &mut Vec<u8>, remaining: u64) {
709 let hint = usize::try_from(remaining).unwrap_or(usize::MAX);
710 let wanted = hint.clamp(CHUNK, MAX_READ_RESERVE.max(CHUNK));
711 if buf.try_reserve(wanted).is_err() {
712 // Nothing reserved; the read loop grows the buffer one chunk at a time.
713 let _ = buf.try_reserve(CHUNK);
714 }
715}
716
717#[cfg(test)]
718mod tests {
719 use super::*;
720
721 /// A file reporting an impossible size must not abort the process: the
722 /// up-front reservation is capped, and a refused one is not fatal.
723 #[test]
724 fn reserve_for_read_caps_and_survives_an_impossible_size() {
725 let mut buf = Vec::new();
726 reserve_for_read(&mut buf, u64::MAX);
727 assert!(buf.capacity() >= CHUNK);
728 assert!(buf.capacity() <= MAX_READ_RESERVE * 2, "{}", buf.capacity());
729
730 let mut small = Vec::new();
731 reserve_for_read(&mut small, 10);
732 assert!(small.capacity() >= CHUNK, "at least one chunk");
733
734 let mut mid = Vec::new();
735 reserve_for_read(&mut mid, 1024 * 1024);
736 assert!(mid.capacity() >= 1024 * 1024, "the hint is used when sane");
737 }
738
739 #[test]
740 fn file_flag_distinct_raw_values() {
741 let flags = [
742 FileFlag::Read,
743 FileFlag::Write,
744 FileFlag::Create,
745 FileFlag::CreateNew,
746 FileFlag::Append,
747 ];
748 for (i, a) in flags.iter().enumerate() {
749 for b in flags.iter().skip(i + 1) {
750 assert_ne!(a.to_raw(), b.to_raw(), "{a:?} and {b:?} share a raw value");
751 }
752 }
753 }
754}