1
Prerequisites
Nile provides a cloud offering to help build multi-tenant apps. You can also get started with Nile’s Docker image
and try Nile locally. Join our discord to give feedback or ask questions about running Nile locally.
- Docker
- Postgres client. We’ll use
psql
in this guide.
2
Run the Docker Container
test
database
and the 00000000-0000-0000-0000-000000000000
user.3
Connecting to the Database
You can use Or, if you are using a different client, you use the following connection details:
psql
with the following connection string:4
Create a tenant-aware table
From this point, you can use the local database just like you would use Nile service.
All the examples in the documentation are also applicable to the local database.
Below we’ll go through the steps in the quickstart guide using the local database.Tenant-aware tables are tables that have
a If you are using
tenant_id
column. All the rows in such tables belong to a specific tenant.Let us create our first table that has a tenant_id column and a vector column:psql
, you can view the table schema by running \d todos
.5
Create tenants
Nile ships with built-in tables, like
tenants
table. Lets create our first tenant by inserting a row into the tenants
table:6
Insert data into a tenant-aware table
Now that we have a tenant, we can insert data into our tenant-aware table:and you can verify the data was inserted correctly by running:You can add another tenant and insert data for that tenant in a similar fashion. This will allow us to explore
tenant isolation (in the next section).
7
Tenant isolation
Nile goes a step further and provides tenant isolation. You can set the session to a specific tenant, and every query that follows will only return data that belongs to this specific tenant.Think of it as querying a virtual database dedicated to this one specific tenant.✏️ Note that the container uses ephemeral storage, so all the data will be lost when the container is stopped.
This is intentional, as it simplifies the setup (and more importantly - the cleanup), while still allowing you to experiment and test your application.
Looking good! What’s next?
🏆 Tada! You have learned the key Nile concepts. And it only took 5 minutes. You can learn more about Nile’s tenant virtualization features in the following tutorials: Next, you will probably want to learn how to use Nile for building an app in your favorite language. Check out our Getting Started guides for more information.Optional: Docker container configuration
The docker container can be configured with the following environment variables:NILE_TESTING_DB_NAME
: The name of the database. Defaults totest
.NILE_TESTING_DB_ID
: The ID of the database. Must be a UUID. Defaults to01000000-0000-7000-8000-000000000000
.NILE_TESTING_DB_USER
: The username for the database user. Must be UUID. Defaults to00000000-0000-0000-0000-000000000000
.NILE_TESTING_DB_PASSWORD
: The password of the database user. Defaults topassword
.
Troubleshooting
If you are having trouble running the container, the first step is to check that you are using the latest version of the container. You can do this by first deleting existing images ofniledatabase/testingcontainer:latest
(since they may refer to older versions) and then running docker pull ghcr.io/niledatabase/testingcontainer:latest
.
Please check if any of the common issues and solutions below help solve your problem. If not, we welcome you to report the issue on either GitHub or Discord
When reporting the issue, please include:
- The docker container logs (
docker logs <container_id>
) - The exact error message you’re encountering
Server closed the connection unexpectedly
It takes a bit of time for the container to start up. If you get the following error:Role does not exist
If you get the following error:psql
will try to connect to the default Postgres instance, which fails because we are using a specific user that doesn’t exist in the default Postgres instance.
You can either:
- Stop the other Postgres instance - the exact command depends on your operating system and Postgres installation method.
- Change the port mapping when running the container. For example to port 5433, and then connect to the new port: