BlueTusk documentation

BlueTusk is a PostgreSQL-native .NET platform built as a set of independently versioned product families. The documentation follows the same boundaries as the code: start with the provider, add EF Core or an extension when the application needs it, and adopt Streams, Sync, Live, Control Plane or Continuous Graph only when their delivery contracts match the workload.

The stable 1.0.0 line and public 1.1.0-rc.1 train each contain 62 NuGet packages and three npm packages. The RC was published from exact commit 2e735ed46aec11d5009158a00ca7b862f9ec12af, and registry availability plus clean package-consumer installs were verified. Read the 1.1 RC release record, installation guide, and support matrix before choosing a channel. Stable 1.1.0 remains gated on PostgreSQL 19 GA and the exact stable-candidate endurance, performance, security, and external-acceptance record.

Choose a path

You want to…	Start here	Then read
Install published packages	Installation and package selection	Quickstart and 1.1 RC release record
Evaluate BlueTusk from source	Quickstart	Core concepts
Build with ADO.NET	Provider guide	Compatibility matrix and dependency injection
Build with EF Core	EF Core guide	Specification coverage
Move committed changes	Real-time platform	Streams and operations
Synchronize destinations	Sync	Delivery contracts
Deliver authorized live data	Live	Security
Use PostgreSQL extensions	Extensions	Type system
Query or maintain graph data	SQL/PGQ	Continuous Graph
Operate a deployment	Production checklist	Deployment, troubleshooting, and production observability
Contribute	Repository layout	Testing
Prepare a release	Release process	Operational approval evidence and independent review handoff

Product families

Provider

The Provider family owns the PostgreSQL wire path: transport, protocol, authentication, pooling, ADO.NET, types, COPY, notifications, large objects, pipeline mode and replication. It does not wrap Npgsql at runtime.

Read:

• ADO.NET provider
• Supported and intentionally excluded ADO.NET behavior
• Authentication and cloud identity
• Pooling, multi-host routing and bounded multiplexing
• Type system, COPY and replication

EF Core

The EF Core family adds PostgreSQL-native mappings, translations, migrations, scaffolding and design-time tooling on top of the provider-owned data source. It consumes an internal Provider SPI rather than taking ownership of the wire stack.

Read:

• EF Core provider
• Official relational specification coverage
• Internal EF↔Data boundary

Streams, Sync and Live

The real-time families share source identity, transaction and checkpoint concepts but deliberately keep different delivery semantics:

• Streams turns logical replication into acknowledged committed transactions and owns snapshot bootstrap, state stores and durable relay.
• Sync applies versioned transforms to PostgreSQL, Redis, NATS and OpenSearch destinations, with quarantine, reconciliation and rebuilds.
• Live performs authorized re-query and delivery over server-sent events, SignalR and gRPC/browser client surfaces.

Read:

• Platform contracts
• Streams, Sync and Live
• Production operations
• Streams 72-hour and Sync 24-hour evidence contracts

Control Plane and Continuous Graph

Control Plane manages deployment state, operational queries, reconciliation, auditing and the dashboard boundary. Continuous Graph consumes acknowledged changes into checkpointed graph projections for workloads such as fraud and network topology.

Read:

• Control Plane
• Continuous Graph
• Managed-hosting reconciliation decision
• Incremental graph maintenance decision

Architectural foundations

BlueTusk uses a strict downward dependency direction:

Application
  ├─ EF Core / extensions
  ├─ ADO.NET Provider
  ├─ Client / protocol / transport
  └─ PostgreSQL

Logical replication
  └─ Streams
      ├─ Sync
      ├─ Live
      ├─ Control Plane
      └─ Continuous Graph

The important cross-cutting rules are:

1. PostgreSQL behavior is the specification.
2. Capability discovery is stronger than version-string inference.
3. Every untrusted length, count and collection is bounded before allocation.
4. Logical connection ownership is distinct from physical pooled-session ownership.
5. Acknowledgement, checkpointing and destination application are separate operations.
6. Public API, persisted format and package changes are mechanically checked.
7. A successful local build is evidence, not publication permission.

The architecture overview explains the layers and the architecture decisions record why the important boundaries exist.

Operations and release truth

Use these documents when the question is not “how do I call the API?”:

• Deployment and configuration
• Production checklist
• Application platform health and rollout acceptance
• Troubleshooting
• Performance engineering
• BlueTusk versus Npgsql V1 performance report
• Production observability and SLOs
• V1 production-readiness gates and exact-candidate evidence
• Canonical V1 package evidence
• V1 operational approval evidence
• Angular website production contract
• Upgrade guide
• Observability
• Security model
• Testing profiles
• Release process
• V1 hardening programme
• PostgreSQL 19 programme
• V1 application suite and RC deployment
• BlueTusk 1.1.0-rc.1 release record

Documentation contract

Repository Markdown is canonical. The Angular website transforms the selected Markdown files into searchable guides during its build and fails when generated content drifts. When behavior changes:

1. update the implementation and focused tests;
2. update the relevant public API or format baseline;
3. update the canonical Markdown guide and examples;
4. update release/readiness evidence if the claim changed; and
5. regenerate and validate the website documentation.

Examples must use parameterized SQL, explicit cancellation where useful and honest package availability. Experimental-feature boundaries, stable-publication gates and external production validation must never be collapsed into one status.