This repository accompanies the Tonic.AI blog <BLOG_REF> which discusses how the Ephemeral API is used to create and hydrate database snapshots. The repository contains fully worked examples of scripts that can be used to do both these things. It also includes scripts which can be used to set up the required resources (workspace/snapshots) that the scripts rely on. It assumes a reasonable understanding of the Tonic Structural platform.
- A command line environment supporting
bash. - The JSON manipulation tool jq
- Access to Tonic Structural and Tonic Ephemeral using either our cloud services (Structural/Ephemeral) or self hosted installations
Clone this repository and change to the project directory
https://github.com/TonicAI/EphemeralAPIExamples.git
cd EphemeralAPIExamplesAdd your credentials to credentials.sh
# Tonic Ephemeral API Server credentials - modify SERVER/PORT if you are self hosting
TONIC_EPHEMERAL_SERVER="https://ephemeral.tonic.ai"
TONIC_EPHEMERAL_API_PORT=443
TONIC_EPHEMERAL_API_KEY="<YOUR_KEY_HERE>"
# Tonic Structural API credentials - modify SERVER/PORT if you are self hosting
TONIC_STRUCTURAL_SERVER="https://app.tonic.ai"
TONIC_STRUCTURAL_API_PORT=443
TONIC_STRUCTURAL_API_KEY="<YOUR_KEY_HERE>"API keys are acquired from Structural as described here. The process for Ephemeral is similar.
If you do not have a workspace already the scripts provided will set one up for you. We do this by
- Creating a database snapshot for a basic database schema
- Hydrating that snapshot using Ephemeral
- Creating a workspace that uses the hydrated snapshot as the source database
See FirstDemoWorkspace for full details
In this section we generate a data snapshot using a script built using the Structural API. The script takes the id of your workspace as an argument.
This section therefore assumes you have a workspace configured to use Ephemeral as the destination database platform. If you have not done this before please consult our documentation or use the workspace setup process described above.
To generate a data snapshot run
./generateSnapshot.sh <WORKSPACE_ID>If you have generated your workspace using the FirstDemoWorkspace process you can omit the WORKSPACE_ID argument as this will be obtained from data written to disk. If you have set up your own workspace the id can be found via the UI.
The output will be similar to
No workspace id provided
Detected worspace generated using ./createWorkspace.sh
Will generate using workspace id a7c2d6e5-310c-4b0a-dce5-1ee7a0cd513e
Generating snapshot Demo.20250703.CMiy using workspace a7c2d6e5-310c-4b0a-dce5-1ee7a0cd513e
Checking job status - need to wait for 'Completed' state
Job status = Queued
Job status = Running
...
Job status = Running
Job d939758d-277a-ddfc-bf33-6f1e61f11cae completed
Generated snapshot with name Demo.20250703.CMiy
Here we generate a 'well named' snapshot using a scheme composed of a prefix, date of creation and an arbitrary suffix to ensure uniqueness. You are of course free to develop your own scheme. The snapshot used above can then be used to hydrate, on demand, an ephemeral database server.
Hydrating a database server using a snapshot is a simple process. Run
./hydrateSnapshot.sh <SNAPSHOT_NAME> <SAVE_CREDENTIALS>where SNAPSHOT_NAME is the name of a valid snapshot. SAVE_CREDENTIALS indicates whether to save the credentials to disk or not and takes the values true/false. If we were to hydrate the snapshot we created above, we would supply Demo.20250703.CMiy as our snapshot name and the output would be as below.
./hydrateSnapshot.sh Demo.20250703.CMiy true Creating database server Demo.20250703.CMiy-Ytie using snapshot Demo.20250703.CMiy
Obtaining the volume snapshot id for snapshot Demo.20250703.CMiy
Volume snapshot id is efd3eaee-338d-41c2-adab-e736eebfc9a8
Requesting spin up of an ephemeral DB for snapshot Demo.20250703.CMiy. Ephemeral DB server identifier is Demo.20250703.CMiy-Ytie
Request made
Now checking job status - need to wait for 'Running' state
Job status is Pending
Job status is Pending
Job status is Pending
Snapshot Demo.20250703.CMiy is available via db server Demo.20250703.CMiy-Ytie
Credentials
===========
DB User : ephemeral_user
User Password : pF0p9...kxG
Database name : postgres
Host : 1385a845.db.ephemeral.tonic.ai
Port : 13950
Login syntax for psql
psql -U ephemeral_user -d postgres -h 1385a845.db.ephemeral.tonic.ai -p 13950
Warning - writing out db credentials file to Demo.20250703.CMiy.creds as per SAVE_CREDENTIALS=true
Our credentials file would be
{
"dbUser": "ephemeral_user",
"dbName": "postgres",
"dbHost": "1385a845.db.ephemeral.tonic.ai",
"dbPort": "13950",
"dbPassword": "pF0p9...kxG",
"dbType": "Postgres"
}We can now make us of this temporary server as we see fit. We can either terminate it when finished or wait for expiry. Expiry is controlled by DB_SERVER_CONFIG in our script. In our script we name the server by adding a randomly generated suffix to the snapshot name to ensure uniqueness.
DB_SERVER_CONFIG=$(cat <<DOC
{
"name":"${EPHEMERAL_DB_SERVER_NAME}",
"expiry":{
"expiryType": "Static",
"durationEnd": {
"minutesFromStartToExpiry": 360,
"minutesFromLastActivityToExpiry": 180
}
},
"volumeSnapshotId":"${SNAPSHOT_ID}",
"storageSizeInGigabytes": 10
}
DOC
)
The exact configuration can be modified as needed.
This repository provides two additional utility scripts. deleteEphemeralDBServer.sh can be used to terminate a running server & takes the name of the running server as its argument.
./deleteEphemeralDBServer.sh <DB_SERVER_NAME>If we were to delete the server above the output would be
Deleting database with name Demo.20250703.CMiy-Ytie
Obtaining the db identifier for name Demo.20250703.CMiy-Ytie
Found database with name Demo.20250703.CMiy-Ytie
Requesting deletion of ephemeral DB with name Demo.20250703.CMiy-Ytie. DB identifier is b4163037-3bc4-4571-a3b6-45b81b17c190
The script deleteWorkspace.sh can be used to delete a workspace and takes one argument, the id of the workspace to be deleted. It can be particularly helpful if making use of the createWorkspace.sh utility, in which case it can be run without an argument as the workspace id is written to disk.
ktune ephemeral.project > ./deleteWorkspace.sh
No workspace id provided
Detected worspace generated using ./createWorkspace.sh
Will delete using workspace id a7c2d6e5-310c-4b0a-dce5-1ee7a0cd513e
Deleting workspace
==================
Workspace deleted
Deleting workspace id file .lastWorkspace.txt
You will see the -k flag used here for curl commands. This instructs curl to allow self signed certificates. This is not generally recommended for production use but is used here as the scripts may be used vs systems that do make use of self signed certificates for test purposes.