Modul 6: Bermigrasi dari Cloud Datastore ke Cloud Firestore

1. Ringkasan

Rangkaian codelab ini (tutorial interaktif dan mandiri) bertujuan untuk membantu developer Google App Engine (Standar) memodernisasi aplikasi mereka dengan memandu mereka melalui serangkaian migrasi. Sebagian besar migrasi semacam ini melibatkan peralihan dari layanan paket runtime asli karena runtime generasi berikutnya lebih fleksibel, sehingga memberi pengguna lebih banyak opsi layanan. Cara lain untuk memodernisasi aplikasi mencakup mengupgrade ke produk yang lebih baru, dan itulah subjek codelab ini.

Pengguna App Engine yang mengakses Datastore dengan library klien Cloud NDB atau Cloud Datastore sudah siap dan tidak perlu dimigrasikan lebih lanjut. Namun, Cloud Firestore mewakili datastore NoSQL terbaru, skalabel, dan sangat tersedia dengan fitur dari database real-time Firebase.

Anda berada di tempat yang tepat jika Anda adalah developer yang merasa terdorong menggunakan Firestore untuk memanfaatkan fitur-fiturnya atau setidaknya memiliki minat yang cukup untuk mempelajari apa yang diperlukan oleh migrasi. Tutorial ini mengajarkan cara memigrasikan aplikasi App Engine menggunakan Cloud Datastore ke Cloud Firestore.

PERINGATAN: Migrasi ini bersifat opsional dan mahal. Beralih ke Firestore mengharuskan pengguna untuk menggunakan project yang berbeda (dan mungkin baru). Project Cloud dapat menggunakan salah satu dari Datastore atau Firestore, tetapi tidak keduanya. Setelah disetel, kartu tidak dapat diubah. Karena semua aplikasi App Engine lama menggunakan Datastore, project yang berbeda harus digunakan untuk penggunaan Firestore.

Anda akan mempelajari cara

• Mengenali perbedaan antara Datastore dan Firestore
• Bermigrasi dari Cloud Datastore ke Cloud Firestore

Yang Anda butuhkan

• Project Google Cloud Platform dengan:
  • Akun penagihan GCP aktif
  • App Engine yang diaktifkan
• Keterampilan Python dasar
• Pengetahuan perintah Linux umum yang berfungsi
• Pengetahuan dasar tentang mengembangkan dan men-deploy aplikasi App Engine
• Anda sebaiknya menyelesaikan codelab Modul 3, termasuk mentransfernya ke Python 3, sebelum memulai codelab ini (Modul 6).
• Aplikasi App Engine Modul 3 Cloud Datastore Python 3 yang berfungsi.

Survei

Bagaimana Anda akan menggunakan codelab ini?

Hanya membacanya Membacanya dan menyelesaikan latihan

2. Latar belakang

Datastore App Engine menjadi produknya sendiri pada tahun 2013, yaitu Google Cloud Datastore, dan sekarang dapat diakses oleh developer di luar App Engine. Tahun berikutnya, Firebase diakuisisi oleh Google. Pada saat itu, platform ini terkenal dengan database real-time.

Selama beberapa tahun berikutnya, tim Firebase dan Cloud Datastore bekerja mengintegrasikan beberapa fitur Firebase ke dalam Datastore. Hasilnya, pada tahun 2017, Cloud Datastore generasi berikutnya dirilis. Untuk mencerminkan mewarisi beberapa fitur Firebase, produk ini diganti namanya menjadi Cloud Firestore.

Cloud Firestore menjadi mekanisme penyimpanan NoSQL default untuk project Google Cloud. Aplikasi baru dapat menggunakan Cloud Firestore secara native, sementara database Datastore yang ada dikonversi ke Firestore dan sekarang beroperasi sebagai "Firestore dalam mode Datastore" untuk mempertahankan kompatibilitas dengan operasi Datastore. Oleh karena itu, aplikasi hanya dapat mengoperasikan Cloud Firestore dalam salah satu mode tersebut, dan setelah ditetapkan, tidak dapat diubah.

Saat ini, ketika pengguna membuat project baru dan memilih solusi NoSQL, mereka akan diminta untuk memilih Firestore dalam mode Datastore atau Firestore dalam mode native. Setelah pengguna menambahkan entity Datastore, mereka tidak dapat beralih ke Firestore. Demikian pula, setelah mode native Firestore dipilih, mereka tidak dapat lagi beralih kembali ke Datastore (atau lebih tepatnya, Firestore dalam mode Datastore). Baca bagian memilih antara Cloud Firestore dalam mode Datastore atau halaman mode Firestore native dalam dokumentasi untuk mengetahui detail selengkapnya. Untuk memigrasikan aplikasi ke Firestore, project baru harus dibuat, Datastore diekspor lalu diimpor ke Firestore. Tujuan tutorial ini adalah untuk memberikan gambaran kepada developer tentang perbedaan antara penggunaan Cloud Datastore dan Cloud Firestore.

Migrasi ini bukanlah migrasi yang kami harapkan untuk dilakukan pengguna, sehingga merupakan migrasi opsional. Meskipun ada keuntungan nyata menggunakan Cloud Firestore secara native seperti autentikasi klien, integrasi aturan Firebase, dan tentu saja, database real-time Firebase, langkah-langkah migrasi "tidak nyaman":

• Anda harus menggunakan project yang berbeda dengan project aplikasi Anda saat ini.
• Project dengan aplikasi yang telah menambahkan entity Datastore tidak dapat dialihkan ke Firestore dalam mode native
• Demikian pula, project yang telah memilih Firestore dalam mode native tidak dapat dikembalikan ke Firestore dalam mode Datastore.
• Tidak ada alat migrasi yang dapat melakukan streaming data dari satu project ke project lainnya.
• Beberapa fitur Datastore penting, termasuk namespace dan throughput tulis yang lebih tinggi (>10 k/dtk), tidak tersedia dari Firestore.
• Alat ekspor dan impor bersifat "primitif" dan "semua atau tidak sama sekali" yang signifikan.
  • Jika aplikasi Anda memiliki banyak entity Datastore, proses ekspor dapat memerlukan waktu berjam-jam untuk kemudian diimpor ke Firestore.
  • Selama jangka waktu ini, aplikasi/layanan Anda tidak akan dapat menulis/memperbarui data.
  • Aktivitas migrasi diperhitungkan dalam penggunaan normal; Anda sebaiknya menyebarkannya (di seluruh kuota harian jika memungkinkan) untuk meminimalkan biaya.
  • Karena layanan baru Anda berjalan di project yang berbeda, Anda memerlukan jendela untuk menerapkan update DNS.
• Datastore dan Firestore memiliki model data yang serupa tetapi berbeda sehingga proses migrasi memerlukan pembaruan cara kerja aplikasi/layanan
  • Kueri ancestor dari Datastore kini menjadi Kueri koleksi Firestore (default)
  • Kueri jenis yang luas dari Datastore adalah Kueri grup koleksi Firestore
  • Indeks dan penanganannya berbeda, dll.

Oleh karena itu, jika Anda memiliki aplikasi yang cukup mudah dipertimbangkan untuk migrasi, bersiap untuk menyimulasikan migrasi tersebut, atau hanya di sini untuk mempelajari Datastore vs. Firestore, silakan lanjutkan.

Pengguna Python 2: Codelab migrasi opsional ini hanya disajikan di Python 3, tetapi karena Cloud Firestore juga mendukung 2.x, pengguna dapat menginterpolasi perbedaan penggunaan. Salah satu contohnya adalah data Firestore menggunakan string Unicode (bukan string byte), sehingga indikator utama u'' diperlukan untuk literal string Python 2, yang berarti fungsi store_visit() 2.x akan terlihat seperti ini:

def store_visit(remote_addr, user_agent):
    doc_ref = fs_client.collection(u'Visit')
    doc_ref.add({
        u'timestamp': datetime.now(),
        u'visitor': u'{}: {}'.format(remote_addr, user_agent),
    })

Selain itu, library klien harus beroperasi dengan cara yang sama. Satu-satunya masalah lain yang perlu dipertimbangkan adalah library Cloud Firestore 2.x sedang "beku" selama pengembangan berjalan, semakin banyak fitur/fitur yang lebih baru hanya akan tersedia di library klien Firestore 3.x.

Melanjutkan migrasi ini, berikut adalah langkah-langkah utama dalam tutorial ini:

1. Penyiapan/Prakerja
2. Menambahkan library Cloud Firestore
3. Memperbarui file aplikasi

3. Penyiapan/Prakerja

Sebelum memulai bagian utama tutorial, mari kita siapkan project, dapatkan kodenya, lalu deploy aplikasi dasar pengukuran sehingga kita tahu bahwa kita memulai dengan kode yang berfungsi.

1. Siapkan project

Sebaiknya gunakan kembali project yang sama dengan yang Anda gunakan untuk menyelesaikan codelab Modul 3. Atau, Anda dapat membuat project baru atau menggunakan kembali project lain yang sudah ada. Pastikan project memiliki akun penagihan yang aktif dan App Engine (aplikasi) diaktifkan.

2. Dapatkan aplikasi contoh dasar pengukuran

Salah satu prasyarat untuk codelab ini adalah memiliki aplikasi contoh Modul 3 yang berfungsi. Jika Anda tidak memilikinya, selesaikan tutorial Modul 3 (tautan di atas) sebelum melanjutkan ke sini. Atau, jika Anda sudah terbiasa dengan kontennya, Anda dapat memulai dengan mengambil kode Modul 3 di bawah.

Baik Anda menggunakan kode Anda atau kode kami, kode Modul 3 adalah tempat kita akan memulai. Codelab Modul 6 ini akan memandu Anda melalui setiap langkah, dan jika sudah selesai, codelab ini akan menyerupai kode pada titik FINISH. (Tutorial ini hanya tersedia untuk Python 3.)

• START: Repositori Modul 3
• SELESAI: Repositori Modul 6
• Seluruh repo (clone atau download ZIP)

Direktori file Modul 3 (milik Anda atau milik kami) akan terlihat seperti ini:

$ ls
README.md               main.py                 templates
app.yaml                requirements.txt

3. Deploy (ulang) aplikasi Modul 3

Langkah prakerja yang tersisa untuk dijalankan sekarang:

1. Biasakan kembali diri Anda dengan alat command-line gcloud (jika perlu)
2. Deploy (ulang) kode Modul 3 ke App Engine (jika perlu)

Setelah Anda berhasil menjalankan langkah-langkah tersebut dan mengonfirmasikan operasinya, kita akan melanjutkan tutorial ini, dimulai dengan file konfigurasi.

CATATAN: Tutorial ini hanya mendukung Python 3; Jika Anda memiliki aplikasi Python 2 dan ingin bermigrasi dari Datastore ke Firestore, lihat bagian persyaratan di bawah.

Persyaratan Python 2

• Pastikan app.yaml (masih) merujuk ke paket yang dipaketkan pihak ketiga: grpcio dan setuptools.
• Pastikan appengine_config.py masih menggunakan pkg_resources dan google.appengine.ext.vendor untuk mengarahkan aplikasi ke resource pihak ketiga.
• Pada bagian berikutnya yang memperbarui requirements.txt, Anda harus menggunakan google-cloud-firestore==1.9.0 karena merupakan versi final dari library klien Python Firestore yang kompatibel dengan 2.x.
  • Jika requirements.txt Anda memiliki entri untuk google-cloud-core, biarkan apa adanya.
  • Hapus lib dan instal ulang dengan pip install -t lib -r requirements.txt.

4. Memperbarui file konfigurasi (menambahkan library Cloud Firestore)

Selain penyiapan, langkah berikutnya yang diperlukan adalah memperbarui konfigurasi yang diikuti dengan file aplikasi. Untuk yang pertama, satu-satunya perubahan konfigurasi adalah pertukaran paket minor di file requirements.txt Anda, jadi mari kita lakukan sekarang.

Ganti baris google-cloud-datastore dengan google-cloud-firestore di requirements.txt sehingga terlihat seperti ini:

Flask==1.1.2
google-cloud-firestore==2.0.2

Sebaiknya gunakan versi terbaru dari setiap library; nomor versi di atas adalah yang terbaru pada saat penulisan ini. Kode dalam folder repo FINISH lebih sering diperbarui dan mungkin memiliki versi yang lebih baru.

Tidak ada perubahan konfigurasi lain, sehingga app.yaml dan templates/index.html akan tetap seperti apa adanya.

5. Memperbarui file aplikasi

Hanya ada satu file aplikasi, main.py, sehingga semua perubahan di bagian ini hanya memengaruhi file tersebut.

1. Impor

Mengalihkan impor paket merupakan perubahan kecil dari datastore menjadi firestore:

• SEBELUM:

from google.cloud import datastore

• SETELAH:

from google.cloud import firestore

2. Akses Firestore

Setelah menginisialisasi Flask, buat klien Firestore Anda. Buat perubahan yang serupa seperti di atas, tetapi untuk inisialisasi klien:

• SEBELUM:

app = Flask(__name__)
ds_client = datastore.Client()

• SETELAH:

app = Flask(__name__)
fs_client = firestore.Client()

Dengan melakukan migrasi dari Cloud NDB ke Cloud Datastore, Anda telah menyelesaikan tugas berat untuk masuk ke Cloud Firestore. Dengan Datastore, Anda dapat membuat kumpulan data dalam bentuk Entity yang terdiri dari Properti umum dan mengelompokkannya berdasarkan Kunci. Kumpulan data di Firestore adalah Documents, yang terdiri dari key-value pair, dan dikelompokkan bersama ke dalam Collections. Migrasi dari Datastore mengharuskan Anda memikirkan perbedaan ini karena perbedaan tersebut akan terwujud saat Anda membuat kumpulan data data serta membuat kueri untuknya. Hasilnya dapat bervariasi, bergantung pada seberapa rumit kode Datastore Anda.

Untuk Datastore, Anda dapat membuat kueri berdasarkan jenis Entity beserta kriteria pemfilteran dan pengurutan. Untuk Firestore, cara membuat kueri data serupa. Mari kita lihat contoh singkat, dengan asumsi nilai kueri ini, klien (masing-masing ds_client atau fs_client), dan impor:

from datetime import datetime
from firestore.Query import DESCENDING

OCT1 = datetime(2020, 10, 1)
LIMIT = 10

Untuk Datastore, mari kita buat kueri untuk sepuluh entity Visit terbaru yang lebih baru dari 1 Oktober 2020 dalam urutan menurun:

query = ds_client.query(kind='Visit')
query.add_filter('timestamp', '>=', datetime(2020, 10, 1))
query.order = ['-timestamp']
return query.fetch(limit=LIMIT)

Melakukan hal yang sama untuk Firestore, dari koleksi Visit:

query = fs_client.collection('Visit')
query.where('timestamp', '>=', datetime(2020, 10, 1))
query.order_by('timestamp', direction=DESCENDING)
return query.limit(LIMIT).stream()

Kueri aplikasi contoh lebih sederhana (tanpa klausa "WHERE"). Sebagai tinjauan, berikut adalah kode Cloud Datastore:

• SEBELUM:

def store_visit(remote_addr, user_agent):
    entity = datastore.Entity(key=ds_client.key('Visit'))
    entity.update({
        'timestamp': datetime.now(),
        'visitor': '{}: {}'.format(remote_addr, user_agent),
    })
    ds_client.put(entity)

def fetch_visits(limit):
    query = ds_client.query(kind='Visit')
    query.order = ['-timestamp']
    return query.fetch(limit=limit)

Saat bermigrasi ke Firestore, Anda akan mendapati cara membuat dokumen baru yang mirip dengan entity, dan kueri seperti yang ditunjukkan sebelumnya.

• SETELAH:

def store_visit(remote_addr, user_agent):
    doc_ref = fs_client.collection('Visit')
    doc_ref.add({
        'timestamp': datetime.now(),
        'visitor': '{}: {}'.format(remote_addr, user_agent),
    })

def fetch_visits(limit):
    visits_ref = fs_client.collection('Visit')
    visits = (v.to_dict() for v in visits_ref.order_by('timestamp',
            direction=firestore.Query.DESCENDING).limit(limit).stream())
    return visits

Fungsi utama root() tetap sama seperti halnya file template index.html. Periksa kembali perubahan Anda, simpan, deploy, dan verifikasi.

6. Ringkasan/Pembersihan

Men-deploy aplikasi

Deploy ulang aplikasi Anda dengan gcloud app deploy dan konfirmasikan bahwa aplikasi berfungsi. Kode Anda sekarang seharusnya sesuai dengan yang ada di repositori Modul 6 (atau versi 2.x jika itu adalah preferensi Anda).

Jika Anda beralih ke rangkaian ini tanpa melakukan codelab sebelumnya, aplikasi itu sendiri tidak akan berubah. Aplikasi akan mendaftarkan semua kunjungan ke halaman web utama (/) dan terlihat seperti ini setelah Anda mengunjungi situs cukup waktu:

Selamat, Anda telah menyelesaikan migrasi Modul 6 opsional ini. Ini mungkin salah satu dari, jika bukan yang terakhir, migrasi yang dapat Anda lakukan sejauh penyimpanan data App Engine. Satu migrasi alternatif yang dapat Anda pertimbangkan adalah memasukkan aplikasi ke dalam container untuk Cloud Run jika Anda belum melakukannya (lihat Modul 4 dan 5, codelab yang ditautkan di bawah).

Opsional: Pembersihan

Bagaimana dengan pembersihan agar tidak ditagih hingga Anda siap untuk beralih ke codelab migrasi berikutnya? Sebagai developer yang sudah ada, Anda mungkin sudah mengetahui yang terbaru tentang informasi harga App Engine.

PENTING: Runtime App Engine asli sebelumnya tidak memerlukan akun penagihan aktif, tetapi kini tidak lagi (mulai November 2019, diberlakukan mulai April 2020). Namun, kami pastikan bahwa App Engine masih memiliki tingkat akses gratis, sehingga Anda tidak akan dikenakan tagihan apa pun kecuali batas tersebut terlampaui.

Opsional: Nonaktifkan aplikasi

Jika Anda belum siap melanjutkan ke tutorial berikutnya, nonaktifkan aplikasi untuk menghindari tagihan. Jika sudah siap untuk beralih ke codelab berikutnya, Anda dapat mengaktifkannya kembali. Saat dinonaktifkan, aplikasi tidak akan mendapatkan traffic apa pun yang dikenakan biaya, tetapi hal lain yang dapat ditagih adalah penggunaan Firestore jika melebihi kuota gratis, jadi cukup hapus hingga berada di bawah batas tersebut.

Di sisi lain, jika Anda tidak akan melanjutkan migrasi dan ingin menghapus semuanya, Anda dapat mematikan project.

Langkah berikutnya

Selain tutorial ini, ada beberapa codelab modul migrasi lain yang dapat Anda pertimbangkan:

• Modul 7: Task Queues Push App Engine (diperlukan jika Anda menggunakan Task Queues [push])
  • Tambahkan tugas push taskqueue App Engine ke aplikasi Modul 1
  • Siapkan pengguna untuk bermigrasi ke Cloud Tasks di Modul 8
• Modul 4: Bermigrasi ke Cloud Run dengan Docker
  • Build aplikasi dalam container untuk dijalankan di Cloud Run dengan Docker
  • Migrasi ini memungkinkan Anda untuk tetap menggunakan Python 2.
• Modul 5: Melakukan Migrasi ke Cloud Run dengan Cloud Buildpacks
  • Build aplikasi dalam container untuk dijalankan di Cloud Run dengan Cloud Buildpacks
  • Anda tidak perlu mengetahui apa pun tentang Docker, container, atau Dockerfile.
  • Mengharuskan aplikasi Anda untuk sudah bermigrasi ke Python 3 (Buildpacks tidak mendukung Python 2)

7. Referensi lainnya

Masalah/masukan codelab modul migrasi App Engine

Jika Anda menemukan masalah dengan codelab ini, telusuri masalah Anda terlebih dahulu sebelum mengajukan masalah. Link untuk menelusuri dan membuat masalah baru:

• Telusuri masalah
• Ajukan masukan/masukan baru

Referensi migrasi

Link ke folder repo untuk Modul 3 (START) dan Modul 6 (FINISH) dapat ditemukan pada tabel di bawah. Link tersebut juga dapat diakses dari repo untuk semua migrasi App Engine yang dapat Anda clone atau download file ZIP.

Codelab	Python 2	Python 3
Modul 3	(kode)	kode
Modul 6	(T/A)	kode

Resource App Engine

Berikut adalah resource tambahan terkait migrasi khusus ini:

• Referensi Python Cloud Datastore dan Cloud Firestore
  • Dokumen library klien Google Cloud Datastore
  • Repositori library klien Google Cloud Datastore
  • Dokumen library klien Google Cloud Firestore
  • Repositori library klien Google Cloud Firestore
• Melakukan migrasi ke Python 3 dan runtime GAE generasi berikutnya
  • Halaman beranda migrasi
  • Melakukan migrasi file konfigurasi App Engine
• Umum
  • Python di Google Cloud Platform
  • Library klien Python Google Cloud