FastGuid 1.4.0

FastGuid

by Stan Drapkin

10 times faster than Guid.NewGuid()

• High-performance, cryptographically strong GUID generation
• Database-optimized GUIDs for SQL Server and PostgreSQL
• Fast random byte filling
• Fastest .NET random string generation

Install

dotnet add package FastGuid

Static APIs for GUIDs and random data generation

• Guid FastGuid.NewGuid()
  • Returns a cryptographically random GUID.
  • ~10x (900%) faster than Guid.NewGuid().
• FastGuid.Fill(Span<byte> data)
  • Fills a span with cryptographically strong random bytes.
  • ~1.5x (50%) to 9x (800%) faster for <512 bytes, otherwise calls RandomNumberGenerator.Fill()

Static APIs for SQL Server- and PostgreSQL-optimized GUIDs

• Guid FastGuid.NewSqlServerGuid()

  • Returns a new Guid optimized for use as a SQL Server clustered key.
  • Guid structure is [8 random bytes] [8 bytes of SQL-Server-ordered DateTime.UtcNow]
  • Each Guid is sequential across 100-nanosecond UtcNow precision limits.
  • 64-bit cryptographic randomness adds uniqueness for timestamp collisions and provides reasonable unguessability and protection against online brute-force attacks.

• Guid FastGuid.NewPostgreSqlGuid()

  • Returns a new Guid optimized for use as a PostgreSQL primary key or index.
  • Guid structure is [8 bytes of PostgreSQL-ordered DateTime.UtcNow] [8 random bytes]
  • Each Guid is sequential across 100-nanosecond UtcNow precision limits.
  • 64-bit cryptographic randomness adds uniqueness for timestamp collisions and provides reasonable unguessability and protection against online brute-force attacks.

• Helper methods for Guids generated by NewSqlServerGuid():

  • DateTime FastGuid.SqlServer.GetTimestamp(Guid guid)
    • Extracts SqlServer Guid creation timestamp (UTC). Full DateTime.UtcNow precision.
  • Guid FastGuid.SqlServer.MinGuidForTimestamp(DateTime timestampUtc)
  • Guid FastGuid.SqlServer.MaxGuidForTimestamp(DateTime timestampUtc)
    • Return the smallest/largest Guid for a given timestamp (useful for time-based SQL-Server range searches).

• Helper methods for Guids generated by NewPostgreSqlGuid():

  • DateTime FastGuid.PostgreSql.GetTimestamp(Guid guid)
    • Extracts PostgreSQL Guid creation timestamp (UTC). Full DateTime.UtcNow precision.
  • Guid FastGuid.PostgreSql.MinGuidForTimestamp(DateTime timestampUtc)
  • Guid FastGuid.PostgreSql.MaxGuidForTimestamp(DateTime timestampUtc)
    • Return the smallest/largest Guid for a given timestamp (useful for time-based PostgreSQL range searches).

Static APIs for fast random string generation ^(new)

• string FastGuid.StringGen.Text16(int length)
  • Generates a random string using the Base16 (hex) alphabet.
• string FastGuid.StringGen.Text32(int length)
  • Generates a random string using the Base32 alphabet (RFC 4648).
• string FastGuid.StringGen.Text64(int length)
  • Generates a random string using the Base64 alphabet (RFC 4648).
• string FastGuid.StringGen.Text64Url(int length)
  • Generates a random string using the Base64Url alphabet (RFC 4648, URL-safe).
• All methods use cryptographically strong randomness and are suitable for passwords, tokens, keys, and identifiers.

Fast GUID-to-string and string-to-GUID conversion ^(new)

New fast extension methods for efficient conversion between GUIDs and compact Base64Url strings:

• string Guid.ToBase64Url()

  • Converts a Guid to a 22-character Base64Url string (URL-safe, no padding).
  • Useful for compact GUID-as-string identifiers in URLs, tokens, or text fields.

• Guid string.FromBase64Url()

  • Converts a 22-character Base64Url string back to a Guid.
  • Throws ArgumentException if the input is invalid.

• bool GuidExtensions.TryFromBase64Url(ReadOnlySpan<char> base64Url, out Guid guid)

  • Tries to convert a Base64Url string to a Guid.
  • Returns true if successful, false otherwise (never throws).

API Summary

Usage

Replace all calls to Guid.NewGuid() with FastGuid.NewGuid()

..from this:

Guid guid = Guid.NewGuid(); // your current code

..to this:

// using SecurityDriven;
Guid guid = FastGuid.NewGuid(); // 10x faster

• Thread-safe
• 128 bits of cryptographically strong randomness

Switch from this:

Span<byte> key = stackalloc byte[32];
RandomNumberGenerator.Fill(key); // 145 nanoseconds

..to this:

Span<byte> key = stackalloc byte[32];
FastGuid.Fill(key); // 20 nanoseconds (7x faster)

Benchmark #1:

public class Bench
{
	[Benchmark(Baseline = true)]
	public void FastGuid_NewGuid() // 12 calls
	{
		FastGuid.NewGuid(); FastGuid.NewGuid(); FastGuid.NewGuid(); FastGuid.NewGuid();
		FastGuid.NewGuid(); FastGuid.NewGuid(); FastGuid.NewGuid(); FastGuid.NewGuid();
		FastGuid.NewGuid(); FastGuid.NewGuid(); FastGuid.NewGuid(); FastGuid.NewGuid();
	}

	[Benchmark]
	public void Guid_NewGuid() // 12 calls
	{
		Guid.NewGuid(); Guid.NewGuid(); Guid.NewGuid(); Guid.NewGuid();
		Guid.NewGuid(); Guid.NewGuid(); Guid.NewGuid(); Guid.NewGuid();
		Guid.NewGuid(); Guid.NewGuid(); Guid.NewGuid(); Guid.NewGuid();
	}
}//class Bench

BenchmarkDotNet=v0.13.2, OS=Windows 10 (10.0.19045.2364)
Intel Core i7-10510U CPU 1.80GHz, 1 CPU, 8 logical and 4 physical cores
.NET SDK=7.0.101
  [Host] : .NET 7.0.1 (7.0.122.56804), X64 RyuJIT AVX2

Benchmark #2:

static Guid Guid_NewGuid() => Guid.NewGuid();
static Guid Guid_CreateVersion7() => Guid.CreateVersion7();
static Guid FastGuid_NewGuid() => SecurityDriven.FastGuid.NewGuid();
static Guid FastGuid_NewSqlServerGuid() => SecurityDriven.FastGuid.NewSqlServerGuid();
static Guid FastGuid_NewPostgreSqlGuid() => SecurityDriven.FastGuid.NewPostgreSqlGuid();

BenchmarkDotNet v0.13.8, Windows 10 (10.0.19045.5371/22H2/2022Update)
Intel Core i7-10510U CPU 1.80GHz, 1 CPU, 8 logical and 4 physical cores
.NET SDK 9.0.102
  [Host] : .NET 9.0.1 (9.0.124.61010), X64 RyuJIT AVX2

Example: Fast random string generation

// Generate a 16-character random hexadecimal string
string hex = FastGuid.StringGen.Text16(16); // 64 bits of entropy

// Generate a 32-character random Base32 session identifier
string sessionId = FastGuid.StringGen.Text32(32); // 160 bits of entropy

// Generate a 32-character random Base64Url token
string token = FastGuid.StringGen.Text64Url(32); // 192 bits of entropy

Benchmark #3: Fast random string generation

static Guid FastGuid_NewGuid() => FastGuid.NewGuid();
static string FastGuid_StringGen_Text16_16() => FastGuid.StringGen.Text16(16);
static string FastGuid_StringGen_Text32_32() => FastGuid.StringGen.Text32(32);
static string FastGuid_StringGen_Text64Url_32() => FastGuid.StringGen.Text64Url(32);

BenchmarkDotNet v0.13.8, Windows 10 (10.0.19045.5917/22H2/2022Update)
Intel Core i7-10510U CPU 1.80GHz, 1 CPU, 8 logical and 4 physical cores
.NET SDK 10.0.100-preview.5.25277.114
  [Host] : .NET 10.0.0 (10.0.25.27814), X64 RyuJIT AVX2

Example: Extension methods for Guid

Guid guid1 = FastGuid.NewGuid();
string guidString = guid1.ToBase64Url(); // e.g. "Q29uZGVuc2VkQmFzZTY0VXJs"
Guid guid2 = guidString.FromBase64Url(); // round-trip; throws if guid string is invalid

if (guid1 != guid2) throw new InvalidOperationException(); // not going to happen

// Exception-free parsing:
if (GuidExtensions.TryFromBase64Url(guidString, out Guid validGuid))
{
	// validGuid is valid
}