Introducing Endpoints

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.

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:

$ 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:

$ 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 *
us-east

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:

$ fauna default-endpoint us-east

Let's list endpoints to make sure our change took effect:

$ fauna list-endpoints
localhost
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
cloud
localhost 
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:

$ 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 *
localhost

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:

default=cloud

[localhost]
domain=localhost
port=8443
scheme=http
secret=the_secret

[cloud]
domain=db.fauna.com
scheme=https
secret=FAUNA_SECRET_KEY

[us-east]
domain=cluster-us-east.example.com
port=443
scheme=https
secret=OTHER_FAUNA_SECRET

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).

Conclusion

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.