Merge branch 'main' into feat/partiql-delete-returning

Author: hicksy

CHANGELOG.md

@@ -14,6 +14,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - PartiQL now honours the `RETURNING` clause on `ExecuteStatement`, where dynoxide previously parsed the statement but silently dropped the clause. `DELETE ... RETURNING ALL OLD *` returns the deleted item in `Items` (a present but empty `Items` array on a missing target, matching DynamoDB rather than the classic `DeleteItem` path), and `UPDATE ... RETURNING <ALL|MODIFIED> <OLD|NEW> *` returns the matching projection of the item; the `MODIFIED` variants return only the changed paths (a nested `SET a.b` returns just the changed leaf, not the whole `a` attribute), exclude the primary key, and return an empty `Items` array when nothing was projected. `BatchExecuteStatement` honours a member's `RETURNING` clause; `ExecuteTransaction` rejects one with a top-level `ValidationException`. The `RETURNING` variants DynamoDB does not allow on `DELETE` (`MODIFIED OLD *`, `ALL NEW *`, `MODIFIED NEW *`) are rejected with its exact validation message instead of being ignored ([#137](https://github.com/nubo-db/dynoxide/issues/137)).
+### Added
+
+- `dynoxide serve` and `dynoxide` (no-subcommand) now accept a `--schema` flag, taking the same DynamoDB DescribeTable JSON format as `import --schema`. On startup, dynoxide creates each table defined in the file and skips any that already exist. This lets you pre-populate an empty database — in-memory or persistent — with the correct table structure without running an import first.
 
 ## [0.11.4] - 2026-07-17
 
@@ -423,4 +426,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [0.9.8]: https://github.com/nubo-db/dynoxide/compare/v0.9.7...v0.9.8
 [0.9.7]: https://github.com/nubo-db/dynoxide/compare/v0.9.6...v0.9.7
 [0.9.6]: https://github.com/nubo-db/dynoxide/compare/v0.9.5...v0.9.6
-[0.9.5]: https://github.com/nubo-db/dynoxide/releases/tag/v0.9.5
+[0.9.5]: https://github.com/nubo-db/dynoxide/releases/tag/v0.9.5

docs/http-server.md

@@ -26,6 +26,16 @@ dynoxide --db-path data.db --encryption-key-file key.hex
 DYNOXIDE_ENCRYPTION_KEY=$(cat key.hex) dynoxide --db-path data.db
 ```
 
+With tables pre-created from a schema:
+
+```sh
+# Generate schema
+aws dynamodb describe-table --table-name Users > schema.json
+
+# Start with schema
+dynoxide --schema schema.json --port 8000
+```
+
 Then use the AWS CLI or any DynamoDB SDK pointed at localhost:
 
 ```sh

src/import/mod.rs

@@ -101,6 +101,46 @@ pub struct TableImportResult {
     pub lines_skipped: usize,
 }
 
+/// Scaffold empty tables from a DynamoDB DescribeTable JSON schema file.
+///
+/// Reads the schema file, creates each table defined in it, and skips any
+/// tables that already exist. Returns the number of tables created.
+///
+/// The schema file format is identical to `import --schema`: a JSON file
+/// containing a single `aws dynamodb describe-table` response or an array
+/// of them.
+pub fn scaffold_from_schema(db: &Database, path: &std::path::Path) -> Result<usize, ImportError> {
+    let (schemas, schema_json) = schema::load_schemas(path).map_err(ImportError::Config)?;
+    let mut created = 0;
+    for table_schema in &schemas {
+        let create_request = build_create_request(&schema_json, &table_schema.table_name)?;
+        match db.create_table(create_request) {
+            Ok(_) => created += 1,
+            Err(crate::errors::DynoxideError::ResourceInUseException(_)) => {} // already exists
+            Err(e) => return Err(ImportError::Database(e.to_string())),
+        }
+    }
+    Ok(created)
+}
+
+/// Build a `CreateTableRequest` for `table_name` from raw schema JSON.
+///
+/// Deserializes through `CreateTableRequest`'s `Deserialize` impl (rather than
+/// building the struct by hand) so GlobalSecondaryIndexes and
+/// LocalSecondaryIndexes are picked up from the schema. Shared by `run_into`
+/// and `scaffold_from_schema` so the two can't drift apart on which fields a
+/// schema-sourced table ends up with.
+fn build_create_request(
+    schema_json: &serde_json::Value,
+    table_name: &str,
+) -> Result<crate::actions::create_table::CreateTableRequest, String> {
+    let table_json = find_table_json(schema_json, table_name)
+        .ok_or_else(|| format!("Schema JSON not found for table '{table_name}'"))?;
+
+    serde_json::from_value(table_json)
+        .map_err(|e| format!("Failed to deserialize schema for '{table_name}': {e}"))
+}
+
 /// Execute the import pipeline into a caller-provided database.
 ///
 /// This is the core import logic — database-agnostic. The caller is
@@ -166,13 +206,7 @@ pub fn run_into(db: &Database, cmd: ImportCommand) -> Result<ImportSummary, Impo
             )));
         }
 
-        // Find the matching schema JSON and deserialize into a fresh CreateTableRequest
-        let table_json = find_table_json(&schema_json, table_name)
-            .ok_or_else(|| format!("Schema JSON not found for table '{table_name}'"))?;
-
-        let create_request: crate::actions::create_table::CreateTableRequest =
-            serde_json::from_value(table_json)
-                .map_err(|e| format!("Failed to deserialize schema for '{}': {e}", table_name))?;
+        let create_request = build_create_request(&schema_json, table_name)?;
 
         db.create_table(create_request)
             .map_err(|e| format!("Failed to create table '{}': {e}", table_name))?;

src/main.rs

@@ -54,6 +54,11 @@ struct Cli {
     /// Path to file containing the encryption key (requires encryption feature)
     #[arg(long, value_name = "PATH")]
     encryption_key_file: Option<PathBuf>,
+
+    /// Schema file (JSON with DescribeTable responses) — scaffolds empty tables on startup
+    #[cfg(feature = "import")]
+    #[arg(long, value_name = "PATH")]
+    schema: Option<PathBuf>,
 }
 
 #[derive(Subcommand)]
@@ -133,6 +138,11 @@ struct ServeArgs {
     #[cfg(feature = "mcp-server")]
     #[arg(long, value_name = "HOST", requires = "mcp")]
     mcp_allowed_host: Vec<String>,
+
+    /// Schema file (JSON with DescribeTable responses) — scaffolds empty tables on startup
+    #[cfg(feature = "import")]
+    #[arg(long, value_name = "PATH")]
+    schema: Option<PathBuf>,
 }
 
 /// Arguments for the `healthcheck` subcommand.
@@ -404,6 +414,8 @@ async fn run() -> Result<(), Box<dyn std::error::Error>> {
                 mcp_no_auth: false,
                 #[cfg(feature = "mcp-server")]
                 mcp_allowed_host: Vec::new(),
+                #[cfg(feature = "import")]
+                schema: cli.schema,
             };
             run_serve(args).await
         }
@@ -477,6 +489,13 @@ async fn run_serve(args: ServeArgs) -> Result<(), Box<dyn std::error::Error>> {
         }
     })?;
 
+    #[cfg(feature = "import")]
+    if let Some(schema_path) = &args.schema {
+        let n = dynoxide::import::scaffold_from_schema(&db, schema_path)
+            .map_err(|e| -> Box<dyn std::error::Error> { e.into() })?;
+        eprintln!("Scaffolded {} table(s) from schema", n);
+    }
+
     #[cfg(feature = "mcp-server")]
     if args.mcp {
         use tokio_util::sync::CancellationToken;

tests/import.rs

@@ -460,6 +460,172 @@ fields = ["email"]
         );
     }
 
+    // ---------------------------------------------------------------------------
+    // scaffold_from_schema tests
+    // ---------------------------------------------------------------------------
+
+    #[test]
+    fn test_scaffold_creates_table() {
+        let tmp = tempfile::tempdir().unwrap();
+        let schema_file = tmp.path().join("schema.json");
+        create_schema_file(&schema_file, &[simple_table_schema("Users")]);
+
+        let db = dynoxide::Database::memory().unwrap();
+        let n = import::scaffold_from_schema(&db, &schema_file).unwrap();
+        assert_eq!(n, 1);
+
+        let tables = db
+            .list_tables(dynoxide::actions::list_tables::ListTablesRequest::default())
+            .unwrap();
+        assert_eq!(tables.table_names, vec!["Users"]);
+    }
+
+    #[test]
+    fn test_scaffold_multiple_tables() {
+        let tmp = tempfile::tempdir().unwrap();
+        let schema_file = tmp.path().join("schema.json");
+        create_schema_file(
+            &schema_file,
+            &[
+                simple_table_schema("Users"),
+                simple_table_schema("Orders"),
+                simple_table_schema("Products"),
+            ],
+        );
+
+        let db = dynoxide::Database::memory().unwrap();
+        let n = import::scaffold_from_schema(&db, &schema_file).unwrap();
+        assert_eq!(n, 3);
+
+        let mut tables = db
+            .list_tables(dynoxide::actions::list_tables::ListTablesRequest::default())
+            .unwrap()
+            .table_names;
+        tables.sort();
+        assert_eq!(tables, vec!["Orders", "Products", "Users"]);
+    }
+
+    #[test]
+    fn test_scaffold_skips_existing_tables() {
+        let tmp = tempfile::tempdir().unwrap();
+        let schema_file = tmp.path().join("schema.json");
+        create_schema_file(&schema_file, &[simple_table_schema("Users")]);
+
+        let db = dynoxide::Database::memory().unwrap();
+
+        // First call creates the table.
+        let n = import::scaffold_from_schema(&db, &schema_file).unwrap();
+        assert_eq!(n, 1);
+
+        // Second call should succeed and skip the already-existing table.
+        let n = import::scaffold_from_schema(&db, &schema_file).unwrap();
+        assert_eq!(n, 0);
+
+        // Still exactly one table.
+        let tables = db
+            .list_tables(dynoxide::actions::list_tables::ListTablesRequest::default())
+            .unwrap();
+        assert_eq!(tables.table_names.len(), 1);
+    }
+
+    #[test]
+    fn test_scaffold_with_gsi() {
+        let tmp = tempfile::tempdir().unwrap();
+        let schema_file = tmp.path().join("schema.json");
+        let schema = serde_json::json!({
+            "Table": {
+                "TableName": "Events",
+                "KeySchema": [
+                    {"AttributeName": "pk", "KeyType": "HASH"},
+                    {"AttributeName": "sk", "KeyType": "RANGE"}
+                ],
+                "AttributeDefinitions": [
+                    {"AttributeName": "pk", "AttributeType": "S"},
+                    {"AttributeName": "sk", "AttributeType": "S"},
+                    {"AttributeName": "gsi1pk", "AttributeType": "S"}
+                ],
+                "GlobalSecondaryIndexes": [{
+                    "IndexName": "gsi1",
+                    "KeySchema": [{"AttributeName": "gsi1pk", "KeyType": "HASH"}],
+                    "Projection": {"ProjectionType": "ALL"}
+                }]
+            }
+        });
+        create_schema_file(&schema_file, &[schema]);
+
+        let db = dynoxide::Database::memory().unwrap();
+        let n = import::scaffold_from_schema(&db, &schema_file).unwrap();
+        assert_eq!(n, 1);
+
+        let info = db
+            .describe_table(dynoxide::actions::describe_table::DescribeTableRequest {
+                table_name: "Events".to_string(),
+            })
+            .unwrap();
+        assert!(info.table.global_secondary_indexes.is_some());
+        assert_eq!(info.table.global_secondary_indexes.unwrap().len(), 1);
+    }
+
+    #[test]
+    fn test_scaffold_with_lsi() {
+        // `created_at` is used only by the LSI's sort key, not by the table's
+        // own key schema. A hand-parsed CreateTableRequest that drops
+        // LocalSecondaryIndexes leaves it orphaned and table creation fails.
+        let tmp = tempfile::tempdir().unwrap();
+        let schema_file = tmp.path().join("schema.json");
+        let schema = serde_json::json!({
+            "Table": {
+                "TableName": "Orders",
+                "KeySchema": [
+                    {"AttributeName": "pk", "KeyType": "HASH"},
+                    {"AttributeName": "sk", "KeyType": "RANGE"}
+                ],
+                "AttributeDefinitions": [
+                    {"AttributeName": "pk", "AttributeType": "S"},
+                    {"AttributeName": "sk", "AttributeType": "S"},
+                    {"AttributeName": "created_at", "AttributeType": "S"}
+                ],
+                "LocalSecondaryIndexes": [{
+                    "IndexName": "by-created-at",
+                    "KeySchema": [
+                        {"AttributeName": "pk", "KeyType": "HASH"},
+                        {"AttributeName": "created_at", "KeyType": "RANGE"}
+                    ],
+                    "Projection": {"ProjectionType": "ALL"}
+                }]
+            }
+        });
+        create_schema_file(&schema_file, &[schema]);
+
+        let db = dynoxide::Database::memory().unwrap();
+        let n = import::scaffold_from_schema(&db, &schema_file).unwrap();
+        assert_eq!(n, 1);
+
+        let info = db
+            .describe_table(dynoxide::actions::describe_table::DescribeTableRequest {
+                table_name: "Orders".to_string(),
+            })
+            .unwrap();
+        assert!(info.table.local_secondary_indexes.is_some());
+        assert_eq!(info.table.local_secondary_indexes.unwrap().len(), 1);
+    }
+
+    #[test]
+    fn test_scaffold_missing_file_errors() {
+        let db = dynoxide::Database::memory().unwrap();
+        let result = import::scaffold_from_schema(
+            &db,
+            std::path::Path::new("/tmp/dynoxide-nonexistent-schema-file.json"),
+        );
+        assert!(result.is_err());
+        assert!(
+            result
+                .unwrap_err()
+                .to_string()
+                .contains("Failed to read schema file")
+        );
+    }
+
     #[test]
     fn test_import_into_memory_database() {
         let tmp = tempfile::tempdir().unwrap();