Neki quickstart

Getting started

Prerequisites

You will need a PlanetScale account.
An administrator of your PlanetScale organization must join the Neki Platform Preview.

Create a Neki database

Dashboard
CLI

Click “New database” > “Create new database” on your organization’s overview page.

Name your database.

Select a region. For the lowest latency, select a region near you or your application’s hosting location.

Select Neki as the database engine.

Create database form with the Neki engine selected

Select the desired cluster configuration, storage option, and cluster size for your database.

If prompted, add a valid credit or debit card.

Click “Create database” to deploy your database.

Install and authenticate the PlanetScale CLI.

List organizations, then switch to the one enrolled in the Platform Preview:

pscale org list
pscale org switch <ORGANIZATION_NAME>

List regions and pick a slug close to your application:

pscale region list

Create an HA Neki database. --replicas 2 requests two replicas in addition to the primary, for three Postgres nodes on the initial shard. PS_10 is a valid starting cluster size.

pscale database create <DATABASE_NAME> \
  --engine neki \
  --region <REGION_SLUG> \
  --cluster-size PS_10 \
  --replicas 2 \
  --wait

Provisioning can take a few minutes. --wait keeps the command open until the database is ready.

Database names can contain up to 63 lowercase letters, numbers, dashes, or underscores. A name cannot start or end with a dash or underscore.

Add a schema to your database

Use the dashboard’s web console to create some example tables. To use another SQL client, first see Connect to your database.

Enable web console access for production branches.

Select Console and connect to the main branch. The console connects to the Primary server and the postgres database by default. See Web console for connection controls and supported commands.

Web console connected to the main branch

Create some example tables by running the following commands in the web console:

CREATE TABLE categories (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  name varchar(255) NOT NULL
);

CREATE TABLE products (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  name varchar(255) NOT NULL,
  image_url varchar(255),
  category_id bigint
);

CREATE INDEX category_id_idx ON products (category_id);

You can confirm that the tables have been added by running:

SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'public'
  AND table_name IN ('categories', 'products')
ORDER BY table_name;

Web console showing the categories and products tables

Insert data into your database

Run the following SQL to add some rows to the tables:

INSERT INTO categories (name)
VALUES ('Office supplies');

INSERT INTO products (name, image_url, category_id)
VALUES ('Ballpoint pen', 'https://example.com/500x500', 1);

You can confirm the data has been added with:

SELECT * FROM products;

SELECT * FROM categories;

Web console showing SELECT results for the products and categories tables

You can view the schema of your database by navigating to the “Branches” tab and selecting the branch you want to view. You may need to click “Refresh schema”. For now, select main, and it will display the names of the two tables you just created. Click on the name of each table to see further schema details.

Branches page with the products table expanded to show its schema

Connect to your database

Connect from outside the PlanetScale dashboard by creating a new role in the Settings -> Roles page, or open psql through the PlanetScale CLI. On the dashboard page, you can also click Connect to create a new role.

Dashboard
CLI

With the default branch selected, click Connect from your database dashboard.

Click Create new role. A role determines which operations the connection can perform. See Roles and credentials for more details.

Copy the generated psql command and enter it into your terminal.

Connect page showing generated role credentials and the psql command

Open a psql session through the PlanetScale CLI. pscale shell creates temporary credentials, so you do not need a saved role for this step.

pscale shell <DATABASE_NAME> main

For a persistent role that your application can reuse, create one from the dashboard Connect tab or with pscale role. See Roles and credentials.

When the postgres prompt appears, query the data you added:

SELECT c.name AS category, p.name AS product
FROM categories AS c
JOIN products AS p ON p.category_id = c.id;

What’s next?

Open the Connect page and select a framework or language to configure your application. See Connect to Neki for connection parameters, replica routing, and router groups. A new Neki database starts on one shard. Continue with the Sharding quickstart to see how sharding works in Neki. When you want to continue developing your database, create a development branch from main so you can work independently of the production branch. See Development environments to initialize an empty branch for schema work and tests.

Clean up

Delete your database from Settings > Delete database, or use the CLI:

pscale database delete <DATABASE_NAME>

Deleting the database permanently removes all of its branches and data.

Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.

Architecture

Pricing

Platform

Guides

Getting started

Prerequisites

Create a Neki database

Add a schema to your database

Insert data into your database

Connect to your database

What’s next?

Clean up

Need help?

​Getting started

​Prerequisites

​Create a Neki database

​Add a schema to your database

​Insert data into your database

​Connect to your database

​What’s next?

​Clean up

​Need help?

Getting started

Prerequisites

Create a Neki database

Add a schema to your database

Insert data into your database

Connect to your database

What’s next?

Clean up

Need help?