Skip to main content

graduate data-container

Overview#

Graduating a Data Container allows you to create a Data Image from it. This is useful when you make changes to a Data Container and want to use its current state as the baseline for future work. A good example of when to use the graduate command would be when you were able to reproduce a bug and want to share the state of your database with others. You can graduate the Data Container and share the resulting Data Image with your team.

Command#

$ spawnctl graduate data-container <ContainerName_Or_ContainerID> --revision <RevisionID> [--name <GraduatedImageName> --team <GitHub_Team1> --tag <Tag1>]

Tutorial#

In this tutorial we will create a Data Image, then create a Data Container from that image. We will then make some changes to the database, save them and perform a graduation. This will create a new Data Image. We will use this image to create a new Data Container and inspect its current state.

As a prerequisite you should've followed the instructions to install spawnctl

  1. Create a file development.yaml with your Data Image specifications.

    sourceType: empty
    name: dev
    engine: postgresql
    version: 11.0

    In this case we want to create a PostgreSQL Data Image that is completely empty and is named dev.

  2. Run the following command to create a Data Image.

    $ spawnctl create data-image -f ./development.yaml
    Data image 'dev' created!
  3. You can verify your Data Image by running the following command.

    $ spawnctl get data-images
    NAME IMAGE ID ENGINE STATUS MESSAGE CREATED
    dev 10001 PostgreSQL 2 Created 2 minutes ago
  4. Create a Data Container from the newly created Data Image.

    $ spawnctl create data-container --image dev
    Data container 'dev-rambbomj' created!
    -> Host=instances.spawn.cc;Port=53223;User ID=<some_user_id>;Password=<some_password>;
  5. You can verify your Data Container was properly created by running the following command.

    Notice the created Data Container has revision rev.0.

    $ spawnctl get data-containers
    NAME CONTAINER ID REVISION STATUS MESSAGE ENGINE CREATED
    dev-rambbomj 10001 rev.0 2 Running PostgreSQL 1 minute ago
  6. You should now be able to connect to your database and execute queries.

    In this example we connect to the PostgreSQL Data Container (database) using psql.

    $ psql -h instances.spawn.cc -p 53223 -U <some_user_id>
    Password for user <some_user_id>:
    psql (10.5, server 11.0 (Debian 11.0-1.pgdg90+2))
    SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
    Type "help" for help.
    <some_user_id>=# CREATE TABLE customers(id INT);
    CREATE TABLE
    <some_user_id>=# \dt
    List of relations
    Schema | Name | Type | Owner
    --------+-----------+-------+------------------
    public | customers | table | <some_user_id>
    (1 row)
  7. We can now perform a save operation on this Data Container.

    $ spawnctl save data-container dev-rambbomj
    Saving container....
    Data container 'dev-rambbomj' saved!
    New revision is 'rev.1'
  8. We can now perform a graduate operation on this Data Container.

    Now that our new changes are saved, we want to make the current state of this Data Container (database) the baseline for future work.

    $ spawnctl graduate data-container dev-rambbomj --revision rev.1
    Successfully graduated data container 'dev-rambbomj' at revision 'rev.1' to a new data-image
    New image 'dev-rambbomj-graduate-1' available!
  9. You can verify the new Data Image by running the following command.

    $ spawnctl get data-images
    NAME IMAGE ID ENGINE STATUS MESSAGE CREATED
    dev 10001 PostgreSQL 2 Created 2 hours ago
    dev-rambbomj-graduate-1 10002 PostgreSQL 2 Created 2 minutes ago

    Notice the name of the new image is dev-rambbomj-graduate-1. This is because it was created from the graduation of a Data Container.

  10. You can now create a Data Container from that image.

    $ spawnctl create data-container --image dev-rambbomj-graduate-1
    Creating data container......
    Data container 'dev-rambbomj-graduate-1-hztarabe' created!
    -> Host=instances.spawn.cc;Port=53224;User ID=<some_user_id>;Password=<password>;
  11. Connect to this Data Container and verify its content.

    $ psql -h instances.spawn.cc -p 53224 -U <some_user_id>
    psql (10.5, server 11.0 (Debian 11.0-1.pgdg90+2))
    SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
    Type "help" for help.
    <some_user_id>=# \dt
    List of relations
    Schema | Name | Type | Owner
    --------+-----------+-------+------------------
    public | customers | table | spawn_admin_jmij
    (1 row)

    Notice that the table customers we created previously is present. This is because after creating the table, we saved the Data Container and then graduated. The graduation operation created a new image. All subsequent Data Containers based on this image will contain a copy of the data.