Managing Avro Schema

Adding Schema
Changing Schema
Disabling and Enabling Schema
Showing Schema

Avro is a data format that can be used by values in your store's records. Whether a record's value uses the Avro data format is determined by your development team. However, the usage of the Avro data format is strongly recommended, so chances are good that your store uses Avro.

When store records use the Avro data format, your development team must define schema for their usage of that format. This schema is provided in flat-text files in JSON format, and must then be added to the store using the CLI. Schema can also be enabled and disabled, and multiple versions of the schema can exist at the same time. The ability to support multiple versions of the schema is required in order to support the ability to change (or evolve) schema.

Adding Schema

Avro schema is defined in a flat-text file, and then added to the store using the command line interface. For example, suppose you have schema defined in a file called my_schema.avsc. Then (assuming your store is running) you start your command line interface and add the schema like this:

> java -Xmx256m -Xms256m \
-jar <kvhome>/lib/kvstore.jar runadmin -port <port> -host <host>
kv-> ddl add-schema -file my_schema.avsc

Note that when adding schema to the store, some error checking is performed to ensure that the schema is correctly formed. Errors are problems that must be addressed before the schema can be added to the store. Warnings are problems that should be addressed, but are not so serious that the CLI refuses to add the schema. However, to add schema with Warnings, you must use the -force switch.

If you see any Errors or Warnings when you add schema to your store, you should discuss the problem with your development team so as to decide what to do about it.

Changing Schema

To change (evolve) existing schema, use the -evolve flag:

kv-> ddl add-schema -file my_schema.avsc -evolve 

Note that when changing schema in the store, some error checking is performed to ensure that schema evolution can be performed correctly. This error checking consists of comparing the new schema to all currently enabled versions of that schema.

This error checking can result in either Errors or Warnings. Errors are fatal problems that must be addressed before the modified schema can be added to the store. Errors represent situations where data written with an old version of the schema cannot be read by clients using a new version of the schema.

Warnings are problems that can be avoided using a a two-phase upgrade process. In a two-phase upgrade, all clients begin using the schema only for reading in phase I (the old schema is still used for writing), and then use the new schema for both reading and writing in phase II. Phase II may not be begun until phase I is complete; that is, no client may use the new schema for writing until all clients are using it for reading.

If you see any Errors or Warnings when you attempt to evolve schema in your store, you should discuss the problem with your development team so as to decide what to do about it.

Disabling and Enabling Schema

You cannot delete schema, but you can disable it:

kv-> ddl disable-schema -name avro.MyInfo.1 

To enable schema that has been disabled:

kv-> ddl enable-schema -name avro.MyInfo.1 

Showing Schema

To see all the schemas currently enabled in your store:

kv-> show schemas 

To see all schemas, including those which are currently disabled:

kv-> show schemas -disabled