Cara Menjalankan DynamoDB Lokal dengan Docker — Panduan Lengkap

DynamoDB Lokal adalah emulasi DynamoDB AWS yang dapat diunduh dalam satu proses — API yang sama, tanpa akun AWS, tanpa jaringan, tanpa tagihan per permintaan. Gunakan untuk lokal pengujian pengembangan dan integrasi, lalu arahkan kode yang sama ke cloud produksi. Ini mengabaikan throughput yang disediakan dan tidak pernah melakukan pembatasan, sehingga tidak bisa berdiri untuk pengujian beban atau batas.

Bagaimana cara menjalankan DynamoDB Lokal dengan Docker?

Jalankan docker run -p 8000:8000 amazon/dynamodb-local untuk memulai gambar resmi, yang memaparkan mesin DynamoDB pada http://localhost:8000. Arahkan SDK AWS Anda atau CLI di titik akhir tersebut dengan kredensial tiruan apa pun, lalu buat tabel dan jalankan permintaan persis seperti yang Anda lakukan terhadap cloud. Tambahkan -sharedDb dan mount Volume -dbPath untuk menyimpan data saat restart.

Mulai penampung

docker run -p 8000:8000 amazon/dynamodb-local

Itu memperlihatkan mesin pada http://localhost:8000.

docker-compose

Sebagian besar proyek menyematkannya di docker-compose.yml sehingga seluruh tim mendapatkan titik akhir yang sama:

services:
  dynamodb:
    image: amazon/dynamodb-local
    user: root
    command: '-jar DynamoDBLocal.jar -sharedDb -dbPath /data'
    ports:
      - '8000:8000'
    volumes:
      - dynamodb-data:/data
volumes:
  dynamodb-data:

Gambar dijalankan sebagai pengguna dynamodblocal non-root, yang tidak dapat membuka file database di dalam volume bernama milik root — tanpa user: root Anda akan mengalami SQLiteException [14] unable to open database file dan setiap panggilan menggantung.

Ketahanan data

Secara default, DynamoDB Lokal adalah dalam memori — setiap tabel hilang ketika kontainer berhenti. Dua bendera membuatnya tahan lama:

• -sharedDb menyimpan semua klien pada satu file database bersama (tanpa itu, masing-masing kumpulan kredensial/region mendapatkan DB terisolasinya sendiri — yang umum "di mana saya meja pergi?" kejutan).
• -dbPath /data + volume terpasang menulis file itu ke disk, jadi data bertahan docker compose down.

Arahkan SDK ke sana

Hanya titik akhir yang berubah — kredensial dapat berupa nilai tiruan apa pun:

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({
  endpoint: 'http://localhost:8000',
  region: 'local',
  credentials: {accessKeyId: 'x', secretAccessKey: 'x'}
});

Buat tabel

aws dynamodb create-table \
  --endpoint-url http://localhost:8000 \
  --table-name AppData \
  --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
  --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST

Skema tabel tunggal PK/SK seperti ini adalah bawaan yang bagus. Saat Anda memuat perlengkapan, ubah JSON biasa ke format kabel dengan Konverter DynamoDB-JSON.

Pastikan kontainer sudah berjalan dan tabelnya sudah terbentuk:

aws dynamodb list-tables --endpoint-url http://localhost:8000

Jelajahi dengan GUI

Panggilan CLI menjadi cepat membosankan. Opsi yang biasa adalah dynamodb-admin sumber terbuka UI web atau klien desktop. DynoTable terhubung langsung ke localhost:8000 (atau titik akhir LocalStack lainnya — lihat menghubungkan ke DynamoDB Lokal & LocalStack) dan memungkinkan Anda menelusuri, melakukan kueri dengan SQL Workbench, dan mengedit tabel lokal dengan UI yang sama yang Anda gunakan untuk tabel cloud — tidak ada perjalanan bolak-balik aws CLI.

Apa yang tidak ditiru oleh Lokal

Perlakukan Lokal sebagai lapisan kompatibilitas API, bukan simulator kapasitas. Itu mengabaikan throughput yang disediakan, tidak pernah kembali ProvisionedThroughputExceededException, dan tidak memodelkan perilaku burst sesuai permintaan. Tes beban terhadap Lokal memberi tahu Anda tidak ada apa pun tentang batas partisi atau kapasitas adaptif di AWS.

Kesenjangan lain muncul dalam pengujian integrasi jika Anda tidak merencanakannya:

Jika pengujian Anda menyatakan pembatasan, TTL akan habis masa berlakunya dalam hitungan detik, atau aliran keluar, jalankan setidaknya satu suite pada tabel cloud sekali pakai atau LocalStack dengan fitur yang perlu Anda aktifkan.

Alur kerja lokal yang praktis

Sebagian besar tim menyatukan Lokal menjadi tiga lapisan:

1. Pengujian unit — putar wadah di CI, buat tabel di beforeAll, sobek turun di afterAll. Jaga perlengkapan tetap kecil; marshal polos JSON melalui Konverter DynamoDB JSON saat pengujian ditempel peta atribut dengan tangan.
2. Tes integrasi — menggunakan pabrik klien SDK yang sama dengan yang digunakan aplikasi Anda, hanya menukar endpoint dan kredensial. Menegaskan pada bentuk item dan penulisan bersyarat, bukan pada kapasitas yang dikonsumsi (Lokal tidak kembali ConsumedCapacity yang berarti untuk penganggaran).
3. Eksplorasi manual — menghubungkan DynoTable dengan profil Lokal, pengeditan tahap, dan jalankan PartiQL atau kueri kondisi kunci sebelum Anda menerapkan perubahan skema.

Saat Anda melampaui satu proses — beberapa layanan, pemicu S3, atau gaya IAM perutean — beralih ke LocalStack atau a akun pengembang. Lokal tetap menjadi loop tercepat untuk "apakah pola akses saya dikompilasi?"

Data benih tanpa penyusunan tangan

Memuat sepuluh item perlengkapan dari file JSON lebih cepat jika Anda tidak memberi tag pada setiap item hargai dirimu sendiri. Rekatkan array ke dalam Konverter DynamoDB JSON, salin marshallnya keluaran, dan tulis batch dengan BatchWriteItem terhadap --endpoint-url http://localhost:8000. Untuk perlengkapan yang membutuhkan banyak pembaruan, rakitlah UpdateExpression di Pembuat ekspresi DynamoDB dan tempel peta atribut yang dihasilkan ke dalam rangkaian pengujian Anda.

Editor item DynoTable melakukan marshalling yang sama saat dilakukan — berguna ketika a kegagalan pengujian membuat Anda menatap gumpalan {"S":...} mentah di CLI.

Kapan harus meninggalkan Lokal

Kirim ke meja nyata ketika Anda memerlukan salah satu dari hal berikut yang diukur pada AWS itu sendiri:

• Perencanaan kapasitas — item 1 KB yang dikueri 1.000 kali per detik dikonsumsi sekitar 250 RCU yang akhirnya konsisten per detik pada penagihan sesuai permintaan; Lokal melaporkan nol. Modelkan itu dengan kalkulator harga menggunakan ukuran dari kalkulator ukuran item.
• Keterlambatan propagasi indeks — Pembacaan GSI pada akhirnya konsisten dalam produksi; Lokal mengembalikan baris indeks dengan cukup cepat sehingga bug yang sudah basi dapat disembunyikan hingga diterapkan.
• IAM lintas-akun — peran cakupan sumber daya dan kunci kondisi hanya ada di awan.

Pertahankan Lokal untuk umpan balik cepat tentang skema dan sintaksis ekspresi; memvalidasi biaya dan asumsi konsistensi terhadap tabel pementasan sebelum lalu lintas produksi.

Jebakan yang layak untuk ditulis skripnya

• -sharedDb yang Terlupakan — setiap pasangan kredensial unik diisolasi basis data; CI dan laptop Anda terlihat seperti alam semesta yang berbeda.
• Volume milik root tanpa user: root — backend SQLite gagal secara diam-diam hingga Anda menambahkan penggantian penulisan dari bagian di atas.
• Dengan asumsi paritas Streams — Lambdas yang mendukung streaming memerlukan cloud atau LocalStack sasaran; Masyarakat lokal saja tidak akan melakukan fan-out.
• Kunci string kosong — diizinkan pada atribut non-kunci sejak tahun 2020, masih ditolak pada kunci; validasi perlengkapan dengan cara yang sama seperti yang Anda lakukan di AWS.

Unduh DynoTable, tambahkan profil yang diarahkan ke http://localhost:8000, dan telusuri tabel yang baru saja Anda buat — kisi yang sama, pembuat filter, dan SQL Meja kerja yang Anda gunakan dalam produksi, tanpa pengeluaran AWS per loop.