Quick Start

This tutorial will show you how to create and query your first Platter Postgres database with the platter CLI.

Choose one of the connection methods below to get started.

Connection String

Prerequisites

To interact with your database through a connection string, an installation of psql is recommended.

Setting Up the Project

1. Make sure that you've signed up for a Platter account. To create databases and branches, you'll also need to add a payment method. See more about our pricing here.

2. Install the platter CLI with cURL.

3. Log in with your Platter email and password with:

   platter identity login

Setting Up Postgres

1. Once you've installed platter, then you can create or branch (see Concepts to learn more about feature branching) any Platter resource. Run the following command to create your first instance:

   platter postgres create my-new-database

2. Your new instance was created with a "trunk" branch. Future branches will be based off of this branch by default. This branch was given a name based on your local git configuration, falling back to main if no git configuration exists on your machine. To check the name of your new instance's trunk branch, list your instances:

   platter postgres list

   This should give you a list that looks something like this:

   +--------------------------------------+-------------------------------+--------------+

   | ID | NAME | TRUNK BRANCH |

   +--------------------------------------+-------------------------------+--------------+

   | f1b19a32-1334-406c-a792-ad2905289435 | my-new-database | main |

   +--------------------------------------+-------------------------------+--------------+

Using psql

1. If you have psql installed, you can use the url command to connect directly to the trunk branch of your database instance:

   psql $(platter postgres branch url main -i my-new-database)

2. Once you've connected with psql, you can interact with your main branch's database directly. Try running the following commands to create an items table:

   CREATE TABLE IF NOT EXISTS items (

   id SERIAL PRIMARY KEY,

   name TEXT NOT NULL

   );
   INSERT INTO items (name)

   VALUES ('my-new-item')

   RETURNING id, name;

3. Both commands should run succesffully, and subsequent queries to items should return my-new-item.

Node

Prerequisites

This tutorial assumes that you're working with a unix-style command line with an installation of git and Node.js is installed on your system and accessible in your $PATH. See nodejs.org for in-depth installation instructions.

Setting Up the Project

1. Make sure that you've signed up for a Platter account. To create databases and branches, you'll also need to add a payment method. See more about our pricing here.

2. For the rest of this tutorial you'll need a project with a package.json. To generate a brand-new directory and project, run:

   mkdir platter-quick-start && \

   cd platter-quick-start && \

   npm init -y && \

   git init

3. Install the Platter CLI as a devDependency, like so:

   npm install --save-dev platter

4. Log in with your Platter email and password with:

   npx platter identity login

Setting Up Postgres

1. Once you've installed platter, then you can create or branch (see Concepts to learn more about feature branching) any Platter resource. Run the following command to create your first instance and a Node.js client:

   npx platter postgres create my-new-database \

   --platform node \

   --directory ./platter

2. After running the above command, you should have a Node.js client and TypeScript declaration file in a new platter directory:

   platter

   └── postgres

   └── node

   ├── MyNewDatabase.d.ts

   └── MyNewDatabase.js

   You'll also notice a new platter configuration section that has been automatically added to your package.json that looks like this:

   {

   "postgres": {

   "some-unique-database-id-1234": {

   "autoBranch": true,

   "platforms": [

   "node",

   ],

   "directory": "platter"

   }

   }

   }

   You can learn more about these configuration options in the Configuration section of the documentation.

Using the Node.js Client

1. At this point, you have a running Postgres database that can be accessed from Node.js without a separate connection pool, proxy, or deploy step! Let's try making a query against that database from our website. Open up a node REPL (with the node command) and try the following:

   const Postgres = require('./platter/postgres/node/MyNewDatabase')

   const postgres = new Postgres()

   postgres.query('SELECT NOW()').then(console.log)

   The client automatically aggregates results into an Array of row Objects with keys mapped to Postgres column names. In this case, you should see:

   [ { now: '2021-02-05 15:45:48.278064 UTC' } ] // example timestamp

2. The SELECT NOW() query in the previous step was run anonymously. All data in a database is protected by default, and that data and its permissions can only be modified with the credentials of the database owner. To populate this database with some data, grab an API key from https://dashboard.platter.dev/keys, open up a REPL with PLATTER_API_KEY=<your API key> node, then run the following:

   const Postgres = require('./platter/postgres/node/MyNewDatabase')

   // use the API key from environment variables

   const postgres = new Postgres({ key: process.env.PLATTER_API_KEY })

   const addItems = async () => {

   // create a table for dummy data

   await postgres.query(

   `CREATE TABLE IF NOT EXISTS items (

   id SERIAL PRIMARY KEY,

   name TEXT NOT NULL

   )`

   )

   // insert a new item using a parameterized query

   return postgres.query(

   `INSERT INTO items (name)

   VALUES ($1)

   RETURNING id, name`,

   ['my-new-item']

   )

   }

   addItems().then(console.log) // [ { id: 1, name: 'my-new-item' } ]

Next Steps

Congratulations! You now have a database that can be used anywhere, from the command-line to serverless functions. You also have a database that is public and easy-to-access for identified users, but still protected against malicious queries. And you've completely eliminated the need to manage your own servers, connection pools, cloud databases, or deployment processes along the way. Here's where to go from this point:

1. To learn more about how to create and discard copies of your database as you work on features check out Branching
2. To dive right into some practical examples, check out the Migrations and Netlify Functions guides.