Postgres is our favorite relational database, but it is difficult to use directly in serverless environments, and impossible to use directly from a browser. Platter Postgres is a branching, serverless version of Postgres.

Supported Clients

Platform	Status
Direct Connection	✅ complete
Node	✅ complete
Web (read-only)	✅ complete
Web (read + write)	🚧 in progress
Rust	🚧 in progress

Features

Databases are created on shared postgres clusters, managed by Platter. For dedicated instances, contact us at [email protected].

Most extensions are available on the shared cluster. If there's an extension missing that you would like to see, contact us at [email protected].

Creation

New Postgres instances are created with platter postgres create. This instance includes a new database associated with a trunk branch (main by default) that can be branched later on using platter postgres branch create.

To add client configurations for previously-created instances, use platter postgres client configure.

Usage

Choose one of the connection methods below to learn about how to use your new Postgres instances.

Connection String

Branch connections with url

The url command returns a connection string for a given branch of a given instance. This connection string can be used with an ORM (usually as an environment variable) or through a client like psql, e.g.:

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

Node

Branch connections with generated clients

Once instances have been created, clients can be generated with platter postgres client generate. Generated clients can be imported directly into your project, e.g.:

// clients are generated with a PascalCase filename based on the instance name

// the following import path is customizeable, but shown here with the default path

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

const postgres = new Postgres()

// by default, clients run as anonymous users on the instance's trunk branch

postgres.query('SELECT * FROM public_data').then(console.log)

async and streaming

Clients expose both async and stream-based query interfaces. Server-side, all rows are immediately sent to clients as the become available. In the client, query() will aggregate that stream of rows into a single JavaScript Array wrapped in a Promise, while queryStream() will expose the underlying RowStream directly. For large or slower queries, queryStream() is strongly recommended.

All methods are fallible, and will throw an Error with a simple message describing what went wrong. Wrapping all methods with try/catch or using catch() on returned Promises is highly recommended.

Value and type conversion

type ToJson = {toJSON(): any}

type Primitive = boolean | number | string | null

type Value = Primitive | ToJson | Value[] | undefined

Parameterized values in queries can be any primitive JavaScript type, any type that can be stringified with JSON.stringify(), and Arrays of either of those types. Those types are handled in the following ways:

Primitive

Primitive values are converted to Postgres's internal TEXT format and passed directly to the database. This means that more complex Postgres types can be handled through their broader JavaScript types thanks to Postgres' built-in type inference and casting. If you're unsure which type to use, string is a good fallback, e.g:

postgres

.query(

'SELECT $1 + 5::money AS dollars',

['$5']

)

.then(console.log) // [{ dollars: '$10.00' }]

undefined and null

undefined and null are both converted to Postgres NULL, e.g:

postgres

.query(

'SELECT $1 AS missing',

[undefined]

)

.then(console.log) // [{ missing: null }]

ToJson

Any JavaScript type that implements toJSON() without circular references can be stringified using JSON.stringify(). This includes most Objects, including built-ins like Date. These types will be automatically converted to strings and sent directly to the database, where their types can be inferred or cast more explicitly, e.g.:

postgres

.query(

'SELECT $1::json AS aggregate',

[{ foo: 'bar' }]

)

.then(console.log) // [{ aggregate: { foo: 'bar' } }]

postgres

.query(

'SELECT $1::date AS today',

[new Date()]

)

.then(console.log) // [{ today: '2021-03-17'}]

Value[]

The Client supports single-dimension Postgres ARRAY types. For nested data in a single field, the JSON type is recommended instead of multimensional arrays. JavaScript Arrays will be converted to Postgres ARRAY syntax automatically, e.g.:

postgres

.query(

'SELECT $1::text[] AS words',

[['foo', 'bar']]

)

.then(console.log) // [{ words: [ 'foo', 'bar' ] }]

query results

Rows in query results are serialized into JSON Objects. Each row Object's keys are derived from the returned columns, and the values are the column results themselves. For those columns with Postgres types that cannot be directly tranlated to JSON types, like MONEY, NUMERIC, TIMESTAMP, and INT8, the output from Postgres is returned directly as a JSON string.