When you first begin developing with Couchbase SDKs it is useful to know you can also create a telnet connection to the Couchbase Server. Once you create the connection, you can also experiment with simple gets and sets, to check to see if your SDK-level operations are actually working. When you telnet to Couchbase Server, you can perform retrieves and writes for a specific key.

To connect Couchbase Server via telnet, provide the host and port where it is located. The default bucket created on the Couchbase Server is on port 11211 for purposes of telnet. This does not require any authentication:

telnet localhost 11211

Note that when we telnet to port 11211 this is connecting to the default bucket at Couchbase Server. There are some cases that you may need to telnet to another port for instance if you are using moxi, or if you want to connect to a different bucket. After you successfully connect, you can enter commands at the telnet prompt. In the example that follows we set a key/value pair via the telnet session.

set name1 0 0 5
     karen

In this example we provide they key as ‘name1’, the flags as 0, TTL as 0, and the length of value to be set as 5 characters, respectively. After we return the set command via telnet, we can enter the actual value, which is ‘karen’ in this case. After Couchbase Server successfully stores the key/value, it will return STORED via telnet. The next examples demonstrate use of get and delete via telnet:

get name2
     VALUE name2 0 3
     ari
     END

Couchbase Server will return the value followed by an END statement. Notice that TTL is not returned in this case. When you delete a value, Couchbase Server will respond via telnet with DELETED if it successfully removes the item, and if is unsuccessful it will return NOT_FOUND:

delete name3
    DELETED
    delete name3
    NOT_FOUND

For this next example we demonstrate adding a record via telnet. This shows the general distinction between adding and setting a record. If a given key already exists, setting a record will overwrite it; if you try to add the record, Couchbase Server will return an error and preserve the existing record:

add name1 0 0 4
      erin
      STORED
      add name1 0 0 2
      ed
      NOT_STORED

In this case we first add a new key/value of name1/erin via telnet and received the message STORED from Couchbase Server. When we attempt to add the same key with a new value, Couchbase Server returns NOT_STORED via telnet. This helps provide some form of consistency and atomicity for the record when you use add and it fails for an existing key. In order to change the value of an existing key, we need to use the replace method.

To update a value via telnet, you use the replace command with the original key:

set sue 0 0 2
    ok
    STORED
    replace sue 0 0 3
    new
    STORED
    get sue
    VALUE sue 0 3
    new
    END

In the first three lines of the session, we set the new key ‘sue’ with 0 as flags, 0 as TTL, a value ‘ok’ of length 2. Couchbase sets the new record successfully and returns STORED. Then we replace the key sue with a new value of length 3, ‘new’. After the new value is successfully stored, we get it and the record Couchbase retrieves reflects this change. Notice when you replace a key, you can also update the flags and TTL should you choose to do so.

This next example demonstrates a check and set command at the telnet prompt. For check and set use the cas command and provide any new flags, expiration, new length, and cas value. We can retrieve the cas value for a key using the gets command:

set record1 0 0 4
      sara
      STORED
      gets record1
      VALUE record1 0 4 10
      sara
      END
      cas record1 0 0 7 10
      maybell
      STORED

In this example we set record1 to have 0 flags, 0 expiration, and a length of 4 characters. We set the value to the name ‘sara’. When Couchbase Server successfully stores the record it automatically creates a cas value, which we retrieve with gets. The last number returned by gets in the telnet session is the cas value. In this next step, we perform a check and set with the record1 key with no flags, no expiration, seven characters and the value ‘maybell.’

cas record1 0 0 7 10
      maybell
      STORED

When the cas command succeeds, Couchbase server updates the cas value for record1. If you attempt to check and set the record with the wrong cas value, Couchbase Server will return the error ‘EXISTS’ to the telnet session:

cas record1 0 0 3 10
      sue
      EXISTS

For more information about using telnet with the Couchbase Server, especially for server statistics and performance, see Testing Couchbase Server.