A newer version of this documentation is available.

View Latest

Couchbase Tutorial: A Student Record System

      A short tutorial that will guide the developer in downloading and installing Couchbase, then creating a database to store student records.


      Couchbase is a schema-less document database engine designed for high performance, scalability, and rapid development. During this tutorial, we’ll introduce you to some key concepts behind Couchbase and how they differ from traditional SQL database systems such as MySQL and Oracle. We’re going to examine the advantages of a schema-less engine by building a document database for storing student records.

      This tutorial is designed for use with standalone or Docker installations of the Couchbase Server. If you wish to use the Couchbase Capella cloud service then you can run through the tutorials for Getting Started with Couchbase Capella.

      The Data Model

      The model will consist of three record types:


      holds the information about individual students such as name and date of birth.


      the courses that the student can take. You will need to store the course name, faculty and the number of credit points associated with the course. Against each student you will somehow need to record which of the course they are taking. Bear in mind that a student can take more than one course at a time.


      holds the information related to the course that the student is taking. In relational database, this is usually a link record that provides a relationship between the student and the course.

      So what would this database look like under a relational compared to a document model?

      Relational model

      Entity Relationship Diagram for the student record system

      Nothing too dramatic: the database contains a list of students and a list of courses. Each student can enrol on any number of courses, and the record of each of the student’s enrollments is stored in a separate table called enrollment which links to the student’s record and the courses he/she is enrolling on.

      The enrollment table highlights one of the problems with the relational database model: each table is based on a fixed schema that can only support a single data object type. You cannot store, for example, the enrollment records in the same table as the student, even though it may more natural to do so; after all, an enrollment cannot exist without a student, so why not store them together?

      Document model

      The document model gives you the same decomposition advantages as the relational model, but additionally, it also supports complex types which allows for a much more flexible design.

      Bucket, scope and collections diagram for the studen record system

      Here’s how the student record system might look as a document database.

      student record
        "student-id": "000001",
        "name": "Hilary Smith",
        "date-of-birth": "21-12-1980",
        "enrollments": [
            "course-id": "ART-HISTORY-00003",
            "date-enrolled": "07-9-2021"
            "course-id": "GRAPHIC-DESIGN-00001",
            "date-enrolled": "15-9-2021"

      The document is stored in JSON format, which allows for the storage of complex types such as arrays without decomposing them to a second table. JSON also allows the flexibility to change the structure of the document without having to rebuild schemas (as you would in a relational database system). A new field, let’s say to store email addresses, could be added to new documents without having to migrate existing data to a new schema. In this case, the list of enrollment records is stored with the student record. Each enrollment record holds a reference to the course it relates to.

      It would be a very bad idea to store the course record with each student:

      1. It would lead to massive data duplication.

      2. It would make it very difficult to maintain the data. If the credit-points for a course needed to be changed, then you would need to access every student record to make the change.

      art history course record
        "course-id": "ART-HISTORY-00003",
        "course-name": "art history",
        "faculty": "fine art",
        "credit-points" : 100
      graphic design course record
        "course-id": "GRAPHIC-DESIGN-00001",
        "course-name": "graphic design",
        "faculty": "media and communication",
        "credit-points" : 200

      Couchbase uses a document model which stores each database record as a JSON document. The document can contain both simple scalar types, and complex types such as nested records and arrays.

      Hilary’s enrollments are stored in the same document as her student details. As well as being a more natural way to store child information with its parent, this structure allows for all of Hilary’s details (enrollments included) in one search, without the need for complex table joins to retrieve the enrollment information.

      Next steps

      Okay, now that we’ve got the basic idea behind the document database model, let’s continue with a few exercises:

      Step Tutorial

      Step 1

      Install or provision the Couchbase server

      Step 2

      Buckets, Scopes and Collections

      Step 3

      Installing the Couchbase Java SDK

      Step 4

      Creating the Students Collection

      Step 5

      Creating the Courses Collection

      Step 6

      Retrieving documents

      Step 7

      Adding Course Enrollments

      It is strongly recommended that you follow the sections in order.

      In the next part of the tutorial, you’re going to begin your exploration of Couchbase by installing the Couchbase Server: Community edition.