Share a database server between projects
Run one PostgreSQL or MySQL on a cluster for all of its projects, choose its size, back up and restore each project on its own, and see what deleting it removes.
Updated
A database server is one PostgreSQL or MySQL that your cluster runs for all of its projects. Your small projects then share one server instead of each one reserving room for a database of its own.
Database servers are in early access, offered to the teams that try them first.
What you should know first
A database server belongs to its cluster, not to a project. Pausing or deleting a project leaves it running, so the other projects keep their data. When you hand the cluster over to another team, its database servers go with it, along with the projects that use them, and their applications keep their connections.
The server keeps its data in a volume on one node, its data node. Tenkai chooses that node the way it chooses one for a managed service: a node with room for the size you pick. While a node holds the data of a database server, you cannot drain it or remove it from its cluster.
The server reserves its size on its data node all the time, whether projects use it or not. Choose the size for all the projects you plan to put on it.
Each project gets its own databases on the server, called hosted databases. A hosted database has a user of its own that opens no other database, so one project never reads another's data. Your applications reach the server through a database endpoint that Tenkai runs in their environment, so they never join the server's network.
Create a database server
Owners and admins create and delete database servers. Every other member of your team sees them.
- Open the cluster's page and find its Database servers section.
- Choose Create….
- Enter a Name, such as
shared-postgres. No other database server of the cluster can have it. - Choose its Engine: PostgreSQL or MySQL. A cluster can run one of each, so projects on both engines share too.
- Choose a Size. Small suits a few quiet projects.
- Check High availability if the server should survive the loss of a node. See High availability.
- Choose Create database server.
The server shows Starting, then Running once it accepts logins, with the node that keeps its data.
If creating says that no server has room, give a node more CPU or memory, free some of what its resources reserve, or choose a smaller size.
If the server shows Failed, the reason tells you what to do. When the server did not start, change its size: Tenkai starts it again, and a smaller size helps when its node lacks room.
Every project on a server shares its downtime
Your projects share the server, so they also share each of its stops. When you change its size, move it or turn on its high availability, every project with a hosted database on it loses its connections until it runs again. If its data node goes down, they all lose their database together, unless the server has high availability.
That is why Tenkai lists the projects on the server before you confirm one of these changes. If a project adds or deletes a hosted database on the server meanwhile, Tenkai refuses the change and shows the new list, so you never stop a project you did not see. Choose a quiet moment, and tell the people behind those projects first.
Open a server's page from its card in the cluster's Database servers section. Its Projects list names every project the server holds a hosted database for.
Change the size of a server
Owners and admins change the size of a database server when its projects need more room, or less.
- Open the server's page and choose Change size… in its menu.
- Choose the new Size.
- Read the projects the change stops, then choose Change size.
The server shows Starting while it starts again with its new size, then Running. It keeps its data. Their applications connect again on their own, once their connections closed.
Move a server to another node
Move a database server to another node when you want to drain or remove its data node, or give it a node with more room. Its hosted databases and their database endpoints keep working once it runs there, so no application needs a new deployment.
- Open the server's page and choose Move to another server… in its menu.
- Choose the New server. The list offers the nodes of the cluster that take workloads.
- Read the projects the move stops, then choose Move.
Tenkai copies the server's data to the new node while it runs. Then it stops the server, copies the last changes, starts it on the new node and deletes the old copy. The projects lose their database only during that last copy, which lasts longer the more the server writes.
While the move runs, the server reserves its size on both nodes, so neither of them can drain or leave.
If the copy fails, the server runs again on its old node and shows why. If a node stops answering in the middle, the server shows Failed and its move waits: choose Move to another server… again with the same node, and the move picks up where it stopped.
High availability
A database server holds the databases of many projects, so losing its node takes them all down at once. Give it high availability and it runs two instances on two nodes: when one node goes down, the other instance takes over on its own, and every project keeps its data.
It works as it does for a managed service of the same engine. A PostgreSQL server runs a primary and a standby, which needs a cluster with three manager nodes. A MySQL server runs two instances with an arbitrator on a third node, so it needs three nodes that take workloads. Each instance reserves the server's size on its own node.
Your applications change nothing. Their database endpoints always reach the instance that takes writes, so no application needs a new deployment, even after a node went down.
To turn it on for a server that already runs:
- Open the server's page and choose Turn on high availability… in its menu.
- Read the projects it stops, then choose Turn on high availability.
Tenkai starts the second instance, which copies the server's data, then starts the server again with both instances. Every project on it loses its connections for that moment. The server shows Running on both of its nodes once it ends.
A server with high availability keeps its size, and it does not move to another node. Choose its size before you turn it on.
A MySQL server copies only InnoDB tables to its second instance. If a project keeps tables with another engine, Tenkai names them and turns nothing on: change their engine to InnoDB first. Close the server's external access before you turn it on, too.
High availability keeps your data running when a node goes down. It does not undo a mistake, such as a dropped table, because both instances drop it together.
Open external access to a server
External access lets you connect to a PostgreSQL database server from your own computer (a MySQL server does not open it yet), for a while, such as to look at a project's data with a SQL client. It works as it does for a managed service: only the addresses you allow can connect, through a port of your cluster's edge node, and Tenkai closes it when the time runs out.
- Open the server's page and choose Open external access….
- Choose a Duration, and the IPv4 addresses or networks allowed to connect.
- Choose Open external access.
Log in with the database and the user of one hosted database on the server, which its page shows, and the password its binding gives your application in its variables. That user opens no other database, but external access opens the server to every project on it: anyone who has the password of a hosted database and connects from an allowed address reaches that database. Choose Close external access… once you are done.
Add a hosted database to a project
Every member who can create resources adds hosted databases.
- Open the project's page, then choose Add resource and Hosted database.
- Enter a Name, such as
orders. - Choose the Database server. The dialog lists the servers of the project's cluster that run, with their engine. The database runs on that engine.
- Choose Add hosted database.
The database shows Creating, then Ready once its user can log in and the database endpoint runs. Adding a database never restarts the server, so the other projects keep their connections.
Bind the database to your applications as you bind a managed service: choose Bind to an application… under Bindings on its page, then deploy. The binding gives each application the database endpoint as its host, with the database's own user and password, in the format of its engine: a postgresql:// or a mysql:// URL, as for a managed service of that engine.
If the database shows Not created, the reason tells you what went wrong. Delete it, then add it again once its server runs.
Copies and previews
When you add an environment as a copy of one with hosted databases, each hosted database of the copy is a new, empty database on the same server, with a user and a password of its own. Each copied application is bound to the new database, so the copy never writes to the original. The copy reaches the server through a database endpoint of its own, so it shares no network with the environment it copies.
A copy stays on the cluster of the server, because no private network crosses clusters. To run the environment on another cluster, start it with nothing and add a hosted database on a server of that cluster.
Pull request previews work the same way. Each preview gets a new, empty database on the server of each hosted database in the environment previews copy, and Tenkai drops it with its data when the pull request closes. Every open preview uses the server like one more project, so choose a size with room for them.
Back up a hosted database
Each hosted database gets backups of its own database alone, so you restore one project without touching the others. Tenkai encrypts each backup with your team's backup key on the server's data node and sends it straight to one of your team's storage buckets, as it does for a managed service.
- Open the hosted database's page and find its Backups section.
- Choose a storage bucket for its backups. Tenkai then backs it up every day and keeps the 7 latest backups.
- To back it up now, choose Back up now.
A backup never stops the server, so the other projects keep running while it reads.
Restore a hosted database
A restore puts the database back to the data of one of its backups. The data written since that backup is lost, so take a backup now if you may need it.
- Open the hosted database's page and find the backup under Backups.
- Open the backup's … menu, choose Restore…, type the database's name, then choose Restore this backup.
Tenkai loads the backup next to the database first, so a backup that does not load leaves the database as it was. Once it has loaded, the sessions of this database end and your applications reconnect to the restored data on their own. The server keeps running, and the other projects on it keep their data and their connections.
On MySQL, the server cannot rename a database, so Tenkai loads the backup a second time into the database itself. If that second load stops, the database holds part of the backup: restore it again.
While a restore runs, the database takes no backup, and you cannot delete it or its project.
Wait for the restore to end before you change the size of its server or move it. Both stop the server, and a restore it stops can leave the database closed to your applications, or partly loaded on MySQL. Restore it again once the server runs: the other projects keep their data either way.
Delete a hosted database
Deleting a hosted database drops it with all its data and its user from the server. You cannot undo it, so copy what you need first. The server keeps running for the other projects.
- Open the hosted database's page and choose Delete… in its menu.
- Type its name, then choose Permanently delete hosted database.
Its bindings go with it, so deploy the applications that used it. Deleting a project drops its hosted databases too.
Delete a database server
Deleting a database server removes it with the volume that holds its data. You cannot undo it, so copy what you need first.
- Open the cluster's page and find the server in its Database servers section.
- Choose Delete….
- Type the server's name, then choose Delete database server.
A server that holds hosted databases stays, and Tenkai names the projects that use it. Delete their hosted databases first.
The server shows Deleting, then leaves the list. If its data node does not answer, the server shows Failed and keeps its volume on that node: choose Delete… again once the node is back.