DEV Community: Ruheni Alex

Extend your Platformatic API with Prisma Client

Ruheni Alex — Fri, 16 Dec 2022 11:22:17 +0000

In this part, you will learn how to extend the auto-generated GraphQL and REST API by Platformatic using Prisma Client.

You will create a GraphQL mutation and a REST API endpoint to increment the views on a post record.

If you're interested in learning how to use Prisma to model your database schema and auto-generate database migrations when working with Platformatic, refer to part 2 of this series.

Note: It is recommended you type out the changes over copying and pasting the code.

Prerequisites

Your dev toolbox

To follow along, ensure you have the following installed:

Node.js v18 or later
npm v7 or later
Prisma VSCode Extension (optional)
Thunder Client VSCode Extension (optional)
Docker (optional)

Note: If you don't have Docker installed, you can set up a free hosted database on Railway or install PostgreSQL.

Assumed knowledge

This guide will require you have basic familiarity in the following technologies:

JavaScript
GraphQL APIs
REST APIs

Set up your Platformatic API

The starting point of this tutorial is part 2 of this series. If you're following along from the previous part, you can jump to Extend the functionality of your API with a plugin section of this guide.

In this tutorial, you'll use the following starter repository. It contains the setup files for a new Platformatic project.

To get started, clone the repository and checkout to the automated-migrations branch.

Clone the repository:

git clone -b extend-plugin https://github.com/ruheni/prisma-platformatic.git

Now, perform the following actions to get started:

Navigate to the cloned directory:
```
cd prisma-platformatic
```
Install dependencies:
```
npm install
```
Create a .env file based-off of the .env.example file:
```
cp .env.example .env
```
Start the PostgreSQL database with docker:
```
docker-compose up -d
```
Note: If you already have an existing database server running locally, update the value of the DATABASE_URL in the .env file with your database's user and password values:
```
DATABASE_URL="postgres://<USER>:<PASSWORD>@localhost:5432/blog"
```
Connect to your database instance using psql or your preferred SQL client. Copy and run the following SQL to create a database:
```
CREATE DATABASE blog;
```

Generate an up and down migration:
```
npx db-diff
```
Apply the up migration to your database:
```
npx platformatic db migrations apply
```
Populate the database with sample data:
```
npx platformatic db seed seed.js
```

Note: If you're following along from the previous part, you can skip this step.

Generate Prisma Client:

```
npx prisma generate
```

Project structure and files

The project has the following structure:
The important files in the directory are:

.env: Contains the database connection string for your PostgreSQL database.
docker-compose.yml: Defines the Docker image and configuration for your PostgreSQL database.
package.json: Defines your application dependencies. platformatic is currently the only dependency in the project.
platformatic.db.json: Defines Platformatic's configuration such as the server's hostname and port, migration directory, and your database's connection string.
seed.js: Contains a script for populating the database with seed data.
schema.prisma: Defines the structure of your database schema.

The schema.prisma file contains two models: User and Post, with a one-to-many relation.

Extend the functionality of your API with plugins

Define the `plugin` property in your `platformatic.db.json` file

The first step is defining the plugin configuration in your platformatic.db.json file. Paste the following snippet to in your configuration file right after the migrations property:

  "plugin": {
    "path": "./plugin.js"
  }

Expand to view the entire file

{
  "server": {
    "logger":{
      "level": "info"
    },
    "hostname": "127.0.0.1",
    "port": "3042"
  },
  "core": {
    "connectionString": "{DATABASE_URL}"
  },
  "migrations": {
    "dir": "./migrations"
  },
  "plugin": {
    "path": "plugin.js"
  }
}

The snippet defines the path to your plugin. The plugin will be registered when your server starts, exposing the custom logic you've defined.

Create a plugin

At the root of your directory, create a new file called plugin.js. Paste the following snippet to your plugin file:

// ./plugin.js
module.exports = async (app) => {
  app.log.info('plugin loaded')
}

The file exports an async function with an app parameter that's a FastifyInstance.

When you you start up Platformatic with npx platformatic db start, Platformatic will register the plugin. "plugin loaded" will also be logged to your console.

With everything set up, let's take a look at how you can extend your API using Prisma Client.

Extend the GraphQL API

You'll extend the GraphQL API by defining a mutation called incrementPostViewCount. The mutation will have one argument, id that is an ID type. The mutation response type will be a Post object type.

To implement the GraphQL mutation, make the following changes to your plugin.js file:

// ./plugin.js

// 1. 
const { PrismaClient } = require("@prisma/client")

// 2
const prisma = new PrismaClient()

module.exports = async (app) => {
  app.log.info('plugin loaded')

  //3.
  app.graphql.extendSchema(`
    extend type Mutation {
      incrementPostViewCount(id: ID): Post
    }
  `)

  //4.
  app.graphql.defineResolvers({
    Mutation: {
      incrementPostViewCount: async (_, { id }) => {
        // 5. 
        const post = await prisma.post.update({
          where: {
            id: Number(id)
          },
          data: {
            viewCount: {
              increment: 1
            }
          }
        })

        // 6.
        if (!post) throw new Error(`Post with id:${id} was not found`)
        // 7.
        return post
      }
    }
  })
}

The above snippet does the following:

Imports Prisma Client.
Creates a new instance of Prisma Client.
Defines the incrementPostViewCount mutation type definition. It also defines the corresponding argument and the return type.
Defines the resolver for your mutation.
Makes a query to the database on the Post model to increment a post's view count.
Adds error handling in the event a record with the matching id was not found.
Returns the updated post on success.

As you're defining the incrementPostMutation resolver, you will notice Prisma Client provides auto-completion. On hovering on the incrementPostViewCount resolver and post variable, VS Code infers the types for you.

You can head over to http://localhost:3042/graphiql to try out the mutation you just created.

mutation INCREMENT_POST_VIEWS {
  incrementPostViewCount(id: 1){
    id 
    title
    viewCount
  }
}

Expand to view the response

{
  "data": {
    "incrementPostViewCount": {
      "id": "1",
      "title": "Prisma 💚 Platformatic",
      "viewCount": 1
    }
  }
}

Extend the REST API

Next, you'll extend the REST API by defining an endpoint that will accept PUT requests to increment the views of a post.

To implement the REST endpoint, update ./plugin.js file with the following snippet:

// ./plugin.js
const { PrismaClient } = require("@prisma/client")

const prisma = new PrismaClient()

module.exports = async (app) => {
  app.log.info('plugin loaded')

  // ...GraphQL API

  // 1. 
  app.put('/post/:id/views', async (req, reply) => {
    // 2. 
    const { id } = req.params
    // 3. 
    const post = await prisma.post.update({
      where: {
        id: Number(id)
      },
      data: {
        viewCount: {
          increment: 1
        }
      }
    })

    // 4.
    if (!post) reply.code(404).send({ error: `Post with id:${id} was not found` })
     // 5.
    return reply.send(post)
  })
}

The above code does the following:

Defines the route for incrementing a post's views.
Retrieves the id from the request parameters.
Makes a query to the database on the Post model to increment the post's view count.
Adds error handling in the event a record with the matching id was not found.
Returns the updated post on success.

Expand to see the diff

const { PrismaClient } = require("@prisma/client")

const prisma = new PrismaClient()

module.exports = async (app) => {
  app.log.info('plugin loaded')

  app.graphql.extendSchema(`
    extend type Mutation {
      incrementPostViewCount(id: ID): Post
    }
  `)

  //4.
  app.graphql.defineResolvers({
    Mutation: {
      incrementPostViewCount: async (_, { id }) => {
        // 5. 
        const post = await prisma.post.update({
          where: {
            id: Number(id)
          },
          data: {
            viewCount: {
              increment: 1
            }
          }
        })

        // 6.
        if (!post) throw new Error(`Post with id:${id} was not found`)
        // 7.
        return post
      }
    }
  })

+  // 1. 
+  app.put('/post/:id/views', async (req, reply) => {
+    // 2.
+    const { id } = req.params
+    // 3.
+    const post = await prisma.post.update({
+      where: {
+        id: Number(id)
+      },
+      data: {
+        viewCount: {
+          increment: 1
+        }
+      }
+    })
+    // 4. 
+    if (!post) reply.code(404).send({ error: `Post with id:${id} was not found` })
+    // 5. 
+    return reply.send(post)
+  })
}

You can head over to http://localhost:3042/documentation to view the Swagger docs. You should see the endpoint you just created.

To try out the endpoint you just created, you can make a request to your endpoint using curl:

curl -X PUT \
  'localhost:3042/post/2/views' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/json'

You can also use Thunder Client on VS Code to run the request. To make a request:

Open up Thunder Client on VS Code.
Create a new request by clicking New Request button on the side bar.
Select the PUT method.
Enter it to the following URL: http://localhost:3042/post/1/views.
Click Send.

You should see the following output on your editor:

Recap and next steps

Congratulations! 🎉
Using Prisma Client, you've successfully extended the GraphQL and REST APIs generated with Platformatic API.

In case you missed it, check out part 2 to learn how you can use Prisma to:

Model your database schema
Auto-generate fully customizable SQL migrations

You can find the source code for this project on GitHub. If you run into any challenges, feel free to create a GitHub issue or contribute to the repository. You can also reach out to me directly on Twitter

Friendly data modeling & auto-generated, editable migrations for Platformatic with Prisma

Ruheni Alex — Thu, 15 Dec 2022 09:38:54 +0000

A wise man once said...

... that was me.

But all jokes and memes aside, automation helps cut down the amount of time spent on tedious and repetitive tasks.

This guide will teach you how to model your database schema and auto-generate customizable SQL migrations using Prisma when working with Platformatic.

Prerequisites

Your dev toolbox

To follow along, ensure you have the following installed:

Node.js v16.17.0
npm v7 or later
Prisma VSCode Extension (optional)
Thunder Client VSCode Extension (optional)
Docker (optional)

Note: If you don't have Docker installed, you can set up a free hosted database on Railway or install PostgreSQL.

Assumed knowledge

This guide will require you to have basic familiarity with the following technologies:

JavaScript
GraphQL APIs
REST APIs

Set up your Platformatic app

In this tutorial, you'll use the following starter repository. It contains the setup files for a new Platformatic project.

To get started, clone the repository and checkout to the automated-migrations branch.

Clone the repository:



git clone -b automated-migrations https://github.com/ruheni/prisma-platformatic.git

Now, perform the following actions to get started:

Navigate to the cloned directory:
```
cd prisma-platformatic
```


1. Install dependencies:

    ```bash


    npm install

Create a .env file based-off of the .env.example file:
```
cp .env.example .env
```


1. Start the PostgreSQL database with docker:

    ```


    docker-compose up -d

Note: If you already have an existing database server running locally, update the value of the DATABASE_URL in your .env file with your database's user and password values:
# .env
DATABASE_URL="postgres://<USER>:<PASSWORD>@localhost:5432/blog"
Connect to your database instance using psql or your preferred SQL client. Copy and run the following SQL to create a database:
CREATE DATABASE blog;

Project structure and files

The project has the following structure:



prisma-platformatic
  ├── .env.example
  ├── .env
  ├── .gitignore
  ├── README.md
  ├── docker-compose.yml
  ├── package-lock.json
  ├── package.json
  └── platformatic.db.json

The noteworthy files in the directory are:

.env: Contains the database connection string for your PostgreSQL database.
docker-compose.yml: Defines the Docker image and configuration for your PostgreSQL database.
package.json: Defines your application dependencies. platformatic is currently the only dependency in the project.
platformatic.db.json: Defines Platformatic's configuration such as the server's hostname and port, migration directory, and your database's connection string.

Data modeling and automated migrations

Now that you've set up your application, it's time to get your hands dirty with Prisma!

Set Prisma in your project

To get started, first install the Prisma CLI as a development dependency in your project:



npm install prisma --save-dev

The Prisma CLI provides the tools that allow you to evolve your database schema in your project.

You can now initialize Prisma in your project with the following command:



npx prisma init

The command creates a prisma folder at the root containing a schema.prisma file. The schema.prisma file serves as a source of truth for your database schema.

When you open up the schema.prisma file, you should see the following:



// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgres"
  url      = env("DATABASE_URL")
}

The Prisma schema uses an intuitive and human-readable language called the Prisma Schema language.

The schema file is composed of three main components:

Data source: Defines your database connection details such as the provider and database's connection string.
Generator: Defines the assets generated when specific Prisma commands are invoked. In this case, Prisma Client, a type-safe query builder for your database, will be generated.
Data model: Defines the entities of your application that map to your database's tables (for relational databases) or collections (MongoDB). The schema doesn't have any yet, but models are denoted with the model keyword, followed by the entity name.

Model your database schema

For this guide, you will create a Post model with the following fields in your schema.prisma file:



// ./prisma/schema.prisma
model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  viewCount Int      @default(0)
  createdAt DateTime @default(now())
}

The snippet above defines a model called Post with the following fields and properties:

id: An auto-incrementing integer that will be the primary key for the model.
title: A non-null String field.
content: A nullable String field.
published: A Boolean field with a default value of false.
viewCount: An Int field with a default value of 0.
createdAt: A DateTime field with a timestamp of when the value is created as its default value.

Refer to the Prisma documentation for further details on how to model your data using Prisma.

Generate a migration with `migrate diff`

With the schema defined, you will now auto-generate a database migration using prisma migrate diff.

prisma migrate diff compares (or "diffs") two schemas, the current, and the anticipated version. The current version is the from state, and the anticipated version is the to state. The command generates a SQL script describing the changes.

Fun fact: If you've used the prisma migrate dev command before, it runs prisma migrate diff under the hood.

The command, prisma migrate diff accepts the following schema sources for comparison:

A live database
A migration history
Schema data model (defined in the Prisma schema)
An empty schema

The prisma migrate diff command will use the following arguments to generate a migration:

--from-schema-datasource: Uses the URL defined in the datasource block.
--to-schema-datamodel: Uses the data model defined in the Prisma schema for the diff.
--script (optional): Outputs a SQL script.

The --from-schema-datasource and --to-schema-datamodel also require a path to your Prisma schema file.

Create the migrations directory that you will use to store a history of migrations:



mkdir migrations

The migrations directory is used by Platformatic to store and track the history of applied migrations.

Next, open up a terminal within your project directory run the following command to auto-generate your first migration:



npx prisma migrate diff \
--from-schema-datasource ./prisma/schema.prisma \
--to-schema-datamodel ./prisma/schema.prisma \
--script > migrations/001.do.sql \
--exit-code

Notes:

Update the output filename for any future migrations to prevent overwriting the contents of 001.do.sql

You can jump to the Side quest section to learn how you can automate versioning and generating migrations with the @ruheni/db-diff utility library

If you omit the --script argument, the command will generate a human-readable summary that looks something like this: ```

[+] Added tables

Post

The command creates a file called 001.do.sql inside the migrations directory with the following contents:



-- migrations/001.do.sql
-- CreateTable
CREATE TABLE "Post" (
    "id" SERIAL NOT NULL,
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "title" TEXT NOT NULL,
    "content" TEXT,
    "published" BOOLEAN NOT NULL DEFAULT false,
    "viewCount" INTEGER NOT NULL DEFAULT 0,

    CONSTRAINT "Post_pkey" PRIMARY KEY ("id")
);

You'll notice that the command generated the SQL that describes the changes you defined in the Prisma schema file.

Start your API server

In your project directory, apply the migrations to your database using the Platformatic CLI:



npx platformatic db migrations apply

Next, start up your API server:



npx platformatic db start

The command will:

Start the Platformatic API server
Auto-generate a REST and GraphQL API from your SQL database

Explore and interact with your API

You can now explore your GraphQL API on http://localhost:3042/graphiql or your REST API on http://localhost:3042/documentation.

Run the following mutation on GraphiQL to insert a record in your database:



mutation INSERT_POST {
  insertPost(
    inputs: {
      title: "Prisma 💚 Platformatic"
      content: "Learn how you can auto-generate your database migrations using Prisma for Platformatic"
    }
  ) {
    id
    title
    content
    createdAt
    published
  }
}

You should see the following output with a different createdAt value:



{
  "data": {
    "insertPost": [
      {
        "id": "1",
        "title": "Prisma 💚 Platformatic",
        "content": "Learn how you can auto-generate your database migrations using Prisma for Platformatic",
        "createdAt": "2022-10-08T14:26:08.101Z",
        "published": false
      }
    ]
  }
}

Congratulations! 🎉

Introspect your database for the `versions` model

Under the hood, Platformatic uses Postgrator to run migrations. Postgrator creates a table in the database called versions to track the applied migrations.

The versions table is not yet captured in the Prisma schema. When auto-generating future migrations, Prisma might prompt you to drop the versions table, which is not ideal.

To prevent this, you can run prisma db pull to introspect the database and populate the Prisma schema with the missing model:



npx prisma db pull

Your Prisma schema should now contain a version model:



// ./prisma/schema.prisma
model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  viewCount Int      @default(0)
  createdAt DateTime @default(now())
}

+model versions {
+  version BigInt    @id
+  name    String?
+  md5     String?
+  run_at  DateTime? @db.Timestamptz(6)
+}

Add the @@ignore attribute function to the model to exclude it from the Prisma Client API:



// ./prisma/schema.prisma
model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  viewCount Int      @default(0)
  createdAt DateTime @default(now())
}

model versions {
  version BigInt    @id
  name    String?
  md5     String?
  run_at  DateTime? @db.Timestamptz(6)
+
+  @@ignore
}

Side quest 🧙🏽: Automate versioning and generation of your database migrations

The approach for generating migrations in the previous section generally works fine. The only caveat is that you have to manually specify the version of the migration file with every migration, i.e., 001.do.sql, 002.do.sql, and so forth.

Another friction point is that the command is very long, tedious and there is a possibility of making an error.

To get around these friction points, I built a utility library called @ruheni/db-diff. The tool wraps around the prisma migrate diff command. It can generate an up and a down migration. @ruheni/db-diff also versions the generated migration file and are Postgrator-compatible. On top of that, you can generate an up and down migration for every schema change.

Alternatively, you can also use platformatic-prisma by Kishan Gajera

Install the helper utility

To get started, you can install @ruheni/db-diff as a development dependency in your project:



npm install --save-dev @ruheni/db-diff

Update your schema

Next, update your Prisma schema by creating a User model with the following fields:

id: the primary key with an auto-incrementing integer
email: a string value with a @unique constraint
name: a string value (nullable/ not-required)
posts: a one-to-many relationship between the Post and User models, respectively

Your Prisma schema should resemble the schema in the code block below:



// ./prisma/schema.prisma
model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id        Int      @id @default(autoincrement())
  createdAt DateTime @default(now())
  title     String
  content   String?
  published Boolean  @default(false)
  viewCount Int      @default(0)
  author    User?    @relation(fields: [authorId], references: [id])
  authorId  Int?
}

model versions {
  version BigInt    @id
  name    String?
  md5     String?
  run_at  DateTime? @db.Timestamptz(6)

  @@ignore
}

Expand here to see the schema diff



// ./prisma/schema.prisma
+model User {
+  id    Int     @id @default(autoincrement())
+  email String  @unique
+  name  String?
+  posts Post[]
+}

model Post {
  id        Int      @id @default(autoincrement())
  createdAt DateTime @default(now())
  title     String
  content   String?
  published Boolean  @default(false)
  viewCount Int      @default(0)
+  author    User?    @relation(fields: [authorId], references: [id])
+  authorId  Int?
}

model versions {
  version BigInt    @id
  name    String?
  md5     String?
  run_at  DateTime? @db.Timestamptz(6)

  @@ignore
}

Auto-generate an `up` migration using `@ruheni/db-diff`

Next, use @ruheni/db-diff to auto-generate an up migration:



npx db-diff --up

The command should generate a new file called 002.do.sql with the following contents:



-- migrations/002.do.sql
-- AlterTable
ALTER TABLE "Post" ADD COLUMN     "authorId" INTEGER;

-- CreateTable
CREATE TABLE "User" (
    "id" SERIAL NOT NULL,
    "email" TEXT NOT NULL,
    "name" TEXT,

    CONSTRAINT "User_pkey" PRIMARY KEY ("id")
);

-- CreateIndex
CREATE UNIQUE INDEX "User_email_key" ON "User"("email");

-- AddForeignKey
ALTER TABLE "Post" ADD CONSTRAINT "Post_authorId_fkey" FOREIGN KEY ("authorId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;

You can specify the type of migration you would like to generate by passing either --up for only the up migration or --down for the down migration.

@ruheni/db-diff utility library will auto-generate an up and a down migration if you don't provide either the --up or --down flags. If you maintain down migrations, ensure the migration version name is at par with the up migration.

Apply the generated migration using Platformatic CLI:



npx platformatic db migrations apply

Restart and interact with your API using Platformatic

Restart the API server:



npx platformatic db start

Platformatic will regenerate the GraphQL and REST APIs.

Open up GraphiQL on http://localhost:3042/graphiql and run the following mutation to create a user record in your database:



mutation INSERT_USER {
  insertUser(inputs: { name: "Alex", email: "alex@prisma.io" }) {
    id
    name
  }
}

Expand to view the response



{
  "data": {
    "insertUser": [
      {
        "id": "1",
        "name": "Alex"
      }
    ]
  }
}

Run another query to link the user record with the existing post record you created in a previous step:



mutation SAVE_POST {
  savePost(input: { id: 1, authorId: 1 }) {
    id
    title
    content
    author {
      name
    }
  }
}

Expand to view the response



{
  "data": {
    "savePost": {
      "id": "1",
      "title": "Prisma 💚 Platformatic",
      "content": "Learn how you can auto-generate your database migrations using Prisma for Platformatic",
      "user": {
        "name": "Alex"
      }
    }
  }
}

And you're all done! 🎉

Wrapping up

To recap what was covered in this part, you:

Modeled your database schema using Prisma
Used the prisma migrate diff to auto-generate your SQL migrations
Created a GraphQL and REST API using Platformatic
Used the @ruheni/db-diff utility to auto-generate and version your SQL migrations

The next article will cover how you can extend the generated GraphQL and REST API using Prisma Client.

Feel free to refer to prisma migrate diff reference docs to learn how you can use it to automate your database migration workflows. If you build something cool you would like to share with the rest of the world, feel free to share it in this GitHub discussion thread.

In the event you run into any issues working with @ruheni/db-diff, feel free to create a GitHub issue or contribute to the library.

Happy hacking! 🚀

Why Prisma and Platformatic are a great match

Ruheni Alex — Wed, 14 Dec 2022 11:27:35 +0000

Platformatic is a new tool that helps Node.js developers ship APIs faster. In this 3-part series, we’ll explore why Prisma and Platformatic are such a great fit and how Prisma can help improve your data modeling, migrations, and querying workflows when using Platformatic.

What is Platformatic DB

Platformatic DB is an open-source tool that auto-generates CRUD APIs for your database. It supports both GraphQL and REST (with an OpenAPI schema) APIs.

It also allows you to extend the API using plugins and add authentication as well as authorization for your APIs. Platformatic DB supports SQLite, MySQL, MariaDB, and PostgreSQL databases.

What is Prisma

Prisma is an open-source ORM (Object Relational Mapper). It provides a declarative way to define the structure of your database using the Prisma schema language. It also provides tools for evolving your database schema by auto-generating fully customizable SQL migrations.

Prisma provides a type-safe and intuitive client for interacting with your database called Prisma Client.

How Prisma can improve your development workflow with Platformatic DB

While Platformatic speeds up building REST and GraphQL APIs from your database, Prisma can complement your development workflow in several ways.

In the following sections, we'll explore three concrete ways Prisma makes working with Platformatic DB easier.

Intuitive data modeling language

Prisma provides a Prisma schema — an intuitive, human-readable declarative definition of your database schema. The Prisma schema serves as the source of truth for your database schema by describing its desired end state.

One of the benefits of using the Prisma schema is the auto-completion, with the help of the Prisma extension, and type-checking when modeling your database schema, allowing you to catch errors early.

The following schema represents:

User and Post models
A one-to-many relationship between the User and Post models

model User {
  id        Int      @id @default(autoincrement())
  createdAt DateTime @default(now())
  name      String?
  email     String   @unique

  posts     Post[]
}

model Post {
  id        Int      @id @default(autoincrement())
  createdAt DateTime @default(now())
  title     String
  content   String
  published Boolean  @default(false)

  author    User?    @relation(fields: [authorId], references: [id])
  authorId  Int?
}

Refer to the Prisma docs to learn more about data modeling.

Auto-generated and customizable SQL migrations

To generate your API with Platformatic, you must first define your database schema. The database schema is defined using SQL in a set of migrations files that are written manually. However, maintaining SQL migrations by hand can be tedious, brittle, and error-prone.

// Detect dark theme var iframe = document.getElementById('tweet-1575443725047812098-340'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1575443725047812098&theme=dark" }

I also think writing your own migrations introduces risk for user error like forgetting to create a foreign key.

Kishan Gajera from Generate Up and Down Migrations for Platformatic DB using Prisma

Editors typically don't provide auto-completion and type-checking when working with SQL. This might make it challenging to spot errors such as missing constraints like foreign keys.

Prisma can help automate this process by generating a fully-customizable migration based on the defined schema using the CLI.

The following SQL migration will be generated based on the schema in the previous section:

-- CreateTable
CREATE TABLE "User" (
    "id" SERIAL NOT NULL,
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "email" TEXT NOT NULL,
    "name" TEXT,

    CONSTRAINT "User_pkey" PRIMARY KEY ("id")
);

-- CreateTable
CREATE TABLE "Post" (
    "id" SERIAL NOT NULL,
    "title" VARCHAR(255) NOT NULL,
    "content" TEXT NOT NULL,
    "published" BOOLEAN NOT NULL DEFAULT false,
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "authorId" INTEGER,

    CONSTRAINT "Post_pkey" PRIMARY KEY ("id")
);

-- CreateIndex
CREATE UNIQUE INDEX "User_email_key" ON "User"("email");

-- AddForeignKey
ALTER TABLE "Post" ADD CONSTRAINT "Post_authorId_fkey" FOREIGN KEY ("authorId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;

Type-safety and auto-completion for database queries

Platformatic provides plugins for extending your API. It also provides a SQL mapper for querying the database.

Besides the out-of-the-box SQL mapper, you can alternatively extend your Platformatic API using Prisma Client to query your database. Prisma Client provides fully type-safe queries with rich type definitions based on your Prisma schema.

Platformatic also provides TypeScript support. You can use the CLI to generate TypeScript types for your entities from your database.

If you're working with the VS Code editor, VS Code's intellisense and suggestions will pop up as you define your queries.

Additionally, VS Code can also run your JavaScript file, which uses Prisma Client through the TypeScript compiler and throws errors when a type is violated.

Learn more how you can write type-safe JavaScript with JsDoc in this article

Wrapping up

Platformatic speeds up the development of REST and GraphQL APIs. Prisma pushes the development experience even further by providing intuitive data modeling, auto-generating customizable migrations, type-safety, and auto-completion.

Look out for parts 2 and 3 — modeling, auto-generating database migrations, and extending your API using a plugin with Prisma Client for Platformatic. 🤙🏾

Data modeling – Table Inheritance

Ruheni Alex — Tue, 23 Nov 2021 00:00:00 +0000

Modeling data is challenging. Well, at least I find it hard because of database normalization and the ever-changing database schemas.

This article will cover table inheritance: what it is, where it likely came from, an example challenge, the different patterns with their pros and cons. Most of it will be theoretical, but I will do my best to include the relevant SQL for the examples.

In this article, I will refer to database tables as an Entity and a column in a table as an Attribute. The SQL snippets will also be PostgreSQL specific.

So, let's jump into it.

Meet the family

Inheritance is an Object-Oriented Programming (OOP) pattern where a class (child) acquires properties of another class (parent). The inheritance between different classes creates a hierarchy/ tree from which you can draw a relationship between the classes.

This presents an advantage – reducing redundancy redefining a parent class' attribute in the child class.

Relational databases, however, were not designed to be object-oriented – except for PostgreSQL that supports inheritance.

Object Relational Mappers (ORMs) created an abstraction over databases, allowing you to model tables in your database as you would define entities/ objects/ classes instead of writing SQL by hand. The advantage this creates is that it creates a simple way to conceptualize your database. My hunch is that table inheritance was introduced by ORMs

A visit to the bank 💰

A customer in a bank has an Account. A customer can be a person or a company. This also means a bank would support different types of accounts: CompanyAccount and a SavingsAccount – to keep this analogy simple.The 2 types of accounts will have shared attributes – id, address, name – and unique properties – company name, owners etc.

How would you model this sort of data?

One option is table inheritance. There are 3 different forms of inheritance that you can use:

Single Table Inheritance
Concrete Table Inheritance
Class Table Inheritance

Single Table Inheritance

Ironically, Single Table Inheritance doesn't inform any form of inheritance when modeling tables using SQL. This is a conceptual model introduced by ORMs.

You would create your parent entity Account that would contain all the shared attributes. The child entities CompanyAccount and SavingsAccount would inherit the parent entity's attributes and define their own attributes.

To differentiate the child entities a type or discriminator property is introduced in the parent entity which is a string value.

class Account {
    // define the attributes here
    type: string // "CompanyAccount" or "SavingsAccount"
}

class CompanyAccount extends Account {
    // define the attributes here
    signatories: Json
}

class SavingsAccount extends Account { 
    // define the attributes here
    signatory: string
}

However, at the database level, only one table – Account – is created. All the attributes of the child entities would be added to the Account table and marked as nullable or NULL.

CREATE TABLE "Account" (
    "id" SERIAL NOT NULL,
    "balance" DOUBLE PRECISION NOT NULL,
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "type" TEXT NOT NULL,

    -- SavingsAccount specific field
    "signatory" TEXT,

    -- CorporateAccount specific field
    "signatories" JSONB,


    CONSTRAINT "Account_pkey" PRIMARY KEY ("id")
);

CREATE INDEX "account_type_index" on "content" ("type");

This approach would be considered okay if there are few child entities inheriting from Account.

Single Table Inheritance wouldn't scale well because:

Depending on the number of attributes from child entities, there would be many NULL fields.
Adding a new class would make this difficult to maintain.

Concrete Table Inheritance

The Concrete Table Inheritance pattern takes a slightly different approach when creating tables in the database.

The parent entity would serve as a template from which child entities would inherit. However, in this instance, the parent entity isn't created in the database.

The plus sides for this approach include:

Child entities will have individual tables and won't store attributes of other child entities.
Mandatory fields of the child entity would be enforced with the NOT NULL constraint.
No type column in the parent entity to determine the type of child entity

Some downsides are:

Modeling using SQL would be very repetitive when defining attributes from the parent entity every time you'd create a child entity
Searching through all child entities would require a UNION on child tables

The SQL for Concrete Table Inheritance would resemble this:

CREATE TABLE "SavingsAccount" (
    "id" SERIAL NOT NULL,
    "balance" DOUBLE PRECISION NOT NULL,
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "signatory" TEXT NOT NULL,

    CONSTRAINT "SavingsAccount_pkey" PRIMARY KEY ("id")
);

CREATE TABLE "CorporateAccount" (
    "id" SERIAL NOT NULL,
    "balance" DOUBLE PRECISION NOT NULL,
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "signatories" JSONB NOT NULL,

    CONSTRAINT "CorporateAccount_pkey" PRIMARY KEY ("id")
);

PostgreSQL supports the INHERITS keyword that takes care of inheritance. The only difference is that the parent entity is also created in the database

CREATE TABLE ACCOUNT (
--- Base table properties here
);
CREATE TABLE CORPORATE_ACCOUNT (
--- Specific table properties
) INHERITS(ACCOUNT);
CREATE TABLE SAVINGS_ACCOUNT (
--- Specific table properties
) INHERITS(ACCOUNT);

Class Table Inheritance

Class Table inheritance resembles Classes in OOP and takes the best of both worlds.

The parent entity would have its own table and any child entity would have a 1-1 relationship with the parent. The ID of the child entity would serve as a foreign key in the parent entity.

Example Entity Relationship Diagram:

SQL

-- CreateTable
CREATE TABLE "Account" (
    "id" SERIAL NOT NULL,
    "balance" DOUBLE PRECISION NOT NULL,
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "savingsAccountId" INTEGER NOT NULL,
    "corporateAccountId" INTEGER NOT NULL,

    CONSTRAINT "Account_pkey" PRIMARY KEY ("id")
);

-- CreateTable
CREATE TABLE "SavingsAccount" (
    "id" SERIAL NOT NULL,
    "signatory" TEXT NOT NULL,
    "accountId" INTEGER,

    CONSTRAINT "SavingsAccount_pkey" PRIMARY KEY ("id")
);

-- CreateTable
CREATE TABLE "CorporateAccount" (
    "id" SERIAL NOT NULL,
    "signatories" JSONB NOT NULL,
    "accountId" INTEGER,

    CONSTRAINT "CorporateAccount_pkey" PRIMARY KEY ("id")
);

-- CreateIndex
CREATE UNIQUE INDEX "Account_savingsAccountId_key" ON "Account"("savingsAccountId");

-- CreateIndex
CREATE UNIQUE INDEX "Account_corporateAccountId_key" ON "Account"("corporateAccountId");

The advantages of this approach are:

It is DRY
No type column in the parent entity to determine the type of child entity
Searching through tables is easier – no UNIONs
There is no risk of child entities having attributes of other child entities.

It's not all roses with this approach. Some of the disadvantages are:

You wouldn't be able to determine the type of a child entity without querying them. However, if you're using an ORM is a non-issue
It can be hard keeping the parent and child entities in sync using triggers.

Conclusion

The take away of this article is there's no one-size fits all approach when modeling entities in your database. Some have work well, and others... don't. What's important is doing the appropriate research in your domain and modeling data from that. Even this won't be enough as you will have to iterate on your database schema over and over again.

You can read more in Patterns of Enterprise Application Architecture by Martin Fowler.

Database Migrations for .NET and Entity Framework with Prisma

Ruheni Alex — Thu, 04 Nov 2021 12:51:58 +0000

Introduction

In this article, you will learn how to model your data using Prisma, run a migration with Prisma Migrate and then introspect your database with .NET to generate your Entity Framework models. This article will use Azure SQL/ SQL Server.

This article only offers an alternative data modelling workflow that is succinct and offer a better development experience. Besides .NET and the Entity framework, you can also use Prisma with your tool/ frameworks of choice such as Django.

Prisma auto-generates migration files in SQL that you can modify before applying them on your database. The workflow following this approach would be:

Model your data
Run a migration using Prisma Migrate.
Use the Entity Framework to reverse engineer/ scaffold/ introspect your database and generate models and your database context.

What is Prisma?

Prisma is an object-relational mapper (ORM) that provides a declarative way to define your database models that are easy to read and comprehend. Prisma also provides Prisma Client – an intuitive and type-safe query builder based off your schema.

At the core of Prisma is the Prisma Schema – aka schema file. The schema contains 3 parts: the data sources, generators and your data model definition.

Prerequisites

To follow along, ensure you have the following:

Familiarity with .NET and the Entity framework
Installed Node.js v 12.6.x or higher
Installed .NET locally
A SQL Server or Azure SQL database
Prisma Extension for VS Code users

Note: If you're not familiar with setting up SQL Server, check out Setting up a local SQL Server database.

Step 1: Create a new console application

The first step is to create a new .NET console app in your working directory. This guide uses a console application to keep it simple. However, feel free to create any other type of application.



dotnet new console --output *__app-name__*

Once the command is done, navigate to the project and confirm that your project is running.



cd *__app-name__*
dotnet run

If the output on the terminal is Hello World!, everything seems to be running just fine! 🎉

Step 2: Add Prisma to your project

On a separate terminal window but still within the same project run the following commands.



mkdir prisma-migrate
cd prisma-migrate
npm init -y

The commands create a new directory, navigate to the folder and initializes it as a Node.js project. The Prisma CLI is the only dependency for this project.



npm install --save-dev prisma

Initialize Prisma

Once the install is done, run the following command.



npx prisma init --database-provider sqlserver

The command:

Creates a .env file at the root of the project for storing environment variables
Creates prisma folder containing a schema.prisma file.
Specifies the database provider as sqlserver in schema.prisma file and provides a dummy sqlserver connection string in .env.

The schema.prisma file defines the database connection and the Prisma Client generator. This is where you will also define your database models.



/// prisma/schema.prisma
datasource db {
  provider = "sqlserver"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

For this guide, you can delete generator client as it is relevant in a TypeScript/ JavaScript project. The generator client is used to generate the TypeScript definitions for the Prisma Client.

Update .env with your database connection string. Refer to connection details for information on how to configure the connection string.



# .env
DATABASE_URL="sqlserver://HOST:PORT;database=DATABASE;user=USER;password=PASSWORD;"

If you're using a remote database during development like Azure SQL, open this to learn more about how to configure the shadow database.
Create a new database which will be the shadow database on Azure. Update your .env file to include the SHADOW_DATABASE_URL as well. The shadow database will be used in the data modelling step



# .env
DATABASE_URL="sqlserver://HOST:PORT;database=DATABASE;user=USER;password=PASSWORD;"
SHADOW_DATABASE_URL="sqlserver://HOST:PORT;database=DATABASE;user=USER;password=PASSWORD;"

Update your schema.prisma file with the connection string for the shadow database.



/// prisma/schema.prisma
datasource db {
  provider          = "sqlserver"
  url               = env("DATABASE_URL")
  shadowDatabaseUrl = env("SHADOW_DATABASE_URL")
}

A shadow database is a second, temporary database for use in the local development workflow. When running a migration, the secondary database is created and deleted automatically unless you're using a cloud-hosted database.

Here's an illustration of how the shadow database works:

Data modelling

This example will define 2 models: Post and User.The relationship between User and Post is a one-to-many relationship.

The models defined in schema.prisma will resemble a GraphQL syntax . The models also map to a table in your database.



/// prisma/schema.prisma
model Post {
  id        Int      @id @default(autoincrement())
  content   String?
  title     String
  createdAt DateTime @default(now())
  author    User?    @relation(fields: [authorId], references: [id])
  authorId  Int?
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

Refer to the Prisma Schema Reference for further information on database field types, attributes, conventions and functions.

Create a database migration

After modelling your data, it's time to apply the changes to your database. On your terminal window, run npx prisma migrate dev.



npx prisma migrate dev --name init

If no database exists, a new database with the database name specified in your .env file will be created. The command also creates a new database migration that is located in ./prisma/migrations directory. The migration is in SQL and is applied against your database. init refers to the migration name which you can change to something more semantic.

If you wish to only create a migration but not apply it to your database, pass the --create-only option to Prisma Migrate. This will generate the SQL and allow you to customize it before applying it against your database.

You can confirm that the changes have been applied, run:



npx prisma studio

Select the Model you would like to view/ edit data.

Click Save 1 change to apply the changes.

Navigate to the User model, create a new user, link the post created in the previous step and save the change.

Step 3: Introspect your database aka Reverse Engineering

Entity framework allows you to introspect your database schema and scaffold entity type classes and the database context based off an existing database.

Navigate out of prisma-migrate directory to the root of your project.



cd ../

Install Entity Framework tools you will require to work with SQL Server in your project.



dotnet add package Microsoft.EntityFrameworkCore.SqlServer 
dotnet add package Microsoft.EntityFrameworkCore.Tools 
dotnet add package Microsoft.EntityFrameworkCore.Design

Scaffold entity type classes based on your database schema to your project.



dotnet ef dbcontext scaffold "Server=**HOST**;Database=**DATABASE_NAME**;User Id=**USER**;Password=**PASSWORD**" Microsoft.EntityFrameworkCore.SqlServer --context-dir DbContext --context BlogExampleContext --output-dir Models

Microsoft.EntityFrameworkCore.SqlServer refers to the package to be used to introspect the database.
--context-dir and --output-dir refer to the location of the context and the entity type classes after introspection
--context refers to the name of your database context

On a successful run 2 folders with 4 files will be created in your project.



*app-name*/
┣ DbContext/
┃ ┗ BlogExampleContext.cs
┣ Models/
┃ ┣ Post.cs
┃ ┗ PrismaMigration.cs
┃ ┗ User.cs
┣ ...

As you will notice, PrismaMigration.cs was not defined in schema.prisma. This is a table created by Prisma to track the migrations that have been created and applied against your database.

To exclude the PrismaMigrations table, and re-run the previous command but specify the tables you would like using the --table and —force options to overwrite the existing models.



dotnet ef dbcontext scaffold "Server=**HOST**;Database=**DATABASE_NAME**;User Id=**USER**;Password=**PASSWORD**" Microsoft.EntityFrameworkCore.SqlServer --context-dir DbContext --context BlogExampleContext --output-dir Models --force --table User --table Post

This time, 3 files are generated and the PrismaMigrations.cs file is excluded when scaffolding.

If you're interested in migrating to Prisma with an existing database, the Prisma CLI provides db pull for introspecting the database and populating schema.prisma with your database models.

Conclusion

Congratulations! You have successfully modelled your entities, run a migration with Prisma and scaffolded your models and context with Entity Framework.

Learn how you can set up and deploy a Prisma based Node.js REST API to Azure Functions together with Azure SQL in Deploying to Azure Functions.

If you would like to learn more about Prisma, check out the documentation and feel free to create an issue or start a discussion on GitHub.

SE Internship Log[5]

Ruheni Alex — Tue, 07 Sep 2021 07:14:32 +0000

This week, I tackled an interesting challenge revealing knowledge gaps – executing an exported function in a TypeScript file without calling it within the file and working with the Node CLI.

For most of the application code, you may write, you may never have to learn such concepts because, in software, we have A LOT of abstractions – mainly in the form of npm packages for fellow JavaScript Developers.

But if you're building systems for other systems to run on, you have to dive deeper and learn the abstractions are.

Context - how seeding in Prisma works

The task involved writing a script would end up being part of a mini-test-suite to ensure that the instructions a user followed wouldn't lead to an error.

One of the steps was seeding a database in a Prisma project. The Prisma CLI exposes a seed command, but at the time of writing this, it's a preview-feature and its implementation is being redesigned.

The default way of executing a function in a file is by calling it. It just works. The stable implementation of seeding currently works as follows:

function main(){
  /** your seeding logic */
}

main()
  .catch((e) => {
    console.error(e);
    process.exit(1);
  })
  .finally(async () => {
    await prisma.$disconnect();
  });

Running npx prisma db seed --preview-feature would successfully seed your database with the above code example

But... seeding was using a different implementation of the seed command that the Prisma CLI supports – executing seed function with a default exported seed() or exported seed() function in your ./prisma/seed.ts file:

export default function seed (){
    /** your logic */
}
// OR

export function seed(){
  /** your logic */
}

Running npx prisma db seed --preview-feature would work just okay but it isn't always guaranteed to work perfectly. Occasionally, prisma db seed encounters an error but won't throw an error – indicating a false positive.

The solution

ts-node 🎉

ts-node is a handy tool for transpiling/ transforming TypeScript into JavaScript.

Unlike the first main() seeding example, the seed() function isn't called. Running npx ts-node ./prisma/seed would only transform the file checking for type errors.

ts-node exposes the --eval/ -e flag from the Node CLI. The --eval flag accepts a script argument which is valid TypeScript/ JavaScript code. For It has to be valid JavaScript in the case of Node.js.

You can execute the seed() function with the following command:

npx ts-node -e "import seed from './prisma/seed'; seed()"

OR:

npx ts-node -e "import {seed} from './prisma/seed'; seed()"

As the command is being executed, --eval creates a "sandbox" – the Node.js REPL (Read-Eval-Print-Loop) – where the code is executed.

Note: You can execute exported functions in your TypeScript project following the above command. E.g.

// path - ./src/starWars.ts
export function fetchStarWarsMovies(){
  try{
    /** logic here */
  } catch (error){
    /** error handling */
  }
}

yarn ts-node -e "import {fetchStarWarsMovies} from './src/starWars'; fetchStarWarsMovies()"

Besides --eval flag, you can also use the --print/-p. --print is similar to --eval but prints the output on the console.

Learning about --eval and --print flag in ts-node and Node.js showed me there's a whole mountain of tools/ software to learn out there. Abstractions are grand, but every once in a while, it's a good idea to understand how to use them instead of installing another npm package :troll_face:

I hope you enjoyed this article. If you have any comments or feedback, my Twitter DM is open.

Till next week. ✌🏽

SE Internship Log[4]

Ruheni Alex — Mon, 23 Aug 2021 10:16:49 +0000

Hello there internet stranger, 👋🏽

Welcome to the 5th edition of the Software Engineering(SE) Log.

This week was frustrating. I spent the week trying to debug a test that failed 1-3 times a day (a cron job that runs on an hourly basis).

When does it fail? Anytime.

Why does it fail? The response data is 0 instead of 20(expectation).

Why is it 0? No freakin' clue. 🥲

Hopefully, the upcoming week will be better than the previous one.

Enough with the rant. This week, I learned a bunch of stuff – re-thinking performance, Next.js measuring performance, label-sync, and being proactive.

Technical Skills

Re-thinking performance

This won't be about bloated JavaScript bundles or optimizing. I'm not an expert.

This week, I got a comment on a PR for a task I was working on that I was making an expensive API call – introspecting the user's database checking for any tables.

No big deal? Well, it is. This operation would happen every time a user opens a project.

This changed how I think about API requests from the frontend in terms of:

Cost
User experience.
Compute required to make a task happen – on the API, and the user's resources which in this case is their database

Just because you can do something doesn't mean you should. Compute resources are finite. Evaluate the impact of the requests you make and how you can cut down on what isn't necessary.

Next.js Measuring performance

Vercel provides analytics on application performance for different stacks – Next.js included.

Next.js can provide tooling that allows you to measure analytics and use your own custom analytics.

The metrics that Next.js allows you to track include:

Web Vitals - these metrics measure and report the performance of your application to ensure you're delivering a great user experience.

Custom Metrics - this is specific to Next.js measuring the time taken for a page to hydrate and render:
- Next.js-hydration - time take for a page to start and finish hydrating
- Next.js-route-change-to-render - time taken for a page to render a page after navigating to the route
- Next.js-render - time taken for a page to finish rendering after a route change

💡 Fun learning project idea - build your own/ custom tool to measure these analytics. The aim would be to learn how to store time-series data, average the data, and visualize the data. Chrome devtools and Web.dev doesn't measure custom Next.js metrics.
You can see how well my site is performing 🤡

In your Next.js application, edit/ create _app.js in the /pages directory. Define the reportWebVitals function:

export function reportWebVitals(metric) {
  switch (metric.name) {
    case 'FCP':
    // handle results - console.log or send to an API (same case for other metrics)
      break
    case 'LCP':
      break
    case 'CLS':
      break
    case 'FID':
      break
    case 'TTFB':
      break
    case 'Next.js-hydration':
      break
    case 'Next.js-route-change-to-render':
      break
    case 'Next.js-render':
      break
    default:
      break
  }
}

These analytics provide insights into how user experience is, parts of your application that are not doing too well, and tips on improving performance in your web application.

🧰 Label-sync

Label-sync is a handy tool that makes managing GitHub labels across multiple repositories delightful.

Why do you need it? You don't.

The default GitHub labels are okay. But, they could be better.

GitHub labels provide meta-data for a GitHub issue. This could be the context of a given problem, for example backend, frontend, bug, test, improvement, feature, whether an issue requires discussion, time, and the list goes on on what this could be

Label-sync allows you to define affected repositories, labels, themes, descriptions, group labels, etc.

It requires some configuration when starting. However, managing issues in your projects will be a delight.

This is a personal opinion.

Soft Skills

Being Proactive

Being proactive involves taking responsibility in your life. It involves anticipating problems, seeking solutions, and giving it your best shot.

The alternative to being proactive is reactive - responding to tasks/life as they stream.

You are responsible for your growth, including your career.

Go out there, ace it and have a great week!

Till next week. ✌🏽

SE Internship Log[3]

Ruheni Alex — Mon, 16 Aug 2021 19:59:00 +0000

Hello there internet stranger, 👋🏽

This is the 4th installment of the Software Engineering(SE) Log.

Technical Skills

Toolbox 🧰

This week, I'll share a some libraries/ tools I discovered that I found helpful:

ts-node `--require` flag

ts-nodetransforms TypeScript into JavaScript, which is executed in Node.js.

A useful flag I discovered is the -r/ --require that enables you to execute a file with an export (aka a module):

For example:

// path to file on your computer: /src/hello.ts
export function sayHello(){
  return "Hello there"
}

You can execute this file by running:

npx ts-node -r ./src/hello.ts

Reading and writing files with `fs-jetpack`

fs-jetpack is a utility library that makes interacting with the file-system delightful.
This can be the CRUD of files and directories - creating, reading, updating and deleting.

Soft Skills

Consistency

Sometimes – or most times – software engineering gets tough. Tasks may be daunting, issues may be vague, or sometimes getting help/ feedback on a task may take a little longer than expected.

It's frustrating. The feeling sucks!

The frustration is part of the learning/ growth process.

There will be days you will crush it!

And sometimes, the simplest of tasks can seem impossible.

What matters the most is showing up and making an attempt to fix and a bug, close an issue, or just give feedback on a project.

A hack that I use to "trick" my brain to getting it done is starting with the simplest task to build up some momentum. For example, opening VS Code, starting the app server, and breaking something to try fix it.

Or, take a break. It's totally fine.

I've discovered that I get most of my eureka moments when I take a walk, I'm in the shower or lying on the bed – thinking about the finality of death and how life is meaningless and we're all going to die someday and nothing we do matters.

💡

Till next week. ✌🏽

SE Internship Log[2]

Ruheni Alex — Mon, 09 Aug 2021 00:00:00 +0000

Hello there internet stranger, 👋🏽

This is the 3rd article in the Software Engineering(SE) Log.

A little about me, I'm Alex, and I have no freaking idea what I'm doing. But, I'm taking one step at a time to learn and trying to figure things out.

Technical skills

Testing 🎙

I was going for a mic check with the emoji, but uuuuhh (awkward stares)... moving on swiftly

This week was spent improving our end-to-end testing for the smoke tests. It was pretty neat because I learnt how to create a test matrix with jest. A test matrix reduces repetitive tests that uses the same data.

Let's back up for a moment and explain some jargon.

What is a test?

A test is code that tests your code ensuring it does what it's suppose to.

Testing may be manual – a user going through your application and finding bugs – or automated – a program runs assertions against your code to ensure everything works correctly.

There are different types of tests such as unit, integration, and end-to-end tests that help build confidence you're not shipping any bugs – which are features sometimes. It can be painful sometimes writing tests but on the bright side, it's a great skill to have and you ship less bugs. 🙂

This Log won't cover everything that has to do with testing because there's a lot and it can't be summarized into a short article. However, you can check out the Google Test User Guide. It provides a good introduction to testing concepts. It's specific to C++ but I think it provides a good foundation in testing.

I accidentally once shipped a slightly broken feature about 2 weeks ago. It wasn't a bug, but it didn't behave as expected. I still haven't fixed it but by the time this log is out, there'll be a PR fixing it.

End-to-end tests aka smoke tests

An end-to-end (e2e) test is a test that simulates a user's interaction in an application. I.e, it opens up the application up on an emulator (browser window or mobile emulator) and interacts with the application by clicking links, filling out forms etc.

There are a suite of tools that can be used to accomplish this such as Cypress and Playwright for web-based applications.

To give a sense of what this would be like, here's a small guide on getting started with Playwright. It'll use the GraphQL-Next.js Prisma example.

A small demo testing with Playwright

Set up the application

Download the example and install dependencies:

curl https://codeload.github.com/prisma/prisma-examples/tar.gz/latest | tar -xz --strip=2 prisma-examples-latest/typescript/graphql-nextjs
cd graphql-nextjs
npm install

Set up the database (this uses SQLite for ease of set up)

npx prisma migrate dev --name init    # Creates a database and applies the schema against it
npx prisma db seed --preview-feature  # Seeds the database based on `prisma/seed.ts
npm run dev                           # Starts the application server

On a separate terminal, install playwright as a devDependency:

npm install --save-dev @playwright/test
npx playwright install

It's now time to write an example test for the application. At the root of the project, create a folder called tests and a file called test.spec.ts. In test.spec.ts, paste in the following:

import { test, expect } from '@playwright/test';

// 1
test.describe('User flow:', () => {
  // 2
  test.beforeEach(async ({ page }) => {
    await page.goto('http://localhost:3000');
  })

  // 3
  test('signup', async ({ page }) => {
    // 4
    expect(await page.getAttribute('text=Signup', 'href')).toBe('/signup');

    // 5
    await page.click('text=Signup');

    await page.fill('[placeholder="Name"]', 'John');
    await page.fill('[placeholder="Email address"]', 'john@email.io');

    await page.click('[value="Signup"]');

    expect(await page.waitForSelector('text=My Blog')).toBeTruthy();
    expect(await page.url()).toBe('http://localhost:3000/')
  })

  test('cancel signup', async ({ page }) => {
    expect(await page.getAttribute('text=Signup', 'href')).toBe('/signup');

    await page.click('text=Signup');
    await page.click('text=or Cancel')

    expect(await page.waitForSelector('text=My Blog')).toBeTruthy();
    expect(await page.url()).toBe('http://localhost:3000/#')
  })
})

The following test does a number of things:

This groups logically related tests
Creates a hook that executes before a test is run. In this case, it navigates to the application
The test definition
An assertion to verify what is expected to be on the user's device
Simulates user interaction

Run the test:

npx playwright test

The tests does the following:

Test case 1:

Navigates to http://localhost:3000
Clicks the Signup link
Fills out the user information
Submits values

Test case 2:

Navigates to http://localhost:3000
Clicks the Signup link
Exits from the flow

The output on your terminal should resemble this:

You can make the test intentionally fail by playing around with the values in .toBe('random_value') method.

The tests run on the CLI – in headless mode, meaning there's no browser window being opened. You can play around with the configuration.

This is just a glimplse of what e2e tests look like and there's so much more that you can do with e2e tests.

Soft skills

Learning in public

An interesting thought I had earlier this week was on sharing knowledge or learning in public. Most of the time – especially as a beginner or even if you're senior – you may feel like you're not qualified enough to share the knowledge you have for a number of reasons. Maybe, you're not good at it yet, someone else has done it or any other excuse that may come up, preventing you from talking about what you learnt.

Well, go ahead and do it!

Am I qualified to talk to you about Playwright, testing, TypeScript (the list is endless) or any other topic?

No.

Maybe.

I don't know.

But, the more you make content about what you love, the easier it gets and someone out there will appreciate your work.

Start before you think you're ready.

Matt D'Avella

Do what brings you joy and enjoy the process. 🙂

Till next week. ✌🏽

SE Internship Log[1]

Ruheni Alex — Mon, 02 Aug 2021 07:03:44 +0000

Hello there internet stranger, 👋🏽

This is the second article in Software Engineering(SE) Log.

The better part of the week was spent arguing with the TypeScript compiler and we both know who was right.

It was me.

JK, The compiler is always right!

Technical skills

Types! Types! Types!

This week, I learnt there's more to types than string, number, boolean, Array, and Object types.

TypeScript allows you to do some advanced type wizardry by manipulating types from existing types – besides extending from other types with interfaces. Sounds meta, right?

When a type/ interface is not specified, TypeScript interprets it as its widest form/type.

Case example, if you have an array of strings, the type will always be string[]. However, you can take it a step further and be specific with what the value of the string should be in your array or variable.

In the example below, no type is assigned to colors. Therefore, TypeScript will interpret it as string[].

const colors = ['blue', 'black', 'white', 'yellow', 'orange']

However, you can create a readonly type from the above example by appending the key words as const to the end of the statement. This means that the properties will be immutable – you cannot perform a write to the array.

const colors = ['blue', 'black', 'white', 'yellow', 'orange'] as const

The intellisense on hovering on colors would reveal readonly ["blue", "black", "white", "yellow", "orange"].

Union Types

You could take the previous example a step further and create a union type from colors array with a little TypeScript magic:

const colors = ['blue', 'black', 'white', 'yellow', 'orange'] as const

type color = (typeof colors)[number]

On hovering on type color, a union type is created: "blue" | "black" | "white" | "yellow" |"orange". The [number] annotation is an Indexed Access Type – this means that it looks up a property from another type.

Template Literal Types

TypeScript also supports Template Literal Types which builds on top of string literal type. It enables creating types from interpolated strings. For example:

type lang = "en" | "de"
type book = "TypeScript Handbook" | "Functional Programming"

type BookCategories = `${book}_${lang}`

In this example, we're creating "internationalized" – a German and English – versions of the book type. The generated types on hovering is a union type of each lang and book, i.e.: "TypeScript Handbook_en" | "TypeScript Handbook_de" | "Functional Programming_en" | "Functional Programming_de".

Template literal types can be taken to another level be manipulated by conversion to uppercase, lowercase, un-capitalization, and capitalization.

type book = "TypeScript Handbook"
type lowercaseBook = Lowercase<book>

The output of lowercaseBook is "typescript handbook"

This is all just a tip of the iceberg of what Type manipulation with TypeScript looks like.

You can explore the TypeScript documentation and learn more on types:

Should probably have spent more time reading the docs and not making gifs

Soft Skills

Pursuing projects

This is more of a technical skill but I feel like it still falls under the soft skills.

Advice from my manager was to work on other projects on the side. It is not compulsory and I don't mean that you should sacrifice your time.

Working on other projects besides work would potentially expose you to new technology and or features of the programming language you're using. Projects may require you to read someone else's code and gain a better understanding of how and why the thing was built the way it is.

An alternative to side projects is contributing to existing open-source projects.

This week has been mind blowing watching my manager tackle tasks in 20 minutes that took me a day. It all seemed like magic – especially the TypeScript stuff – but it's all practice and experience.

What comes next?

It's definitely getting more familiar with TypeScript and digging deeper into the TypeScript Handbook.

A TS cheat sheet maybe? A project?

🤞🏽 this week I win a fight with the TS compiler. I mean, what are the odds?

There's always a lot to learn. It's one step at a time and be patient with the process.

Till next week. ✌🏽

SE Internship Log[0]

Ruheni Alex — Mon, 26 Jul 2021 06:50:10 +0000

Hello there internet stranger, 👋🏽

Software engineering can be daunting. This may be true if it's your first time working as a software engineer.

For the summer of 2021, I'll be interning in one of the engineering teams at Prisma. I'll share a summary of my learning experience – technical and soft skills – on a weekly basis for a number of reasons.

One, this is a great opportunity to document my learning experience. This would also serve as a reminder to my future self or whoever stumbles on this article.

Two, if you happen to doubt yourself, I hope you find some comfort that you're not alone. We're all in this together and true growth takes time. 🙂

Technical skills

Type-Only imports and exports

This week, I learned about type-only imports and exports. It was introduced in TypeScript version 3.8.

Type-only imports and exports let the TypeScript compiler know that you're only interested in type declarations. The type-declarations won't be included in the build output.

This feature is be useful in development when you're only interested in inferring types from a library but not shipping it in your application bundle.

The syntax would resemble something like this in your application:

// type-only import
import types { Request, Response } from 'express';
import express from 'express';

const app = express()

app.get('/', (req: Request, res: Response) => {/** logic here */})

// type-only export
export type { Request, Response };

Design systems

Building good and reusable components is hard. The complexity of components grow over time with changing product requirements.

When you're building your frontend application, you may have two choices – adopt an existing design system/ styling library such as Bootstrap and Bulma or design and build the components on your own.

Adopting an existing system offers the advantage of not worrying about styling. The downside is that, when your application will require a custom component, building it to match the existing style may be a little tricky. Plus, there's the "Bootstrap effect" and your application may be bland because it will resemble many sites on the internet.

Enter design systems! Now this is not easy, but definitely makes your application, website, web app stand out from the rest. A number of factors to be considered include theming, typography, layouts, icons, internationalization(i18n) and most importantly accessibility.

Accessibility

According to MDN, accessibility is the practice of making websites/ applications usable by as many people as possible. This includes people with disabilities – cognitive, mobility, hearing, and visual impairments. Sometimes we assume our users will be like us and accessibility becomes an afterthought. It happens, but this is a grave mistake that would hurt your users.

The design and development process should conform to the Web Content Accessibility Guidelines (WCAG). It states how to make your content more accessible and design guidelines when building an application. For example, making input fields, dialogs, and menus keyboard accessible.

React-Aria provides a set of React hooks that allow you to add behavior and interaction in your React components. It follows the WAI-ARIA Authoring practices that provides accessibility out of the box.

Note: The Adobe team built react-aria and use it in their design system – react spectrum.

If you're looking to build a design system, react-aria will enable you to build accessible-first components. It doesn't ship with any styling, giving you the freedom to explore your artistic side. 😜

Soft Skills

Be confident - don't put yourself down

In the software engineering field, it's common to experience Imposter Syndrome. The feeling that you're not good enough or don't deserve what you get. You may also feel overwhelmed from every once in a while. And it's okay.

Despite your background and level of experience, everyone has something to offer. Be you and your team will appreciate that. Remember not to compare yourself with others and be open to learning and taking up any kind of task. That's how you'll grow.

Don't compare yourself with other people; compare yourself with who you were yesterday

– Jordan Peterson

You got this. 💪🏾

Asking for feedback

Candid feedback is good. Feedback from a team member or manager will help you evaluate your growth, understand your weaknesses, and develop goals to grow your career.

1:1s with your manager can help you get on the same page with your manager on goals, overcome the daunting feeling when you're new, and motivate you.

What comes next?

I have no idea. Could be breaking prod, dropping all tables... it's all uncertain. I look forward to learning more and sharing it with you folks.

Till next week. ✌🏽

Cover photo by Vadim Bozhko on Unsplash

Reliable, Scalable, and Maintainable Applications

Ruheni Alex — Thu, 08 Apr 2021 08:11:08 +0000

Hello friends 👋🏾

These are my notes on Designing Data-Intensive Applications by Martin Kleppmann. The book is an incredible read and would recommend you pick up your copy.

The purpose of sharing this is to keep myself accountable - making sure I read -, share what I learn, make sure what I learn sticks, and serve as a reference to future me.

I don't have a lot of experience building applications at scale and therefore my notes may contain a lot of content. I hope this summary will be of value to you too. 🙂

Reliability

Software is deemed reliable depending on its ability to tolerate faults, function as expected, ensure the right level of authorization access, and have reasonable performance for its tasks.

Not all faults and failures can be captured.

Types of faults

Hardware faults - e.g., hard drive corruption.
Software errors - e.g., unhandled exceptions for error handling.
Systematic errors: these are errors within a system - correlated with areas across nodes in a system, e.g., the leap second glitch that caused an outage of popular web services.
Human error - e.g., having faulty configuration during deployment.

Inducing faults helps in capturing faults, improving the reliability of an application.

Making systems more reliable

System design - this reduces opportunity and can include patterns such as having well-designed abstractions, APIs, and admin interfaces make it easy doing the right thing.
Sandbox environments - these are environments for battle testing applications before moving to production.
Testing - using unit, integration, and end-to-end tests taking software to the extreme to capture "edge cases" users may encounter.
Telemetry - using monitoring software to track usage, exceptions, and application performance.

Scalability

This is a software's ability to cope with an increased load within a given set of parameters.

TIL: Tail latency amplification: An instance where a request gets slower because it is dependent on other calls (e.g., to other services or APIs).

Monitoring the performance of an application can be done in two ways:

Option A: Keeping a log of requests/ responses every 10 minutes, detailing the response times.
Option B: Collecting all requests/responses and sorting through them every 10 minutes. This may be a naïve approach, and you can sort through them every 10 minutes using the following algorithms:

Maintaining performance

Rethinking system architecture - taking a different approach on how systems can be scaled. There are two scaling "models": scaling up (vertical scaling) and scaling out(horizontal scaling) alias shared-nothing architecture.
Elastic systems - having systems that can either be manually or automatically scaled under a load.

There is no magic scaling sauce or a one-size-fits-all architecture for designing scalable systems.

Maintainability

This refers to designing software that makes it less painful to maintain in the long run. Maintainability helps ensure developers avoid building legacy software. No one likes legacy systems. 🤷🏾‍♂️

While writing this summary, the following tweet resonated:

To ensure maintainability, development teams have to follow a couple of design principles when building systems:

Operability - refers to making a system easy to run (making life easy for the operations team).
Simplicity - refers to the ability to manage complexity when building a platform, e.g., creating abstractions.
Evolvability - refers to adapting software for future needs such as new features.

Cheers, and stay tuned for more. 📣

DEV Community: Ruheni Alex

Extend your Platformatic API with Prisma Client

Prerequisites

Your dev toolbox

Assumed knowledge

Set up your Platformatic API

Project structure and files

Extend the functionality of your API with plugins

Define the plugin property in your platformatic.db.json file

Create a plugin

Extend the GraphQL API

Extend the REST API

Recap and next steps

Friendly data modeling & auto-generated, editable migrations for Platformatic with Prisma

Prerequisites

Your dev toolbox

Assumed knowledge

Set up your Platformatic app

Project structure and files

Data modeling and automated migrations

Set Prisma in your project

Model your database schema

Generate a migration with migrate diff

Start your API server

Explore and interact with your API

Introspect your database for the versions model

Side quest 🧙🏽: Automate versioning and generation of your database migrations

Install the helper utility

Update your schema

Auto-generate an up migration using @ruheni/db-diff

Restart and interact with your API using Platformatic

Wrapping up

Why Prisma and Platformatic are a great match

What is Platformatic DB

What is Prisma

How Prisma can improve your development workflow with Platformatic DB

Intuitive data modeling language

Auto-generated and customizable SQL migrations

Type-safety and auto-completion for database queries

Wrapping up

Data modeling – Table Inheritance

Meet the family

A visit to the bank 💰

Single Table Inheritance

Concrete Table Inheritance

Class Table Inheritance

Conclusion

Database Migrations for .NET and Entity Framework with Prisma

Introduction

What is Prisma?

Prerequisites

Step 1: Create a new console application

Step 2: Add Prisma to your project

Initialize Prisma

Data modelling

Create a database migration

Step 3: Introspect your database aka Reverse Engineering

Conclusion

SE Internship Log[5]

Context - how seeding in Prisma works

The solution

SE Internship Log[4]

Technical Skills

Re-thinking performance

Next.js Measuring performance

🧰 Label-sync

Soft Skills

Being Proactive

SE Internship Log[3]

Technical Skills

Toolbox 🧰

ts-node --require flag

Reading and writing files with fs-jetpack

Soft Skills

Consistency

SE Internship Log[2]

Technical skills

Testing 🎙

What is a test?

End-to-end tests aka smoke tests

Define the `plugin` property in your `platformatic.db.json` file

Generate a migration with `migrate diff`

Introspect your database for the `versions` model

Auto-generate an `up` migration using `@ruheni/db-diff`

ts-node `--require` flag

Reading and writing files with `fs-jetpack`