Production documentation, from first install to incident.
Choose an outcome, follow the steps, and keep the operational detail close at hand. Every guide is built from the repository source, searchable, cross-linked, and checked for drift.
From zero to an operable service.
Install the right packages
Choose stable or release candidate, install only what you need, and confirm it restores.
Installation guide 02BUILDRun the first query
Start PostgreSQL, create one shared data source, and run a safe parameterized query.
Developer quickstart 03SHIPDesign for production
Plan security, limits, monitoring, rollout, backups, and recovery before launch.
Production checklist 04OPERATEDiagnose with evidence
Follow a problem from the first connection through streaming, delivery, and recovery.
TroubleshootingOrient yourself and run the first provider sample.
BlueTusk documentation
Navigate the complete BlueTusk V1 engineering handbook by workload, product family, architecture, operations, and release responsibility.
Install BlueTusk
Choose the stable or RC channel, install the smallest NuGet/npm package set, pin exact versions, and verify the resolved dependency graph.
BlueTusk 1.1.0-rc.1 release record
Review the immutable 1.1.0-rc.1 tags, workflow runs, 65 public packages, verification record, product changes, and stable-release boundary.
Quickstart: run BlueTusk locally
Build the repository, start PostgreSQL, run the provider, register dependency injection, and choose the right next layer.
Core concepts
Learn data-source ownership, sessions, capabilities, type identity, checkpoints, source identity, and release-state vocabulary.
Architecture
Understand the layers, dependency direction, ownership, and async boundaries.
ADO.NET
Build and run the native ADO.NET provider.
BlueTusk
PostgreSQL, fully exposed to .NET.
Own every PostgreSQL data path through ADO.NET.
Authentication
Credentials, password files, TLS certificates, GSSAPI, Kerberos, and SSPI.
Cloud identity
AWS, Azure, and Google Cloud identity integration and live-test boundaries.
Dependency injection and health checks
Register one long-lived provider data source, consume DbDataSource, and design readiness checks without harming liveness.
Connection pooling
Pool sizing, reset behavior, operational signals, and PgBouncer modes.
Multi-host connections
Multi-host routing, failover, target session attributes, and recovery.
Batches
Execute ordered command batches with PostgreSQL-aware error behavior.
COPY
Text and binary COPY APIs, typed values, cancellation, and completion.
Large objects
Large-object ownership and streaming behavior.
Asynchronous notifications
LISTEN and NOTIFY lifecycle, dispatch, and connection behavior.
Sequential readers
Bounded sequential reads for large PostgreSQL values.
Schema discovery
Use GetSchema, GetColumnSchema, GetSchemaTable, restrictions, and provider-neutral catalogue metadata.
Core type mappings
Catalogue-driven PostgreSQL type mappings and extension points.
PostgreSQL pipeline mode
Pipeline groups, protocol Sync boundaries, and ordered failures.
Replication
Physical and logical replication, pgoutput, and WAL feedback.
ADO.NET V1 compatibility
This matrix is the V1 contract for provider-neutral ADO.NET consumers. A capability marked excluded fails explicitly; it is not silently approximated. The live acceptance suite is tests/BlueTusk.CompatibilityTests/Ado…
Multiplexing compatibility
BlueTusk multiplexing is an opt-in throughput path for independent, session-neutral commands created directly from a BlueTuskDataSource. It does not turn PostgreSQL sessions into logical connections and never moves an…
NativeAOT and trimming
The provider core supports trimmed and NativeAOT applications across BlueTusk.Transport, BlueTusk.Protocol, BlueTusk.Security, BlueTusk.TypeSystem, BlueTusk.Client, BlueTusk.Diagnostics, and
Protocol notes
PostgreSQL backend frames begin with a one-byte identifier followed by a big-endian 32-bit length. The length includes itself and excludes the identifier. Startup messages are exceptional: they have no identifier byte.
Protocol capture format
BlueTusk protocol captures use the .btpc extension. The format is a streamable, big-endian container intended for conformance debugging and packet-laboratory fixtures; it is not a general network-capture replacement.
Keep PostgreSQL features inside familiar EF workflows.
Move committed changes through explicit delivery contracts.
BlueTusk real-time platform
Correctness contract and independent release trains.
Real-time platform contracts
Shared delivery, checkpoint, and source identity contracts.
BlueTusk Streams
The implemented Streams kernel, transactions, failures, and performance.
Consistent snapshot bootstrap
A fenced snapshot-then-stream protocol.
PostgreSQL durable relay
Storage, backup, groups, retention, and relay fan-out.
Streams checkpoint and lease stores
State-store contracts and supported persistence behavior.
Hosting and observability
Hosted services, health checks, metrics, and operational behavior.
Streams release endurance
The 72-hour endurance gate and evidence contract.
BlueTusk Sync
Versioned destination synchronization, quarantine, reconciliation, and rebuilds.
Sync release endurance
The 24-hour Sync release gate and evidence contract.
BlueTusk Live
Authorized live delivery, replay, subscriptions, transports, and browser clients.
BlueTusk Control Plane and Dashboard
Operational queries, dashboard boundaries, authorization, and audit.
Real-time operations
Operate source identity, checkpoints, relay storage, destinations, failover, reconciliation, rebuilds, and endurance evidence.
BlueTusk Continuous Graph
Checkpointed graph projections for fraud and network workloads.
Control Plane API and format compatibility
The Control Plane V1 candidate has two independently enforced compatibility surfaces:
BlueTusk Control Plane 0.1.0-preview.1 release notes
This preview contains the independently versioned BlueTusk.ControlPlane and BlueTusk.Dashboard packages. Its implementation and compatibility gates are complete. The product-family manifest remains non-publishable unt…
BlueTusk Control Plane 1.0.0 release record
Status: published on 2026-08-23 from control-plane-v1.0.0 at release commit 7380d7b028c72b2aae348b778711d104d022a3f8.
Live public API compatibility
The current Live 1.0 candidate surface is locked by two independent gates:
Live format compatibility
Every durable or externally visible Live format is registered in eng/live-formats.json. A test binds the registry to implementation constants, the versioned protobuf package, and named compatibility evidence.
BlueTusk Live 0.1.0-preview.1
This is the first packaging-ready BlueTusk Live preview. It provides trusted, authorised, resumable real-time queries over BlueTusk Streams while preserving PostgreSQL/EF as the source of every client-visible row.
BlueTusk Live 1.0.0 release record
Status: published on 2026-08-23 from live-v1.0.0 at release commit 7380d7b028c72b2aae348b778711d104d022a3f8.
Real-time platform delivery plan
The implementation uses two-week iterations and lands only passing vertical slices. Each slice updates documentation and is committed and pushed on an AI-neutral feature/... branch.
Streams public API compatibility
The current Streams 1.0 candidate surface is locked by two independent gates:
Aspire integration
BlueTusk.Streams.Aspire wires Streams workers to Aspire connection-string resources without resolving or copying secrets in the AppHost. It targets the Aspire application model and supports both relay and explicit dir…
Streams validation and provisioning CLI
BlueTusk.Streams.Tool provides the bluetusk-streams .NET tool. It validates the PostgreSQL version, wallevel, publications, table selection, logical slot, source/control isolation, relay-schema exclusion, and canonica…
CloudEvents
BlueTusk.Streams.CloudEvents writes CloudEvents 1.0 structured JSON without changing the source transaction delivery unit. One committed PostgreSQL transaction becomes one event with one versioned BlueTusk transaction…
Streams format compatibility
BlueTusk records every durable or externally visible Streams format in eng/streams-formats.json. A test binds that registry to the constants used by the implementation and verifies that its named compatibility evidenc…
Prepared and two-phase transactions
Prepared-transaction delivery is an opt-in Streams preview feature. The default PreparedTransactionMode.Fail behavior rejects every two-phase pgoutput message before changing assembler state. Enable PreparedTransactio…
BlueTusk Streams 0.1.0-preview.1
This is the first packaging-ready Streams preview. It establishes the public transaction, checkpoint, lease, snapshot, typed-mapping, hosting, and relay contracts needed by the later Sync and Live product families.
BlueTusk Streams 1.0.0 release record
Status: published on 2026-08-23 from streams-v1.0.0 at release commit 7380d7b028c72b2aae348b778711d104d022a3f8.
Snapshot-then-stream sample
The BlueTusk.Samples.Streams worker demonstrates the complete first-run path: an exported PostgreSQL snapshot, bounded binary COPY batches, transition to the matching pgoutput position, and transaction acknowledgement…
Typed change mappings
Streams always retains the dynamic ChangeRow and its explicit per-column states. Typed mapping is an optional projection over that lossless row; it does not replace it and never manufactures a complete CLR object from…
Sync public API compatibility
The current Sync 1.0 candidate surface is locked by two independent gates:
Sync format compatibility
Every durable or externally visible Sync format is registered in eng/sync-formats.json. A test binds the registry to implementation constants and named compatibility evidence.
BlueTusk Sync 1.0.0 release record
Status: published on 2026-08-23 from sync-v1.0.0 at release commit 7380d7b028c72b2aae348b778711d104d022a3f8.
Compose optional PostgreSQL-native capabilities.
Query and project connected data.
PostgreSQL 19 SQL/PGQ V1 candidate
PostgreSQL 19 SQL/PGQ, discovery, migrations, and typed EF queries.
ContinuousGraph public API compatibility
The immutable 1.0 surface and additive 1.1 candidate surface are locked by two independent gates:
BlueTusk Continuous Graph 0.1.0-preview.1
This is the first package-verified Continuous Graph preview candidate. It builds trusted, registered PostgreSQL 19 SQL/PGQ plans on the existing BlueTusk property-graph, Live, and Control Plane foundations without exp…
BlueTusk ContinuousGraph 1.0.0 release record
Status: published on 2026-08-23 from continuous-graph-v1.0.0 at release commit 7380d7b028c72b2aae348b778711d104d022a3f8.
Understand ownership, dependency rules, decisions, and performance constraints.
Allocation discipline
BlueTusk treats low allocation as a measured engineering constraint, not as a blanket “allocation-free” claim. Returned strings, arrays, records, and buffered large fields own managed memory by design. The provider in…
ADR 0001: Enforce layered dependency direction
- Status: Accepted - Date: 2026-07-21
ADR 0002: Treat PostgreSQL as the specification
- Status: Accepted - Date: 2026-07-21
ADR 0003: Discover types from catalogues
- Status: Accepted - Date: 2026-07-21
ADR 0004: Test protocol framing independently
- Status: Accepted - Date: 2026-07-21
ADR 0005: Separate PostgreSQL pipeline mode from transport pipelines
- Status: Accepted; retain the ArrayPool/Span/Memory transport - Date: 2026-08-01
ADR 0006: Make Streams the application CDC boundary
- Status: Accepted - Date: 2026-08-03
ADR 0007: Persist checkpoints before replication feedback
- Status: Accepted - Date: 2026-08-03
ADR 0008: Bootstrap with an exported consistent snapshot
- Status: Accepted - Date: 2026-08-03
ADR 0009: Bound transaction memory and spill to a versioned spool
- Status: Accepted - Date: 2026-08-03
ADR 0010: Use PostgreSQL for the first durable relay
- Status: Accepted - Date: 2026-08-03
ADR 0011: Treat CDC as Live invalidation, not client-visible truth
- Status: Accepted - Date: 2026-08-03
ADR 0012: Keep source transactions as the Sync delivery unit
- Status: Accepted - Date: 2026-08-03
ADR 0013: Use bounded, session-neutral statement multiplexing
- Status: Accepted - Date: 2026-08-04
ADR 0014: managed hosting uses fenced desired-state reconciliation
- Status: accepted - Date: 2026-08-03
ADR 0015: Gate client-authored queries with database capabilities
- Status: Accepted - Date: 2026-08-03
ADR 0016: Use bounded incremental graph maintenance with authoritative repair
- Status: Accepted - Date: 2026-08-04; extended for 1.1 on 2026-08-28
ADR 0017: Keep the EF-to-Data provider SPI internal and minimal
- Status: accepted - Date: 2026-08-04
Transport contract
BlueTusk.Transport owns byte movement and connection establishment. It has no PostgreSQL authentication, SQL, type-system, pooling, or ADO.NET knowledge.
Build, test, secure, and evolve the repository.
Production checklist
Take a BlueTusk application from package selection to a secure, bounded, observable, recoverable, and operator-owned production deployment.
Deployment and configuration
Design production topology, security roles, pool capacity, migrations, rolling deployment, and real-time persistence.
Diagnostics and observability
Metrics, traces, and slow-command events.
Troubleshooting
Diagnose connection, TLS, authentication, pool, command, type, EF, replication, and destination failures from the lowest boundary upward.
Security review
Threat model, closed findings, application boundaries, and checks.
Performance engineering
Measure pool pressure, command paths, multiplexing, allocation, readers, COPY, and real-time throughput with reproducible evidence.
BlueTusk V1 performance report: BlueTusk versus Npgsql
Review the V1 BlueTusk versus Npgsql benchmark matrix, tail latency, allocation, saturated pooling evidence, methodology, and integrity hashes.
Runtime release readiness
Executable gates for provider, EF, extensions, artifacts, and documentation.
Upgrade guide
Upgrade product families, EF Core, extensions, PostgreSQL, formats, mappings, and rolling deployments with a recoverable plan.
API compatibility
Public API baselines and compatibility expectations.
Testing
Unit, live, topology, security, stress, and endurance test profiles.
Repository and solution layout
Repository projects and dependency boundaries.
Roadmap
Provider, EF, graph, extension, real-time, and 1.0 milestones.
Contributing to BlueTusk
Issue-first contribution flow, tests, compatibility, and secrets policy.
Security policy
Report vulnerabilities privately through the repository hosting platform.
Compatibility and versioning
PostgreSQL 15–18 are the released-server compatibility baseline. PostgreSQL 19 is currently exercised with the pinned postgres:19beta3-alpine image and is explicitly beta-sensitive: SQL/PGQ syntax, catalogues, and cap…
Public API naming
BlueTusk names should read naturally after the caller has already selected a BlueTusk package or entered a PostgreSQL-specific domain. Repeating the product name in every fluent member obscures the operation without a…
Specification completion audit
This record maps the original BlueTusk product specification and the subsequent architecture-gap review to concrete repository evidence. “Complete” here means the engineering surface is implemented, documented, and co…
Parser reliability and coverage-guided fuzzing
BlueTusk fuzzes every externally controlled parser boundary used by the V1 product chain:
V1 hardening programme
The Provider → Streams → Sync → Live → Continuous Graph development chain is feature-complete for V1. Version 1.0.0 was published on 2026-08-23 under the documented repository-owner exception.
Application platform health and rollout acceptance
BlueTusk's three Clean Architecture reference applications are production-shaped workloads, but Kubernetes desired state is not proof that a workload is actually running. A stale Pod object can continue to show Runnin…
V1 operational approval evidence
BlueTusk treats operational acceptance as measured release evidence, not a collection of unchecked signatures. The protected candidate workflow requires ten JSON records for one immutable commit. Every record is SHA-2…
Endurance disturbance evidence
V1 requires more than a long-running green test process. The exact 72-hour Streams run and exact 24-hour Sync run must each survive the seven operational disturbances in eng/v1-endurance-disturbance-contract.json. Tha…
V1 fuzz-finding review handoff
This record preserves the release-relevant outcome of the 2026-08-04 coverage-guided run without placing triggering inputs in public documentation. It is a defensive review handoff, not approval to publish.
Production observability and SLOs
BlueTusk V1 exposes one OpenTelemetry meter per product area and treats telemetry as a versioned operational contract. Metrics are low-overhead when no listener is attached, exporter-neutral, and deliberately avoid SQ…
Canonical V1 package evidence
The manual build.yml candidate run produces one canonical, evidence-only package set for all six BlueTusk product families. The set is the package input to release review. It is not a publication path and receives no…
BlueTusk 1.1 performance leadership report
Public RC basis: 2e735ed46aec11d5009158a00ca7b862f9ec12af
V1 production readiness
BlueTusk has two deliberately different readiness states:
Website production contract
The Angular website is part of the V1 release evidence surface. It explains product maturity, publishes the source-synchronized handbook, and exposes the current benchmark, compatibility and operational records. A suc…
PostgreSQL 19 compatibility programme
PostgreSQL 19 is currently at Beta 3. BlueTusk treats it as pre-GA evidence, not a production dependency. The official project warns that beta features and behaviour may still change and does not recommend beta releas…
BlueTusk Provider 1.0.0 release record
Status: published on 2026-08-23 from provider-v1.0.0 at release commit 7380d7b028c72b2aae348b778711d104d022a3f8.
Release process
BlueTusk release publication is fail closed. A successful build or candidate package is evidence, not permission to publish.
Independent V1 release review handoff
Use one copy of this record for each exact candidate commit. Reviewers must be independent of the person who prepared the release. Blank, inherited or ancestor-commit evidence does not pass.
BlueTusk 1.0.0 publication record
Status: published on 2026-08-23.
BlueTusk 1.1.0 coordinated release line
BlueTusk 1.1.0 is one coordinated, API-compatible performance release across all six product families and the three Live browser clients. The existing 1.0 artifacts are immutable; 1.1 adds optimised paths and observab…
V1 application suite and RC deployment
BlueTusk V1 is exercised by three independently deployable applications in applications/BlueTusk.Applications.slnx:
V1 release readiness
BlueTusk 1.0.0 was published on 2026-08-23 under the explicit repository-owner decision recorded in the V1 publication record. Publication did