Docker ile DynamoDB Local Nasıl Çalıştırılır — Eksiksiz Rehber

DynamoDB Local, AWS'nin DynamoDB'yi tek bir işlemde indirilebilir emülasyonudur — aynı API, AWS hesabı yok, ağ yok, istek başına fatura yok. Yerel geliştirme ve entegrasyon testleri için kullanın, ardından üretimde aynı kodu buluta yönlendirin. Provisioned throughput'u yok sayar ve asla kısıtlama yapmaz, bu yüzden yük veya limit testinin yerini tutamaz.

DynamoDB Local'i Docker ile nasıl çalıştırırım?

Resmi imajı başlatmak için docker run -p 8000:8000 amazon/dynamodb-local çalıştırın; bu, DynamoDB motorunu http://localhost:8000 üzerinde açığa çıkarır. AWS SDK'nızı veya CLI'nizi herhangi bir sahte kimlik bilgisiyle o endpoint'e yönlendirin, ardından tam olarak buluta karşı yaptığınız gibi tablolar oluşturun ve istekler çalıştırın. Yeniden başlatmalar boyunca verileri korumak için -sharedDb ve bağlanmış bir -dbPath volume ekleyin.

Konteyneri başlatın

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

Bu, motoru http://localhost:8000 üzerinde açığa çıkarır.

docker-compose

Çoğu proje bunu docker-compose.yml içinde sabitler, böylece tüm ekip aynı endpoint'i alır:

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:

İmaj, root olmayan dynamodblocal sensı olarak çalışır ve bu kullanıcı, root'a ait adlandırılmış volume içindeki bir veritabanı dosyasını açamaz — user: root olmadan SQLiteException [14] unable to open database file hatasını alırsınız ve her çağrı takılır.

Kalıcılık

Varsayılan olarak DynamoDB Local bellek içidir — konteyner durduğunda her tablo yok olur. İki bayrak onu kalıcı hale getirir:

• -sharedDb tüm istemcileri tek bir paylaşılan veritabanı dosyasında tutar (onsuz, her kimlik bilgisi/bölge kümesi kendi izole DB'sini alır — yaygın bir "tablom nereye gitti?" sürprizi).
• -dbPath /data + bağlanmış bir volume, o dosyayı diske yazar, böylece veri docker compose down sonrasında da kalır.

SDK'yı ona yönlendirin

Yalnızca endpoint değişir — kimlik bilgileri herhangi bir sahte değer olabilir:

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

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

Bir tablo oluşturun

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

Bunun gibi bir single-table PK/SK şeması iyi bir varsayılandır. Fixture'ları yüklerken, düz JSON'u DynamoDB-JSON dönüştürücüsü ile wire formatına çevirin.

Konteynerin çalıştığını ve tablonun yerine oturduğunu doğrulayın:

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

Bir GUI ile ona göz atın

CLI çağrıları hızla yorucu olur. Alışılmış seçenekler açık kaynak dynamodb-admin web arayüzü veya bir masaüstü istemcisidir. DynoTable, doğrudan localhost:8000'e (veya herhangi bir LocalStack endpoint'ine — bkz. DynamoDB Local ve LocalStack'e bağlanma) bağlanır ve bulut tablolarında kullandığınız aynı arayüzle yerel tablolara göz atmanıza, SQL Workbench ile sorgulamanıza ve düzenlemenize olanak tanır — aws CLI gidiş dönüşleri olmadan.

Local'in emüle etmedikleri

Local'i bir kapasite simülatörü değil, bir API uyumluluk katmanı olarak görün. Provisioned throughput'u yok sayar, hiçbir zaman ProvisionedThroughputExceededException döndürmez ve on-demand burst davranışını modellemez. Local'e karşı yapılan bir yük testi, AWS'deki partition sınırları ya da adaptive capacity hakkında size hiçbir şey söylemez.

Planlamazsanız entegrasyon testlerinde başka boşluklar da ortaya çıkar:

Testiniz kısıtlamayı, saniyeler içinde TTL sona ermesini ya da akış dağıtımını iddia ediyorsa, en az bir paketi tek kullanımlık bir bulut tablosuna ya da ihtiyacınız olan özellikleri açılmış bir LocalStack'e karşı çalıştırın.

Pratik bir yerel iş akışı

Çoğu ekip Local'i üç katmana bağlar:

1. Birim testleri — konteyneri CI'da ayağa kaldırın, tabloları beforeAll'da oluşturun, afterAll'da yıkın. Fixture'ları küçük tutun; testler attribute haritalarını elle yapıştırdığında düz JSON'u DynamoDB JSON dönüştürücüsünden geçirin.
2. Entegrasyon testleri — uygulamanızın kullandığı aynı SDK istemci fabrikasını çalıştırın, yalnızca endpoint ve kimlik bilgilerini değiştirin. Tüketilen kapasiteye değil, öğe biçimine ve koşullu yazmalara iddia yazın (Local, bütçeleme için anlamlı bir ConsumedCapacity döndürmez).
3. Elle keşif — DynoTable'ı bir Local profiliyle bağlayın, düzenlemeleri hazırlayın ve şema değişikliklerini dağıtmadan önce PartiQL ya da anahtar koşullu sorgular çalıştırın.

Tek bir süreci aştığınızda — birden çok servis, S3 tetikleyicileri ya da IAM tarzı yönlendirme — LocalStack'e ya da bir dev hesabına geçin. Local, "erişim desenim derleniyor mu?" sorusu için en hızlı döngü olmayı sürdürür.

Elle marshal etmeden veri tohumlayın

Bir JSON dosyasından on fixture öğesi yüklemek, her değeri kendiniz etiketlemediğinizde daha hızlıdır. Diziyi DynamoDB JSON dönüştürücüsüne yapıştırın, marshal edilmiş çıktıyı kopyalayın ve --endpoint-url http://localhost:8000 ile BatchWriteItem kullanarak toplu yazın. Güncelleme ağırlıklı fixture'lar için UpdateExpression'ı DynamoDB ifade oluşturucuda kurun ve üretilen attribute haritalarını test koşum takımınıza yapıştırın.

DynoTable'ın öğe düzenleyicisi commit sırasında aynı marshalling'i yapar — bir test hatası sizi CLI'da ham {"S":...} blob'larına bakar hâlde bıraktığında işe yarar.

Local'i ne zaman bırakmalı

Aşağıdakilerden herhangi birinin AWS'nin kendisinde ölçülmesi gerektiğinde gerçek bir tabloya geçin:

• Kapasite planlaması — saniyede 1.000 kez sorgulanan 1 KB'lık bir öğe, on-demand faturalandırmada saniyede kabaca 250 nihai tutarlı RCU tüketir; Local sıfır raporlar. Bunu, boyutları öğe boyutu hesaplayıcısından alıp fiyatlandırma hesaplayıcısıyla modelleyin.
• Dizin yayılma gecikmesi — GSI okumaları production'da nihai tutarlıdır; Local dizin satırlarını o kadar hızlı döndürür ki bayat okuma hataları dağıtıma kadar saklanır.
• Hesaplar arası IAM — kaynak kapsamlı roller ve koşul anahtarları yalnızca bulutta vardır.

Local'i şema ve ifade sözdiziminde hızlı geri bildirim için tutun; maliyet ve tutarlılık varsayımlarını production trafiğinden önce bir staging tablosuna karşı doğrulayın.

Etrafında betik yazmaya değer tuzaklar

• Unutulan -sharedDb — her benzersiz kimlik bilgisi çifti izole bir veritabanı alır; CI ile dizüstünüz farklı evrenler gibi görünür.
• user: root olmadan root'a ait volume — yukarıdaki bölümdeki compose geçersiz kılmasını eklemedikçe SQLite arka ucu sessizce başarısız olur.
• Streams eşitliğini varsaymak — akış etkin Lambda'lar bir bulut ya da LocalStack hedefi ister; Local tek başına dağıtımı çalıştırmaz.
• Boş string anahtarlar — 2020'den beri anahtar olmayan attribute'larda izinli, anahtarlarda hâlâ reddediliyor; fixture'ları AWS'de yapacağınız gibi doğrulayın.

DynoTable'ı indirin, http://localhost:8000'e yönelen bir profil ekleyin ve az önce oluşturduğunuz tablolara göz atın — production'da kullandığınız aynı ızgara, filtre oluşturucu ve SQL Workbench, döngüde sıfır AWS harcamasıyla.