Cassandra CREATE KEYSPACE Guide in cqlsh and DbSchema

Every table inherits the replication of the keyspace that holds it, which makes CREATE KEYSPACE a durability decision rather than a naming one. The statement takes one mandatory option, replication, and one that defaults to true, durable_writes. For how many keyspaces to create, Cassandra 5.0 gives a good general rule of one keyspace per application, and notes that a cluster commonly defines only one for an active application.

The name itself has two constraints worth knowing before you type it. A keyspace name is limited to 48 characters and may hold only alphanumeric characters and underscores. It is also case-insensitive, so myKeyspace and mykeyspace are the same keyspace unless you wrap the name in double quotes.

What a keyspace controls

Two options, and everything else about the keyspace follows from them. The replication property is mandatory and must contain the class sub-option that names the replication strategy; the remaining sub-options depend on which strategy you chose. durable_writes decides whether updates to this keyspace go through the commit log, and Cassandra 5.0 attaches an unusually blunt note to it: disable this option at your own risk.

Running the statements below needs a Cassandra cluster, permission to create schema objects, either cqlsh or DbSchema connected to it, and the real datacenter names if you are going to use NetworkTopologyStrategy. nodetool status prints them.

Replication strategies

Cassandra supports two replication strategy classes out of the box, and the documentation is direct about which one belongs where.

SimpleStrategy

SimpleStrategy defines a replication factor for data to be spread across the entire cluster, and it takes a single mandatory argument, replication_factor, which is the number of replicas to store per range.

{'class': 'SimpleStrategy', 'replication_factor': 1}

Cassandra 5.0 states that this is generally not a wise choice for production, as it does not respect datacenter layouts and can lead to wildly varying query latency, and that production should use NetworkTopologyStrategy instead. Where the cluster has one datacenter, there is no layout for it to ignore, which is why it survives on a laptop.

NetworkTopologyStrategy

NetworkTopologyStrategy is described as the production-ready strategy, and it sets the replication factor independently for each datacenter. Its sub-options are key-value pairs whose key is a datacenter name and whose value is that datacenter's replication factor.

{'class': 'NetworkTopologyStrategy', 'DC1': 3, 'DC2': 3}

It also accepts a plain replication_factor, which Cassandra expands across the datacenters it knows about. That expansion is shown below with its output, because it is the part people are surprised by later.

Transient replication, where it has been enabled on the cluster, is expressed by writing the factor as '<total_replicas>/<transient_replicas>', so 'DC1': '3/1' means three replicas in DC1, one of them transient.

Replication factor and durable writes

The replication factor is the number of copies Cassandra keeps of each token range, per datacenter under NetworkTopologyStrategy and across the whole cluster under SimpleStrategy. Changing it later with ALTER KEYSPACE has one behavior worth knowing before you rely on it: when you alter a keyspace and change the replication_factor, auto-expansion only adds new datacenters, for safety. It does not alter existing datacenters and it does not remove any, even ones that have left the cluster.

Removing a datacenter therefore takes an explicit zero rather than an omission:

CREATE KEYSPACE excalibur
WITH replication = {'class': 'NetworkTopologyStrategy', 'replication_factor': 3, 'DC2': 0};

DESCRIBE KEYSPACE excalibur;

On a cluster with datacenters DC1 and DC2, the documentation shows DC2 dropping out of the stored definition:

CREATE KEYSPACE excalibur WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1': '3'} AND durable_writes = true;

durable_writes stays out of most conversations because its default is true and that is the right value. Setting it to false skips the commit log for this keyspace, which is the risk the documentation tells you to weigh before you take it.

Design and visualize
your database schema

Edit referenced records
in related tables

Query your data
visually too

Reuse the SQL
generated

Free Download

Create a keyspace in cqlsh

For a local development cluster, one copy of everything on one node:

CREATE KEYSPACE IF NOT EXISTS app_lab
WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};

For a production deployment in a single datacenter, and then across two:

CREATE KEYSPACE IF NOT EXISTS ecommerce
WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1': 3}
AND durable_writes = true;

CREATE KEYSPACE IF NOT EXISTS ecommerce
WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1': 3, 'DC2': 3}
AND durable_writes = true;

Creating a keyspace that already exists returns an error, and IF NOT EXISTS turns that into a no-op, which is what makes the second of those statements harmless in a script that has already run once. A DDL statement that succeeds prints nothing in cqlsh.

Reading the definition back is how you confirm which datacenters Cassandra actually recorded:

DESCRIBE KEYSPACE ecommerce;

CREATE KEYSPACE ecommerce WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1': '3', 'DC2': '3'} AND durable_writes = true;

Write the same keyspace with a bare 'replication_factor': 3 instead of naming the datacenters, and on a cluster with DC1 and DC2 that DESCRIBE returns the identical line: Cassandra expanded the factor to both datacenters it knows.

Create a keyspace in DbSchema

DbSchema reaches Cassandra through its own open-source JDBC driver, com.dbschema.Cassandra.JdbcDriver, whose URL carries the datacenter name from nodetool status after the keyspace. The Cassandra connection page has the URL format.

1. In DbSchema, choose Connect to Database and pick Cassandra, and DbSchema opens the Connection Dialog.
2. Set Connection Mode to Edit the JDBC URL Manually and paste the full URL, since the datacenter parameter has no field of its own in the Standard mode. Click Test Connection, then Connect.
3. Open the DbSchema SQL Editor from the Editors menu, paste the CREATE KEYSPACE statement and click Execute Query.
4. Save the design as a .dbs model file so the keyspace and the tables inside it are documented in one place, in the repository next to the application code.

Step 3 changes the cluster. Step 4 writes a file on your computer and touches no database, and saving the model to a file is in the DbSchema Pro edition.

Common mistakes

SimpleStrategy in production is the first, and it is the one the Cassandra documentation names itself: it does not respect datacenter layouts, and the symptom it gives you is query latency that varies wildly.

The second is expecting ALTER KEYSPACE to tidy up after a decommissioned datacenter. Auto-expansion adds datacenters and never removes them, so a datacenter that has left the cluster stays in the replication map until somebody sets it to zero.

The third is a keyspace name that runs past 48 characters or picks up a hyphen, and the fourth is one keyspace per microservice where the application is a single application. One keyspace per application is the documented rule, and every extra keyspace is another replication map to keep in step with the others.

A replication map that lives only in one person's shell history is a decision nobody can review. Download DbSchema at https://dbschema.com/download.html, connect to the cluster with the datacenter name nodetool status gives you, run the CREATE KEYSPACE in the SQL Editor, and save the model to a .dbs file so the replication settings sit in the repository with the schema; saving the model is in the Pro edition. The next step is the tables, and How to Create a Table in Cassandra covers the primary key decisions behind them.