When we introduced the Fauna Shell, one of our goals was to make FaunaDB easier to use. In that article, we showed you how to get started with FaunaDB 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 FaunaDB instances. Enter endpoints.
To connect to different FaunaDB 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 FaunaDB 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 FaunaDB 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 FaunaDB.
Connecting to a different FaunaDB 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 FaunaDB. 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
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).
In this blog post, we learned how to access different FaunaDB 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 FaunaDB.