Dynoxide

io.github.nubo-db由 GitHub 帳號 nubo-db 發布v1.6.0更新於 Nov 8, 2026

A DynamoDB emulator with an MCP server exposing 35 DynamoDB tools to coding agents.

已驗證STDIO僅桌面資料庫開發者工具

概覽

AI 產生的概覽

以 SQLite 為後端的本機 DynamoDB 模擬器,提供助手 35 個工具來建立、查詢、修改與快照 DynamoDB 資料表,不需 AWS。

可以做什麼
  • 檢視資料庫與資料表:資料庫資訊、資料表清單、結構詳情、TTL 與標籤設定
  • 建立、更新與刪除資料表,包含鍵結構、GSI、LSI、計費模式與刪除保護
  • 讀寫項目:單筆與批次的讀取、寫入、刪除,大量插入,更新表達式,條件式寫入
  • 查詢與掃描資料表及索引,支援篩選、投影、分頁與僅計數模式
  • 執行 PartiQL 陳述式、批次與全有或全無的交易,以及原子化的多項讀寫
  • 搜尋向量索引、讀取 DynamoDB Streams 記錄、執行 TTL 清理,並建立、列出、還原或刪除快照
適用情境
適合在開發或測試會存取 DynamoDB 的程式時使用,讓助手在本機建立資料表、灌入資料並執行查詢,不需 AWS 憑證或 JVM 模擬器。也適用於 CI 流程,以及由助手協助排查 DynamoDB 資料模型問題。
執行需求
以本機 stdio 程序執行,通常透過 npx dynoxide 或已發布的容器映像啟動;使用 npm 方式需要 Node.js。不需 AWS 帳號、憑證、API 金鑰或環境變數,資料全部留在本機。
安裝前請注意
許多工具會寫入或刪除資料,其中部分標示為破壞性操作:delete_table 會刪除資料表及其資料,restore_snapshot 會以快照內容取代目前全部資料,delete_snapshot 會移除還原點。啟用唯讀模式可阻擋寫入類工具。它面向本機開發與測試,並非正式環境 DynamoDB 的替代品,且部分行為與 AWS 不同,例如無法模擬最終一致性讀取、資料流只有單一分片。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Dynoxide,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Dynoxide

[crates.io] [docs.rs] [CI] [conformance] [license]

A DynamoDB emulator in Rust, backed by SQLite. Runs as an HTTP server or an MCP server for coding agents, embeds into Rust and iOS applications as a library, and compiles to WebAssembly for the browser.

The crates.io badge above shows the crate version, which covers the Rust library alone. Everything you install rather than depend on carries a separate product version: the binary, the npm packages, the container images, the browser engine and the Action. That is the number dynoxide --version prints and the one to quote in a bug report. Why there are two.

Why Dynoxide?

I built Dynoxide because DynamoDB Local is slow, heavy, and can't embed. It needs a JVM, and the typical Docker-based setups adds ~3 seconds of cold-start, ~209 MB of memory at idle, and a ~225MB Docker image (~473 MB on disk) before you've done anything useful. If you're running integration tests, that's Docker starting, the JVM warming up, and your pipeline waiting.

Dynoxide is a native binary. It starts in milliseconds, idles at ~7.2 MB, and ships as a ~3 MB download. Point any DynamoDB SDK at it and your tests just work.

For Rust projects, there's also an embedded mode - direct API calls via Database::memory() with no HTTP layer at all. Each test gets an isolated in-memory database with zero startup cost. And because it compiles to a native library with no runtime dependencies, it runs on platforms where DynamoDB Local can't, including iOS.

Performance

Local Development (Apple Silicon)
MetricDynoxide (embedded)Dynoxide (HTTP)DynamoDB Local
Cold startup~0.2ms~15ms~2,287ms
GetItem (p50)9µs0.1ms0.8ms
PutItem throughput~51,613 ops/s~6,703 ops/s~945 ops/s
50-test suite (sequential)~484ms~569ms~2,407ms
50-test suite (4x parallel)~203ms~235ms~1,189ms
CI (GitHub Actions)

Numbers from ubuntu-latest (4-core AMD EPYC 7763, 16GB RAM). Commit 17be96a.

MetricDynoxide (embedded)Dynoxide (HTTP)DynamoDB LocalLocalStack (all services)FlociMiniStack
Cold startup<1ms~2ms~2,605ms~12,217ms~228ms~2,636ms
GetItem (p50)16µs0.3ms0.8ms---
50-test CI suite828ms859ms2,628ms---
Full workload (10K items)-3.2s12.2s---
Binary / image (download)~3 MB~3 MB225 MB1.1 GB--
Binary / image (on disk)8 MB8 MB473 MB1.1 GB234 MB162 MB
Idle memory (RSS)~7.2 MB~8 MB~209 MB~387 MB~23 MB~47 MB

The gap is wider on Apple Silicon because the faster CPU amplifies the difference between native code and JVM overhead. Both are real measurements of the same benchmark suite. Full methodology and per-operation breakdowns →

Conformance

Dynoxide is continuously verified against real DynamoDB by Parity Suite, the DynamoDB conformance suite that runs one test matrix against AWS itself and every major DynamoDB emulator. Pass rates move as the suite grows and each engine changes, so rather than pin a snapshot that goes stale, see the live standings:

Disclosure: Dynoxide and Parity Suite are maintained by the same person. The suite scores Dynoxide on the same public matrix it runs against every other engine, and the results and test code are open.

This covers the native build. The WebAssembly build is scored as its own row: it passes every test it implements, with a far higher skip count than any other target because several operations are still missing.

How It Compares

DynoxideDynamoDB LocalLocalStack (all services)FlociMiniStackdynalite
LanguageRustJavaPython + JavaJava (GraalVM native image)PythonNode.js
StorageSQLiteSQLiteSQLite (via DDB Local)Its own (in-memory, persistent or WAL)Its own (in-memory, optional on-disk state)LevelDB
Runtime dependency-JVMDocker + a LocalStack account (auth token)DockerDocker or PythonNode.js
Embeddable (Rust / iOS)✓-----
MCP server for agents✓-----

LocalStack uses DynamoDB Local internally as its DynamoDB engine, so its startup and memory overhead includes DynamoDB Local's JVM plus LocalStack's own Python routing layer. Since March 2026 its image needs a LocalStack account and LOCALSTACK_AUTH_TOKEN to start, even for the services that used to be free. Floci and MiniStack are general AWS emulators like LocalStack, each with its own DynamoDB engine rather than DynamoDB Local.

Quick Start

Run a local server without installing anything:

sh
npx dynoxide --port 8000

Or install it into a project to pin the version, after which npx dynoxide uses that copy:

sh
npm install --save-dev dynoxide

Or run it in Docker, a drop-in for amazon/dynamodb-local:

sh
docker run --rm -p 8000:8000 ghcr.io/nubo-db/dynoxide

Point any AWS SDK or DynamoDB client at http://localhost:8000. For Homebrew, Cargo, pre-built binaries, and embedding as a Rust library, see the installation guide.

Add --log quiet to suppress informational startup and shutdown messages on stderr (useful in test suites). It works on serve, mcp and import --serve or --mcp, and warnings and errors still print. Without --log, the output is unchanged.

Documentation

  • Installation - npm, Homebrew, Cargo, binaries, GitHub Actions, and Docker
  • HTTP server - running the DynamoDB-compatible HTTP API
  • Testcontainers - driving the container from a test suite, and the wait strategy it needs
  • MCP server - the Model Context Protocol server for coding agents
  • DynamoDB Streams - enabling and reading stream records
  • Import CLI - loading data, table filtering, and anonymisation
  • WebAssembly - the browser build and embed contract
  • Using as a Rust library - embedded mode and feature flags
  • Compatibility - operation, expression, and PartiQL coverage versus DynamoDB
  • Versioning - what the version number promises and what forces a major
  • Releasing - release cadence and process

Supported Operations

Dynoxide implements the DynamoDB API across tables, items, query and scan, batches, transactions, PartiQL, streams, TTL, and tags, with GSI and LSI support, the full expression syntax, and DynamoDB-compatible pagination, validation, and error codes. For the operation-by-operation breakdown and a comparison, see the compatibility summary.

Limitations

Dynoxide is built for local development, testing, and CI, not as a production DynamoDB replacement, so two classes of thing are missing on purpose.

Cloud-only operations with no local equivalent aren't implemented: backups and point-in-time restore, global tables, Kinesis streaming, resource policies, and capacity management. Call one and you get an UnknownOperationException.

A few behavioural differences are also worth knowing when you test against it:

  • ConsistentRead is accepted but changes nothing. SQLite is strongly consistent, so every read already is - you can't reproduce eventually-consistent reads.
  • Streams expose a single shard. DescribeStream returns one shard, and its ExclusiveStartShardId and Limit paging parameters are accepted but ignored.
  • Transaction-contention errors (TransactionConflictException, TransactionInProgressException) aren't emulated - there's no concurrent contention in a single process.

For the per-feature support matrix, see the live capability matrix; the full operation-by-operation breakdown is in the compatibility summary.

Acknowledgements

Dynoxide's DynamoDB API semantics and validation logic were informed by dynalite, the excellent DynamoDB emulator built on LevelDB by Michael Hart and now maintained by the Architect team.

Dynoxide is a clean-room Rust implementation. No code was ported directly, but dynalite's thorough approach to matching live DynamoDB behaviour, including edge cases and error messages, was an invaluable reference.

Dynoxide uses SQLite as its storage layer. (AWS's DynamoDB Local also uses SQLite internally.)

License

Dual-licensed under MIT and Apache 2.0. See LICENSE-MIT and LICENSE-APACHE.

Trademarks

Amazon DynamoDB, DynamoDB, and AWS are trademarks of Amazon.com, Inc. or its affiliates. Dynoxide is an independent project and is not affiliated with, endorsed by, or sponsored by Amazon, and nothing here grants any right to use those names or marks.

來源:README.md,提交 aecc7ab

工具

35

batch_execute_partiql

[WRITE] Execute a batch of PartiQL statements. Each statement can be SELECT, INSERT, UPDATE, or DELETE. A member's RETURNING clause is honoured, with the returned item surfaced on that response's Item field. Write statements are blocked in read-only mode.

輸入參數statements必填return_consumed_capacity

batch_get_item

Retrieve up to 100 items from one or more tables in a single call. Accepts both PascalCase (Keys) and snake_case (keys) in request_items.

輸入參數request_items必填return_consumed_capacity

batch_write_item

[WRITE] Write up to 25 put or delete operations across one or more tables in a single call. Accepts both PascalCase (PutRequest/DeleteRequest) and snake_case (put_request/delete_request) keys. Duplicate keys across operations are rejected. ReturnItemCollectionMetrics: SIZE returns partition collection size for tables with LSIs.

輸入參數request_items必填return_consumed_capacity

bulk_put_items

[WRITE] Bulk-insert items into a table. Faster than repeated put_item calls. Maximum 10,000 items per call. Existing items with the same key are overwritten.

輸入參數items必填table_name必填record_streams

create_snapshot

[WRITE] Create a snapshot of the current database state. Returns the snapshot name for later restoration via restore_snapshot. A global limit of 20 snapshots is enforced, and when it is reached auto-snapshots are evicted first, then the oldest manual ones. This holds the database lock for the duration of the copy, so a large database may briefly block other operations.

輸入參數name

create_table

[WRITE] Create a new DynamoDB table with specified key schema and optional GSIs and LSIs. Supports BillingMode, ProvisionedThroughput, OnDemandThroughput, SSESpecification, TableClass, Tags, and DeletionProtectionEnabled. The table is available immediately after creation.

輸入參數tagskey_schema必填table_name必填table_classbilling_modevector_indexessse_specificationon_demand_throughputstream_specificationattribute_definitions必填provisioned_throughputlocal_secondary_indexes另有 2 個

delete_item

[WRITE] Delete a single item by its primary key. Returns the deleted item if return_values is set to ALL_OLD. Blocked if DeletionProtectionEnabled is set on the table. Condition expression values are validated for empty strings/sets/numbers.

輸入參數key必填table_name必填return_valuescondition_expressionreturn_consumed_capacityexpression_attribute_namesexpression_attribute_valuesreturn_values_on_condition_check_failure

delete_snapshot

[DESTRUCTIVE] Delete a snapshot by name. Use list_snapshots to see available snapshots.

輸入參數name必填

delete_table

[DESTRUCTIVE] Delete a table and all its data. An auto-snapshot is created before deletion for recovery via restore_snapshot.

輸入參數table_name必填

describe_stream

Get details about a DynamoDB Stream including its shards.

輸入參數limitstream_arn必填

describe_table

Get detailed schema information for a table including key schema, GSIs, LSIs, item count, size, stream config, and TTL settings. Returns an agent-friendly flattened format by default; set raw=true for the full DynamoDB-format response.

輸入參數rawtable_name必填

describe_time_to_live

Get the TTL configuration for a table.

輸入參數table_name必填

execute_partiql

Execute a PartiQL statement. Supports SELECT (with LIMIT, nested paths), INSERT (with IF NOT EXISTS, parameter placeholders), UPDATE (with SET arithmetic, REMOVE, nested paths), DELETE. UPDATE and DELETE accept a RETURNING clause, surfaced in the response Items: DELETE allows only RETURNING ALL OLD * (returning the deleted item; other variants are rejected), UPDATE allows all four RETURNING <ALL|MODIFIED> <OLD|NEW> * variants. WHERE supports BETWEEN, IN, CONTAINS, IS MISSING, IS NOT MISSING, AND, OR, NOT, parenthesised grouping up to 64 levels deep, and nested paths; AND binds tighter than OR, and a NOT over a group is applied by De Morgan. An index is named in the FROM clause as "table"."index", which serves the read from that GSI or LSI on SELECT only; a write statement rejects the qualifier. An UPDATE or DELETE whose WHERE condition fails is a ConditionalCheckFailedException; with return_values_on_condition_check_failure set to ALL_OLD the error carries the item the condition was evaluated against. Write statements are blocked in read-only mode.

輸入參數limitstatement必填next_tokenparametersconsistent_readreturn_consumed_capacityreturn_values_on_condition_check_failure

execute_transaction_partiql

[WRITE] [DESTRUCTIVE] Execute PartiQL statements transactionally (all-or-nothing). Max 100 statements. If any fails, the entire transaction is rolled back. A RETURNING clause is not supported inside a transaction and is rejected with a ValidationException. Example transact_statements: [{"Statement": "INSERT INTO Users VALUE {'pk': 'u1', 'name': 'Alice'}"}]

輸入參數transact_statements必填client_request_tokenreturn_consumed_capacity

get_database_info

Get database-level information: storage mode, path, size, table count, and per-table summaries. When the data was loaded by dynoxide import, also returns the import's notices and whether any exposures were accepted. Use this as your first call to orient yourself.

無需輸入參數。

get_item

Retrieve a single item by its primary key.

輸入參數key必填table_name必填consistent_readprojection_expressionreturn_consumed_capacityexpression_attribute_names

get_records

Read stream records using a shard iterator.

輸入參數limitshard_iterator必填

get_shard_iterator

Get a shard iterator for reading stream records. Use TRIM_HORIZON for all records or LATEST for new records only.

輸入參數shard_id必填stream_arn必填sequence_numbershard_iterator_type必填

list_snapshots

List available database snapshots with name, size, and creation time. Returns newest first, up to 20 entries.

無需輸入參數。

list_streams

List DynamoDB Streams, optionally filtered by table name.

輸入參數limittable_name

list_tables

List all DynamoDB tables in the database. Returns table names as an array.

無需輸入參數。

list_tags_of_resource

List tags for a DynamoDB table.

輸入參數resource_arn必填

put_item

[WRITE] Insert or replace an item in a table. Supports conditional writes via condition_expression. Empty strings, empty sets, and invalid numbers are rejected. Sets are deduplicated. Unused ExpressionAttributeNames/Values are rejected.

輸入參數item必填table_name必填return_valuescondition_expressionreturn_consumed_capacityexpression_attribute_namesexpression_attribute_valuesreturn_values_on_condition_check_failure

query

Query items using a key condition expression. Supports filtering, projection, pagination, and GSI/LSI queries via IndexName. Use select=COUNT to get only Count and ScannedCount without items.

輸入參數limitselectindex_nametable_name必填filter_expressionscan_index_forwardexclusive_start_keyprojection_expressionkey_condition_expression必填return_consumed_capacityexpression_attribute_namesexpression_attribute_values

restore_snapshot

[DESTRUCTIVE] Restore the database from a snapshot. This replaces all current data with the snapshot contents. Use list_snapshots to see available snapshot names.

輸入參數name必填

scan

Scan an entire table or GSI/LSI, optionally applying a filter expression. Use query instead when you know the partition key. Use select=COUNT to get only Count and ScannedCount without items. Use Segment and TotalSegments for parallel scan; segment filtering uses FNV-1a hash at the SQLite level.

輸入參數limitselectsegmentindex_nametable_name必填total_segmentsfilter_expressionexclusive_start_keyprojection_expressionreturn_consumed_capacityexpression_attribute_namesexpression_attribute_values

search_vectors

[READ] Search a vector index for the nearest entries to a query vector. Exact brute-force KNN over the whole index, so the top-k is the true top-k. COSINE and EUCLIDEAN score as distances, where a self match is 0; DOT_PRODUCT scores as a similarity and can be negative. The vector attribute is excluded from results unless a projection_expression names it and the index projects it. Create the index with create_table's vector_indexes, which is searchable at once. An index added later through update_table refuses with 'Cannot search backfilling vector index' until it settles, for longer than describe_table reports it CREATING, so retry the search rather than waiting for the status.

輸入參數top_k必填index_name必填table_name必填search_vector必填projection_expressionreturn_consumed_capacityexpression_attribute_namesexpression_attribute_valuessearch_condition_expression

sweep_ttl

[WRITE] Run a TTL sweep, deleting expired items from all TTL-enabled tables. Returns the number of items deleted.

無需輸入參數。

tag_resource

[WRITE] Add tags to a DynamoDB table.

輸入參數tags必填resource_arn必填

transact_get_items

Execute up to 100 get operations atomically. Returns a consistent snapshot of all requested items.

輸入參數transact_items必填return_consumed_capacity

transact_write_items

[WRITE] Execute up to 100 write actions (Put, Update, Delete, ConditionCheck) atomically. All succeed or all fail. Response includes ItemCollectionMetrics for tables with LSIs.

輸入參數transact_items必填client_request_tokenreturn_consumed_capacity

untag_resource

[WRITE] Remove tags from a DynamoDB table.

輸入參數tag_keys必填resource_arn必填

update_item

[WRITE] Update an item's attributes using an update expression. Supports SET, REMOVE, ADD, DELETE actions and conditional updates. REMOVE/ADD/DELETE on key attributes are rejected. Arithmetic uses arbitrary-precision decimal.

輸入參數key必填table_name必填return_valuesupdate_expressioncondition_expressionreturn_consumed_capacityexpression_attribute_namesexpression_attribute_valuesreturn_values_on_condition_check_failure

update_table

[WRITE] Update a table: add/remove GSIs, change stream settings, switch BillingMode, ProvisionedThroughput or OnDemandThroughput, change TableClass, or toggle DeletionProtectionEnabled.

輸入參數table_name必填table_classbilling_modeon_demand_throughputstream_specificationvector_index_updatesattribute_definitionsprovisioned_throughputdeletion_protection_enabledglobal_secondary_index_updates

update_time_to_live

[WRITE] Enable or disable Time to Live (TTL) on a table. Specify the attribute that holds the expiration timestamp.

輸入參數table_name必填time_to_live_specification必填

版本歷史

5
  1. v1.5.0Oct 23, 2026
  2. v1.4.0Oct 21, 2026
  3. v1.3.0Oct 10, 2026
  4. v1.2.1Sep 20, 2026
  5. v1.2.0Sep 16, 2026

評分

已滿足適用檢查項的 90%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分
  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分