slatedb 0.4.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ea58f5cc108fef4066004dce3db7641d979589c6afa56023845b4e568198630
-  data.tar.gz: c5e52bded1c840e6d51ba420b673c5f03e3f9450dd78476dc129a45cab02b11b
+  metadata.gz: dd1077018f7a8738545fc60b626a0e51d3240ae4141d9616787bf642489a22bc
+  data.tar.gz: 7aea1d1d0f9e1e3ee349d742246b7f89353ab8af39a6aca12d3167d7064d9023
 SHA512:
-  metadata.gz: 715e35df65d25a1487f648718ec72e593fed5e22289f47c2017aa8eac24ccda5d5df00151ec618b1d732550be2f8b6ac5d8136b9358d18c197ae11b5e437e8a9
-  data.tar.gz: 92780ae93284906f92a4e4550d885c281af32f7cd1f91642e6ca9ebbe1f114d574d20a17be3f0605b5caaaafe64e27e70f12a96b5fcc6255fd8f0e210f0fa9b1
+  metadata.gz: 2fcbdc5f116120c4d06bb857407047505a5ca5c526a9c8209cb06411635adc506b9a634024db9152c23f5b98f46d9600d2cf21d4826cf5a947b335cb72449eb2
+  data.tar.gz: e40b8fde694ca637e5ab80d529e161eefe8901cf478a768ebbc2ddd35b9cc16f42e8858feb4cd149333e7e3db6f4ee977770485390c56303ba8dba3fd88803ff

data/README.md

@@ -561,8 +561,19 @@ admin.run_gc(min_age: 3600_000)                 # Set min age for all directorie
 admin.run_gc(manifest_min_age: 86400_000)       # Custom age for manifest (1 day)
 admin.run_gc(wal_min_age: 60_000)               # Custom age for WAL (1 minute)
 admin.run_gc(compacted_min_age: 60_000)         # Custom age for compacted (1 minute)
+
+# Delete a database (SlateDB >= 0.16.0)
+would_delete = admin.delete_db                  # Dry run: returns the object paths
+                                                # that *would* be deleted, deleting nothing
+deleted = admin.delete_db(confirm: true)        # Actually delete; returns the removed paths
 ```
 
+`delete_db` is idempotent, and a confirmed delete of a directory that is not a
+SlateDB database (no manifest and no in-progress deletion marker) is refused, so
+a mistyped path cannot wipe an unrelated directory. For a cloned database, any
+checkpoints it pinned in parent databases are stripped before its own objects
+are removed.
+
 ### Flushing
 
 Ensure all writes are persisted:
@@ -572,6 +583,26 @@ db.put("key", "value")
 db.flush
 ```
 
+By default, `flush` flushes the write-ahead log (WAL) if enabled, otherwise the
+memtable. You can choose explicitly with `flush_type:` (SlateDB >= 0.16.0):
+
+```ruby
+db.flush(flush_type: :wal)       # Flush the write-ahead log
+db.flush(flush_type: :memtable)  # Freeze and flush memtable entries to object storage
+```
+
+### Closing
+
+Closing flushes the active memtable first by default, so durable writes are not
+lost. You can control the final flush when closing (SlateDB >= 0.16.0):
+
+```ruby
+db.close                       # Flush the memtable, then close (default)
+db.close(flush_type: :wal)     # Flush the WAL before closing
+db.close(flush: false)         # Close without a final flush; writes that are not
+                               # yet durable may be lost
+```
+
 ## Thread Safety
 
 **SlateDB is fully thread-safe and optimized for concurrent access.**

data/ext/slatedb/Cargo.toml

@@ -11,7 +11,7 @@ name = "slatedb"
 crate-type = ["cdylib"]
 
 [dependencies]
-slatedb = "0.15.0"
+slatedb = "0.16.0"
 magnus = { version = "0.8.2", features = ["rb-sys"] }
 rb-sys = { version = "0.9.128", features = ["stable-api-compiled-fallback"] }
 tokio = { version = "1.52.3", features = ["rt-multi-thread", "sync"] }

data/ext/slatedb/src/admin.rs

@@ -265,6 +265,26 @@ impl Admin {
 
         Ok(())
     }
+
+    /// Delete a database, stripping any checkpoints it pinned in parent
+    /// databases (for clones) before removing its own objects (SlateDB >= 0.16.0).
+    ///
+    /// # Arguments
+    /// * `confirm` - When `false` (the default), performs a dry run and returns
+    ///   the list of object paths that *would* be deleted without touching
+    ///   anything. When `true`, actually deletes and returns the object paths
+    ///   that were removed.
+    ///
+    /// A `confirm` delete of a directory with neither a manifest nor a leftover
+    /// `.deleting` marker is refused, so an incorrect path cannot wipe an
+    /// unrelated directory. The operation is idempotent.
+    ///
+    /// # Returns
+    /// An array of object paths (deleted, or that would be deleted for a dry run).
+    pub fn delete_db(&self, confirm: bool) -> Result<Vec<String>, Error> {
+        let deleted = block_on_result(async { self.inner.delete_db(confirm).await })?;
+        Ok(deleted)
+    }
 }
 
 /// Define the Admin class on the SlateDb module.
@@ -282,6 +302,7 @@ pub fn define_admin_class(ruby: &Ruby, module: &magnus::RModule) -> Result<(), E
     class.define_method("_refresh_checkpoint", method!(Admin::refresh_checkpoint, 2))?;
     class.define_method("_delete_checkpoint", method!(Admin::delete_checkpoint, 1))?;
     class.define_method("_run_gc", method!(Admin::run_gc, 1))?;
+    class.define_method("_delete_db", method!(Admin::delete_db, 1))?;
 
     Ok(())
 }

data/ext/slatedb/src/database.rs

@@ -4,7 +4,8 @@ use std::sync::{Arc, Mutex};
 use magnus::prelude::*;
 use magnus::{function, method, Error, RHash, Ruby};
 use slatedb::config::{
-    DurabilityLevel, MergeOptions, PutOptions, ReadOptions, ScanOptions, Ttl, WriteOptions,
+    CloseOptions, DurabilityLevel, FlushOptions, FlushType, MergeOptions, PutOptions, ReadOptions,
+    ScanOptions, Ttl, WriteOptions,
 };
 use slatedb::object_store::memory::InMemory;
 use slatedb::{Db, IsolationLevel, IterationOrder, KeyValue};
@@ -79,13 +80,32 @@ impl Database {
     }
 
     fn write_options_from_kwargs(kwargs: &RHash) -> Result<WriteOptions, Error> {
-        let await_durable = get_optional::<bool>(kwargs, "await_durable")?.unwrap_or(true);
         let seqnum = get_optional::<u64>(kwargs, "seqnum")?.unwrap_or(0);
 
-        Ok(WriteOptions {
-            await_durable,
-            seqnum,
-        })
+        Ok(WriteOptions { seqnum })
+    }
+
+    /// Parse the `await_durable` keyword argument (defaults to `true`).
+    ///
+    /// As of SlateDB 0.16.0, `await_durable` is no longer a `WriteOptions`
+    /// field. Write methods return immediately after updating the in-memory
+    /// WAL/MemTable and hand back a `WriteHandle`; blocking until the write is
+    /// durable in object storage is done by awaiting that handle. This helper
+    /// preserves the previous ergonomic `await_durable:` behavior for callers.
+    fn await_durable_from_kwargs(kwargs: &RHash) -> Result<bool, Error> {
+        Ok(get_optional::<bool>(kwargs, "await_durable")?.unwrap_or(true))
+    }
+
+    /// Parse a `flush_type` name into a SlateDB `FlushType` (SlateDB >= 0.16.0).
+    fn parse_flush_type(name: &str) -> Result<FlushType, Error> {
+        match name {
+            "wal" => Ok(FlushType::Wal),
+            "memtable" | "mem_table" => Ok(FlushType::MemTable),
+            other => Err(invalid_argument_error(&format!(
+                "invalid flush_type: {} (expected 'wal' or 'memtable')",
+                other
+            ))),
+        }
     }
 
     /// Open a database at the given path.
@@ -249,16 +269,14 @@ impl Database {
         }
 
         let put_opts = PutOptions { ttl: Ttl::Default };
-
-        let write_opts = WriteOptions {
-            await_durable: true,
-            seqnum: 0,
-        };
+        let write_opts = WriteOptions::default();
 
         block_on_result(async {
-            self.inner
+            let handle = self
+                .inner
                 .put_with_options(key.as_bytes(), value.as_bytes(), &put_opts, &write_opts)
-                .await
+                .await?;
+            handle.await_durable().await
         })?;
         self.increment_metric("db.put.count");
 
@@ -280,18 +298,23 @@ impl Database {
         let ttl = get_optional::<u64>(&kwargs, "ttl")?;
         let put_opts = PutOptions {
             ttl: match ttl {
-                Some(ms) => Ttl::ExpireAfter(ms),
+                Some(ms) => Ttl::ExpireAfterMillis(ms),
                 None => Ttl::Default,
             },
         };
 
-        // Parse await_durable
         let write_opts = Self::write_options_from_kwargs(&kwargs)?;
+        let await_durable = Self::await_durable_from_kwargs(&kwargs)?;
 
         block_on_result(async {
-            self.inner
+            let handle = self
+                .inner
                 .put_with_options(key.as_bytes(), value.as_bytes(), &put_opts, &write_opts)
-                .await
+                .await?;
+            if await_durable {
+                handle.await_durable().await?;
+            }
+            Ok(())
         })?;
         self.increment_metric("db.put_with_options.count");
 
@@ -307,15 +330,14 @@ impl Database {
             return Err(invalid_argument_error("key cannot be empty"));
         }
 
-        let write_opts = WriteOptions {
-            await_durable: true,
-            seqnum: 0,
-        };
+        let write_opts = WriteOptions::default();
 
         block_on_result(async {
-            self.inner
+            let handle = self
+                .inner
                 .delete_with_options(key.as_bytes(), &write_opts)
-                .await
+                .await?;
+            handle.await_durable().await
         })?;
         self.increment_metric("db.delete.count");
 
@@ -333,11 +355,17 @@ impl Database {
         }
 
         let write_opts = Self::write_options_from_kwargs(&kwargs)?;
+        let await_durable = Self::await_durable_from_kwargs(&kwargs)?;
 
         block_on_result(async {
-            self.inner
+            let handle = self
+                .inner
                 .delete_with_options(key.as_bytes(), &write_opts)
-                .await
+                .await?;
+            if await_durable {
+                handle.await_durable().await?;
+            }
+            Ok(())
         })?;
         self.increment_metric("db.delete_with_options.count");
 
@@ -550,7 +578,10 @@ impl Database {
     /// * `batch` - The WriteBatch to write
     pub fn write(&self, batch: &WriteBatch) -> Result<(), Error> {
         let batch_inner = batch.take()?;
-        block_on_result(async { self.inner.write(batch_inner).await })?;
+        block_on_result(async {
+            let handle = self.inner.write(batch_inner).await?;
+            handle.await_durable().await
+        })?;
         Ok(())
     }
 
@@ -561,13 +592,19 @@ impl Database {
     /// * `kwargs` - Keyword arguments (await_durable, seqnum)
     pub fn write_with_options(&self, batch: &WriteBatch, kwargs: RHash) -> Result<(), Error> {
         let write_opts = Self::write_options_from_kwargs(&kwargs)?;
+        let await_durable = Self::await_durable_from_kwargs(&kwargs)?;
 
         let batch_inner = batch.take()?;
 
         block_on_result(async {
-            self.inner
+            let handle = self
+                .inner
                 .write_with_options(batch_inner, &write_opts)
-                .await
+                .await?;
+            if await_durable {
+                handle.await_durable().await?;
+            }
+            Ok(())
         })?;
 
         Ok(())
@@ -584,16 +621,14 @@ impl Database {
         }
 
         let merge_opts = MergeOptions { ttl: Ttl::Default };
-
-        let write_opts = WriteOptions {
-            await_durable: true,
-            seqnum: 0,
-        };
+        let write_opts = WriteOptions::default();
 
         block_on_result(async {
-            self.inner
+            let handle = self
+                .inner
                 .merge_with_options(key.as_bytes(), value.as_bytes(), &merge_opts, &write_opts)
-                .await
+                .await?;
+            handle.await_durable().await
         })?;
 
         Ok(())
@@ -618,17 +653,23 @@ impl Database {
         let ttl = get_optional::<u64>(&kwargs, "ttl")?;
         let merge_opts = MergeOptions {
             ttl: match ttl {
-                Some(ms) => Ttl::ExpireAfter(ms),
+                Some(ms) => Ttl::ExpireAfterMillis(ms),
                 None => Ttl::Default,
             },
         };
 
         let write_opts = Self::write_options_from_kwargs(&kwargs)?;
+        let await_durable = Self::await_durable_from_kwargs(&kwargs)?;
 
         block_on_result(async {
-            self.inner
+            let handle = self
+                .inner
                 .merge_with_options(key.as_bytes(), value.as_bytes(), &merge_opts, &write_opts)
-                .await
+                .await?;
+            if await_durable {
+                handle.await_durable().await?;
+            }
+            Ok(())
         })?;
 
         Ok(())
@@ -708,6 +749,19 @@ impl Database {
         Ok(())
     }
 
+    /// Flush the database, choosing the flush type (SlateDB >= 0.16.0).
+    ///
+    /// # Arguments
+    /// * `flush_type` - "wal" to flush the WAL, or "memtable" to freeze and
+    ///   flush memtable entries to object storage.
+    pub fn flush_with_options(&self, flush_type: String) -> Result<(), Error> {
+        let options = FlushOptions {
+            flush_type: Self::parse_flush_type(&flush_type)?,
+        };
+        block_on_result(async { self.inner.flush_with_options(options).await })?;
+        Ok(())
+    }
+
     /// Return the database metrics registry.
     pub fn metrics(&self) -> Result<Metrics, Error> {
         Ok(Metrics::new(self.metrics.clone()))
@@ -718,6 +772,22 @@ impl Database {
         block_on_result(async { self.inner.close().await })?;
         Ok(())
     }
+
+    /// Close the database, controlling the final flush (SlateDB >= 0.16.0).
+    ///
+    /// # Arguments
+    /// * `flush_type` - `Some("wal"|"memtable")` to flush before closing, or
+    ///   `None` to close without a final flush (writes that are not yet durable
+    ///   may be lost).
+    pub fn close_with_options(&self, flush_type: Option<String>) -> Result<(), Error> {
+        let flush_type = match flush_type {
+            Some(name) => Some(Self::parse_flush_type(&name)?),
+            None => None,
+        };
+        let options = CloseOptions { flush_type };
+        block_on_result(async { self.inner.close_with_options(options).await })?;
+        Ok(())
+    }
 }
 
 /// Define the Database class on the SlateDb module.
@@ -772,9 +842,17 @@ pub fn define_database_class(ruby: &Ruby, module: &magnus::RModule) -> Result<()
         "_create_checkpoint",
         method!(Database::create_checkpoint, 1),
     )?;
-    class.define_method("flush", method!(Database::flush, 0))?;
+    class.define_method("_flush", method!(Database::flush, 0))?;
+    class.define_method(
+        "_flush_with_options",
+        method!(Database::flush_with_options, 1),
+    )?;
     class.define_method("_metrics", method!(Database::metrics, 0))?;
-    class.define_method("close", method!(Database::close, 0))?;
+    class.define_method("_close", method!(Database::close, 0))?;
+    class.define_method(
+        "_close_with_options",
+        method!(Database::close_with_options, 1),
+    )?;
 
     Ok(())
 }

data/ext/slatedb/src/transaction.rs

@@ -109,7 +109,7 @@ impl Transaction {
         let ttl = get_optional::<u64>(&kwargs, "ttl")?;
         let put_opts = PutOptions {
             ttl: match ttl {
-                Some(ms) => Ttl::ExpireAfter(ms),
+                Some(ms) => Ttl::ExpireAfterMillis(ms),
                 None => Ttl::Default,
             },
         };
@@ -172,7 +172,7 @@ impl Transaction {
         let ttl = get_optional::<u64>(&kwargs, "ttl")?;
         let merge_opts = MergeOptions {
             ttl: match ttl {
-                Some(ms) => Ttl::ExpireAfter(ms),
+                Some(ms) => Ttl::ExpireAfterMillis(ms),
                 None => Ttl::Default,
             },
         };
@@ -395,7 +395,16 @@ impl Transaction {
             .take()
             .ok_or_else(|| closed_error("transaction is closed"))?;
 
-        block_on_result(async { txn.commit().await })?;
+        block_on_result(async {
+            // As of SlateDB 0.16.0, commit returns as soon as the write is in
+            // memory and hands back an optional WriteHandle (None for an empty
+            // or read-only transaction). Await durability to preserve the
+            // previous blocking-commit behavior.
+            if let Some(handle) = txn.commit().await? {
+                handle.await_durable().await?;
+            }
+            Ok(())
+        })?;
         Ok(())
     }
 
@@ -403,10 +412,7 @@ impl Transaction {
     pub fn commit_with_options(&self, kwargs: RHash) -> Result<(), Error> {
         let await_durable = get_optional::<bool>(&kwargs, "await_durable")?.unwrap_or(true);
         let seqnum = get_optional::<u64>(&kwargs, "seqnum")?.unwrap_or(0);
-        let write_opts = WriteOptions {
-            await_durable,
-            seqnum,
-        };
+        let write_opts = WriteOptions { seqnum };
 
         let txn = self
             .inner
@@ -414,7 +420,14 @@ impl Transaction {
             .take()
             .ok_or_else(|| closed_error("transaction is closed"))?;
 
-        block_on_result(async { txn.commit_with_options(&write_opts).await })?;
+        block_on_result(async {
+            if let Some(handle) = txn.commit_with_options(&write_opts).await? {
+                if await_durable {
+                    handle.await_durable().await?;
+                }
+            }
+            Ok(())
+        })?;
         Ok(())
     }
 

data/ext/slatedb/src/write_batch.rs

@@ -49,7 +49,7 @@ impl WriteBatch {
         let ttl = get_optional::<u64>(&kwargs, "ttl")?;
         let put_opts = PutOptions {
             ttl: match ttl {
-                Some(ms) => Ttl::ExpireAfter(ms),
+                Some(ms) => Ttl::ExpireAfterMillis(ms),
                 None => Ttl::Default,
             },
         };
@@ -102,7 +102,7 @@ impl WriteBatch {
         let ttl = get_optional::<u64>(&kwargs, "ttl")?;
         let merge_opts = MergeOptions {
             ttl: match ttl {
-                Some(ms) => Ttl::ExpireAfter(ms),
+                Some(ms) => Ttl::ExpireAfterMillis(ms),
                 None => Ttl::Default,
             },
         };

data/lib/slatedb/admin.rb

@@ -118,5 +118,33 @@ module SlateDb
       opts[:min_age] = min_age if min_age
       _run_gc(opts)
     end
+
+    # Delete a database, removing its objects from the object store
+    # (SlateDB >= 0.16.0).
+    #
+    # For a cloned database, any checkpoints it pinned in parent databases are
+    # stripped before its own objects are removed.
+    #
+    # By default this performs a dry run: it returns the object paths that
+    # *would* be deleted without removing anything. Pass +confirm: true+ to
+    # actually delete. A confirmed delete of a directory that is not a SlateDB
+    # database (no manifest and no in-progress deletion marker) is refused, so a
+    # mistyped path cannot wipe an unrelated directory. The operation is
+    # idempotent.
+    #
+    # @param confirm [Boolean] When false (the default), performs a dry run and
+    #   returns the paths that would be deleted. When true, deletes and returns
+    #   the paths that were removed.
+    # @return [Array<String>] Object paths deleted (or that would be deleted)
+    #
+    # @example Preview what would be deleted
+    #   admin.delete_db.each { |path| puts path }
+    #
+    # @example Actually delete the database
+    #   deleted = admin.delete_db(confirm: true)
+    #
+    def delete_db(confirm: false)
+      _delete_db(confirm)
+    end
   end
 end

data/lib/slatedb/database.rb

@@ -506,5 +506,63 @@ module SlateDb
     def metrics
       _metrics
     end
+
+    # Flush in-memory writes to object storage.
+    #
+    # With no arguments this flushes pending writes durably, matching the
+    # previous behavior. Pass +flush_type+ to control what is flushed
+    # (SlateDB >= 0.16.0).
+    #
+    # @param flush_type [Symbol, String, nil] Which data to flush: :wal to flush
+    #   the write-ahead log, or :memtable to freeze and flush memtable entries
+    #   to object storage. When nil (the default), SlateDB flushes the WAL if
+    #   enabled, otherwise the memtable.
+    # @return [void]
+    #
+    # @example Flush pending writes
+    #   db.flush
+    #
+    # @example Explicitly flush the WAL
+    #   db.flush(flush_type: :wal)
+    #
+    def flush(flush_type: nil)
+      if flush_type.nil?
+        _flush
+      else
+        _flush_with_options(flush_type.to_s)
+      end
+    end
+
+    # Close the database.
+    #
+    # By default the active memtable is flushed before closing (matching the
+    # previous behavior). Pass +flush: false+ to close without a final flush,
+    # in which case writes that are not yet durable may be lost
+    # (SlateDB >= 0.16.0).
+    #
+    # @param flush [Boolean] Whether to flush before closing (default: true)
+    # @param flush_type [Symbol, String, nil] When flushing, which data to
+    #   flush: :wal or :memtable. Defaults to :memtable. Ignored when
+    #   +flush: false+.
+    # @return [void]
+    #
+    # @example Close (flushing the memtable first)
+    #   db.close
+    #
+    # @example Close without flushing
+    #   db.close(flush: false)
+    #
+    # @example Flush the WAL before closing
+    #   db.close(flush_type: :wal)
+    #
+    def close(flush: true, flush_type: nil)
+      if !flush
+        _close_with_options(nil)
+      elsif flush_type.nil?
+        _close
+      else
+        _close_with_options(flush_type.to_s)
+      end
+    end
   end
 end

data/lib/slatedb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SlateDb
-  VERSION = "0.4.4"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slatedb
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.5.0
 platform: ruby
 authors:
 - SlateDB Contributors
@@ -137,7 +137,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ruby bindings for SlateDB
 test_files: []