Storine v0.3.0

Clients

Clients

Official clients for eight languages share one API, need only their standard library, apply every write at most once, and follow a cluster's leader on their own.

LanguageRequiresMoney typePage
Python3.8decimal.DecimalPython
TypeScript, JavaScriptNode.js 18DecimalTypeScript
Go1.21storine.DecimalGo
Java17BigDecimalJava
C#.NET 8decimalC#
Rust1.70; 1.82 for TLS (the tls feature)storine::DecimalRust
PHP8.1Storine\DecimalPHP
Ruby3.2, with the bigdecimal gemStorine::DecimalRuby

These clients work with documents and are not ORMs. To use an ORM (SQLAlchemy, Django, Prisma, TypeORM, Sequelize, Drizzle, GORM, Hibernate, Entity Framework Core, Eloquent, ActiveRecord), go through the SQL gateway: see using an ORM.

Installing#

The clients are installed from the repository; they are not on package registries yet. Each client's page has its install command, and so does the quick start.

One API#

Every client uses the same words, in its language's style:

AreaOperations
Connectingconnect(url, options), collection(name), transaction(), collections(), close()
Writingput, insert, replace, update, delete, with if_version
Field operationsset, unset, add(path, amount).min(...).max(...), append
Readingget, get with fields, read_bytes, stream_bytes
Queryingfind, first, count, scan, nearest
Filterseq, ne, lt, le, gt, ge, between, in, prefix, contains, exists, missing, key_prefix, and, or, not
Indexescreate_index, drop_index, create_vector_index, drop_vector_index, vector_indexes, info, drop
Bulk importsreserve(count): room for that many more documents first, so the import doesn't pause while the index grows (admin token)
Analyticsaggregate, scan_columns, enable_columnar, disable_columnar

The guides (documents, queries, indexes, analytics) explain each one with Python examples.

Connection strings#

storine://[token@]host:port[,host:port...][?timeout_ms=5000&follower_reads=1]
  • Several hosts are a cluster's seeds. The client finds the leader.
  • storines:// connects with TLS. tls_ca names the PEM certificates to trust (giving it also turns TLS on), and tls_server_name the name the certificate must carry. Both may be options or query parameters.
  • .NET on Windows cannot use TLS, as its TLS stack lacks Ed25519.

What every client does for you#

  • A connection pool, safe to share between threads or tasks.
  • Authentication right after connecting, when a token is given.
  • At-most-once writes. Each logical write gets a random request id, reused on every retry after a timeout, a reconnect, CommitUnknown or a leader change. The server applies an id at most once within 24 hours.
  • Failover. On NotLeader it retries on the leader; when a server is unreachable it tries another seed.
  • Exact numbers. Decimals map to the language's exact decimal type, never to a float.
  • Backoff on Overloaded for analytic queries.

How they are tested#

All eight pass the same byte-for-byte protocol vectors, and the same end-to-end suite against a real server: standalone, as a 3-node cluster with its leader killed, and over TLS. The release checks run every suite against a single server and against a range cluster.

Writing a client for another language#

Implement sections 3 to 6 of the wire protocol, make every vector pass, then port an existing client's end-to-end suite. See writing a client.