CRUD app with data persistence

⏱ This tutorial is an introductory walkthrough using Begin Data as your application's database. It should take less than 10 minutes.

Introduction

Begin Data is an easy to use, fast, durable, highly scalable, fully managed, SSD-based key-value and document database built on top of AWS DynamoDB. And access to it is available for every Begin app!

You can think of Begin Data as syntactic sugar for making DynamoDB easier to work with. Designed to accommodate most general persistence use cases, its core API has three simple methods: get, set, and destroy.

In this tutorial, we'll show you how to set up and start using Begin Data with a simple todo CRUD app.

Prerequisites

You will need to have git and Node.js installed to your local computer to follow along with this tutorial. (Learn more about installing git and installing Node.js.)

You'll also need a GitHub account. (Learn more about signing up with GitHub.)

This tutorial also assumes some familiarity with such things as:

Text editors
Terminal / CLI
Git and version control
General software development using JavaScript

You do not need to be an expert in any of these things in order to follow along and make your first database-enabled app in Begin!

Getting started

First, click the Deploy to Begin button below. This starts the process of authorizing Begin with your GitHub account. (You may be prompted to log into GitHub, and/or be asked to create a Begin username.)

Name your app & repo

You'll then be prompted to name your new app and repository – this is optional, feel free to use the default app and repo name if you like!

Note: your Begin app name and repository name cannot be changed later.

Once you've clicked the Create... button, Begin will spin up your new project on GitHub (under github.com/{your GH username}/{your repo name}).

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions from this screen (or later from the Settings screen found in the left nav of your Begin app).

Your first deploy

After creating your app, you'll be taken to its Activity stream. Welcome to the main backend interface of your Begin app!

From the Activity view, you'll be able to watch your app build & deploy in real-time. Any time you push to master, you'll see a new build get kicked off in Begin.

Each build undergoes a number of predefined build steps (learn more about build steps here); these build steps may install your app's dependencies (install), test your code's syntax (lint), generate any files or assets needed to run your app (build), and/or run an automated test suite (test).

If no build steps fail, then the build containing your latest commit to master is automatically deployed to your staging environment.

Go ahead and click the Staging link in the upper left corner of your left nav to open your new app's staging URL. You should now see your new app:

💡 Learn more! Head here to dig deeper into covers build pipelines, git tagging, and more.

Get set up locally

Next let's get your new site running in your local environment (i.e. the computer you work on).

First, head to your GitHub repo (from the first card in your Activity, or from the left nav). Find the clone or download button and copy the git URL.

Then head to your terminal and clone your repo to your local filesystem.

git clone https://github.com/your-github-username/your-new-begin-app.git

Once you've got your project cloned on your local machine, cd into the project directory and install your dependencies:

cd your-new-begin-app
npm install

Project structure

Now that your app is live on staging and running locally, let's take a quick look into how the project itself is structured so you'll know your way around. Here are the key folders and files in the source tree of your new todo app:

.
├── public/
└── src/
    └── http/
         ├── get-todos/
         ├── post-todos/
         └── post-todos-delete/

Let's go over each of these directories and how you may use them:

`public/`

The public directory is where we host our home page: index.html. This is also where our app's CSS styles and JavaScript live. Here, we'll fetch our todos from our HTTP functions and append them to elements in the DOM while manipulating the state of our app.

`src/http/get-todos/`

The GET /todos function allows you to read the current todos from your Begin Data todos table; these items are created by way of the HTML form on the home page.

// `src/http/get-todos/index.js`

let data = require('@begin/data')

exports.handler = async function todos (req) {
  let todos = await data.get({
    table: 'todos'
  })
  // Return oldest todo first
  todos.sort((a, b) => a.created > b.created)
  return {
    statusCode: 201,
    headers: {
      'content-type': 'application/json; charset=utf8',
      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0'
    },
    body: JSON.stringify({
      todos
    })
  }
}

`src/http/post-todos/`

The POST /todos function creates or updates todos in your Begin Data todos table when input is posted from your app's HTML form.

// `src/http/post-todos/index.js`

let arc = require('@architect/functions')
let data = require('@begin/data')

exports.handler = async function post (req) {
  let todo = arc.http.helpers.bodyParser(req) // Base64 decodes + parses body
  todo.created = todo.created || Date.now()
  todo.completed = !!todo.completed
  await data.set({
    table: 'todos',
    ...todo
  })
  return {
    statusCode: 302,
    headers: {
      'location': '/',
      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0'
    }
  }
}

`src/http/post-todos-delete/`

The POST /todos/delete function deletes any of the todos from your Begin Data todos table.

// `src/http/post-todos-delete/index.js`

let arc = require('@architect/functions')
let data = require('@begin/data')

exports.handler = async function destroy (req) {
  let key = arc.http.helpers.bodyParser(req).key // Base64 decodes + parses body
  await data.destroy({
    table: 'todos',
    key
  })
  return {
    statusCode: 302,
    headers: {
      'location': '/',
      'cache-control': 'no-cache, no-store, must-revalidate, max-age=0, s-maxage=0'
    }
  }
}

Add Begin Data

First things first. We must always require Begin Data at the top of our functions. The arc variable here is used for parsing request bodies in our functions. Follow the link to learn more about parsing request bodies.

let arc = require('@architect/functions')
let data = require('@begin/data')

Begin Data API

The core Begin Data API is three methods:

data.get(params[, callback]) → [Promise] for retrieving data
data.set(params[, callback]) → [Promise] for writing data
data.destroy(params[, callback]) → [Promise] for removing data

Some additional helper methods are also available:

data.incr(params[, callback]) → [Promise] increment an attribute on an item
data.decr(params[, callback]) → [Promise] decrement an attribute on an item
data.count(params[, callback]) → [Promise] get the number of items for a given table

All methods accept an object and, optionally, a Node-style errback. If no errback is supplied, a Promise is returned (thus, all methods support async / await).

Writes

Let's start by saving a single item to a table with the set method. We identify the table with the table parameter, and can optionally specify a key:

let taco = await data.set({
  table: 'tacos',
  key: 'al-pastor'
})

Since all items have a key, if no key is specified, a unique key will automatically be generated:

let token = await data.set({
  table: 'tokens',
})
// { table: 'tokens', key: 'LCJkYX9jYWwidW50RhSU' }

We can also batch save multiple items to multiple tables by passing set an array of objects:

let collection = await data.set([
  { table: 'ppl', name:'grace', email:'ghopper@navy.mil' },
  { table: 'ppl', name:'sutr0', email:'sutr0@harbl.net' },
  { table: 'tacos', key:'pollo' },
  { table: 'tacos', key:'carnitas' }
])

Reads

Read an item by key with the get method:

let yum = await data.get({
  table: 'tacos',
  key: 'baja'
})

As with set, get can also batch-read by passing it an array of objects. With these building blocks you can construct secondary indexes and joins, like one-to-many and many-to-many!

await data.get([
  { table: 'tacos', key: 'carnitas' },
  { table: 'tacos', key: 'al-pastor' }
])

Destroy

Delete an item by key with the destroy method:

await data.destroy({
  table: 'tacos',
  key: 'pollo'
})

Yep, you guessed it: you can also batch-read delete items bypassing destroy an array of objects.

await data.destroy([
  { table: 'tacos', key: 'carnitas' },
  { table: 'tacos', key: 'al-pastor' }
])

Begin Data in action

So how do all of these HTTP functions come together to compose the core functionality of the app? This happens inside public/index.html. In your index file, the <script> contains the code doing the heavy client-side lifting. Now let's take a look a bit closer at what's going on there.

First, we fetch all the todos that currently reside on in the database. To ensure that that this fetch call always runs when the page is loaded, our business logic is immediately invoked:

// Get all todos
function init () {
  fetch('/todos', {
    credentials: 'same-origin',
    headers: {
      'Content-Type': 'application/json'
    }
  })
  .then(res => res)
  .then(body => body.json())
  // Call update with fetched todos
  .then(json => update(json.todos))
}

// Kick off the app
init()

Now we'll define a set of variables (see: document.getElementById calls) that will append the correct state and data in our DOM (see: innerHTML calls):

// Update the DOM with data
function update(todos) {
  let list = document.getElementById('js-todos')
  let completed = document.getElementById('js-completed')
  let message = document.getElementById('js-message')
  let current = todos.filter(t => !t.completed)
  let complete = todos.filter(t => t.completed)
  let doneTitle = document.getElementById('js-done-title')
  let done = complete.length && !current.length
  let none = !complete.length && !current.length
  if (none) {
    message.innerHTML = Message({
      src: '/_static/rocket.svg',
      text: 'Let\'s get started!',
      alt: 'Rocket'
    })
  } else if (done) {
    message.innerHTML = Message({
      src: '/_static/astronaut.svg',
      text: 'You did it!',
      alt: 'Astronaut'
    })
  }

  if (complete.length) {
    doneTitle.classList.toggle('display-none')
  }

  list && current.length
    ? list.innerHTML = current.map(t => Todo(t)).join('')
    : ''

  completed && complete.length
    ? completed.innerHTML = complete.map(t => Todo(t)).join('')
    : ''
}

Deploy your site

While not required, it's always a good idea to lint and run tests before pushing just to make sure you catch any errors:

npm run lint
npm t

Everything set? Now let's push this commit (and deploy the build to staging):

git add -A
git commit -am 'Just customizing my Begin site!'
git push origin master

Head on back to Begin and open your staging URL once your build is complete. Looking good? Excellent!

Now let's deploy to production: click the Deploy to production button in the upper left, pick a version, leave an optional message summarizing your changes, and Ship it!

When your next build is done, click the production link in the upper left corner to see the latest release of your app.

✨Tip: You can also deploy to production from your terminal by bumping your npm version (npm version [patch|minor|major] && git push origin) or by cutting a git tag (git tag -a 1.0.0 -m "1.0, here we come" && git push origin --tags)