🚀 White Paper: Fauna Architectural Overview - A distributed document-relational database delivered as a cloud API.
Download free
Fauna logo
Log InContact usStart for free
Fauna logo
Log InContact usStart for free
© 0 Fauna, Inc. All Rights Reserved.

Related posts

Database Joins for NoSQLElevating Schema as Code: Fauna Introduces Computed Fields and Check ConstraintsBuilding a Serverless REST API with Fauna, AWS, and TypeScript

Start for free

Sign up and claim your forever-free Fauna account
Sign up and get started
Endpoints Blog Hero 3190X1798

Introducing Endpoints

Alvaro Videla|Dec 17th, 2018|


When we introduced the Fauna Shell, one of our goals was to make Fauna easier to use. In that article, we showed you how to get started with Fauna by using our serverless cloud offering. Of course, we want to offer more, transforming it into the tool that makes your day-to-day usage of the database easier. In this blogpost, we show how to connect the shell to different Fauna instances. Enter endpoints.


To connect to different Fauna instances, we introduced the idea of endpoints into the Fauna Shell. We wanted them to be easy to manage—adding, listing, or removing endpoints had to be a frictionless task.
So, let’s say that you have two Fauna instances running: one in localhost used for development, and one instance in your private cloud. Let's create our first endpoint:
blog post image
$ fauna add-endpoint "https://localhost:443"
Endpoint Key: ****************************************
Endpoint Alias [localhost]: localhost
After running the add-endpoint, you will be prompted for both a database key for that endpoint and an endpoint alias. It should be something that lets you easily reference the endpoint, as we will see later (the default is the endpoint hostname). 
Now you can list endpoints and see that your endpoint was created successfully:
$ fauna list-endpoints
localhost *
Let's add a new endpoint:
blog post image
$ fauna add-endpoint "https://cluster-us-east.example.com:443"
Endpoint Key: ****************************************
Endpoint Alias [cluster-us-east.example.com]: us-east
As you can see in this case, we changed the endpoint alias to have a shorter name, since we want to remember that this Fauna instance is running in our us-east cluster. Let's list endpoints again:
$ fauna list-endpoints
localhost *
There's our newly created endpoint us-east. You may have noticed that there's a star * next to the localhost endpoint name. That's a way to tell which one is the default endpoint used by the Fauna Shell when connecting to Fauna.

Connecting to a different Fauna instance 

If you want the shell to connect to the us-east endpoint instead of using your localhost database, you can do that by setting us-east as the default endpoint by running this command:
blog post image
$ fauna default-endpoint us-east
Let's list endpoints to make sure our change took effect:
$ fauna list-endpoints
us-east * 

What about the Cloud endpoint?

If you followed the steps in the Introducing Fauna Shell blog post, you may have ended up with a cloud endpoint as well:
$ fauna list-endpoints
us-east *
That's because the cloud-login command showcased in the previous blogpost created a cloud endpoint for us.

Deleting an endpoint

Let's say that we decommission our us-east cluster and decide to run all our business out of Fauna Cloud. Then, we need to delete the us-east endpoint from our configuration.
First, we'll set the cloud endpoint as the default one:
blog post image
$ fauna default-endpoint cloud
$ fauna delete-endpoint 'us-east'
Now, let's list endpoints again to see the results of running the previous commands:
$ fauna list-endpoints
cloud *
As you can see, Fauna Shell makes it easy to manage endpoints that connect to Fauna. Now, as a developer you might be wondering where is the endpoint configuration stored?

What's happening behind the scenes?

When we were designing the shell, we tried to keep the solution as simple as possible. That's why, when it came to storing this kind of configuration information, we decided to simply keep it inside an ini file in your home folder. Try checking the contents of the file ~/.fauna-shell. (On Windows, that file will be in your home folder.)
Here's a sample ~/.fauna-shell:



By keeping things simple, we got a config file that fulfills its purpose while providing us with a very readable format (should our users try to connect to different endpoints).


In this blog post, we learned how to access different Fauna server instances from the Fauna Shell by declaring endpoints for each of them. This becomes quite useful when we want to run queries against different databases and servers. We can see that the shell comes packed with a handful of commands that will ease your day to day work with Fauna.

If you enjoyed our blog, and want to work on systems and challenges related to globally distributed systems, and serverless databases, Fauna is hiring!

Share this post

‹︁ PreviousNext ›︁

Subscribe to Fauna's newsletter

Get latest blog posts, development tips & tricks, and latest learning material delivered right to your inbox.